#20563: fix: skip default HEARTBEAT_OK instructions when custom prompt is set
agents
size: XS
Cluster:
Heartbeat Functionality Improvements
## Problem
When a custom heartbeat prompt is configured via `agents.defaults.heartbeat.prompt`, the system prompt still includes hardcoded HEARTBEAT_OK instructions after the custom prompt. This causes conflicting guidance.
**Before (with custom prompt):**
```
## Heartbeats
Heartbeat prompt: <CUSTOM PROMPT>
If you receive a heartbeat poll... and there is nothing that needs attention, reply exactly:
HEARTBEAT_OK <-- CONFLICTS with custom prompt!
```
## Solution
Only add the default HEARTBEAT_OK instructions when NO custom prompt is configured. Custom prompts should fully define their own heartbeat behavior.
**After (with custom prompt):**
```
## Heartbeats
Heartbeat prompt: <CUSTOM PROMPT>
```
**After (without custom prompt - default behavior):**
```
## Heartbeats
Heartbeat prompt: (configured)
If you receive a heartbeat poll... and there is nothing that needs attention, reply exactly:
HEARTBEAT_OK
```
## Use Case
This enables the "Free Mind Protocol" pattern where agents define custom heartbeat behavior that doesn't require HEARTBEAT_OK responses, allowing for more autonomous agent operation.
## Changes
- Modified `src/agents/system-prompt.ts` to conditionally add default HEARTBEAT_OK instructions only when no custom heartbeat prompt is set
## Testing
- Backward compatible: default behavior unchanged
- Custom prompts now work as expected without conflicting instructions
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Conditionally adds default HEARTBEAT_OK instructions only when no custom heartbeat prompt is configured. When `agents.defaults.heartbeat.prompt` is set, the system prompt now excludes the default HEARTBEAT_OK instructions, allowing custom prompts to define their own heartbeat behavior without conflicting guidance.
- Modified `src/agents/system-prompt.ts:620-633` to wrap HEARTBEAT_OK instructions in `if (!heartbeatPrompt)` check
- The `heartbeatPrompt` variable is already trimmed at line 345, so the check correctly identifies when a custom prompt is set
- Maintains backward compatibility: default behavior unchanged when no custom prompt is configured
- Enables custom heartbeat patterns like "Free Mind Protocol" for autonomous agent operation
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no risk
- The change is minimal, well-contained, and logically correct. It adds a simple conditional check that preserves existing behavior when no custom prompt is set, while fixing the conflicting instructions issue when a custom prompt is configured. The variable `heartbeatPrompt` is already properly trimmed at line 345, ensuring the boolean check works correctly for empty strings, undefined, and actual custom prompts.
- No files require special attention
<sub>Last reviewed commit: 8447d89</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#16373: fix: suppress leaked heartbeat poll prompts in reply delivery
by luisecab · 2026-02-14
81.3%
#12701: security: prefix bare .md file references with ./ to prevent TLD re...
by sypsyp97 · 2026-02-09
75.5%
#15575: fix(heartbeat): suppress prefixed HEARTBEAT_OK ack replies (#15505)
by TsekaLuk · 2026-02-13
74.7%
#17371: fix(heartbeat): always strip HEARTBEAT_OK token from reply text
by BinHPdev · 2026-02-15
74.0%
#17221: fix(agents): prevent agents from using exec for gateway management
by CornBrother0x · 2026-02-15
73.9%
#19406: fix(heartbeat): filter error payloads from heartbeat reply selection
by namabile · 2026-02-17
73.7%
#17006: fix(heartbeat): skip delivery when showOk is false
by Limitless2023 · 2026-02-15
73.4%
#23588: fix(auto-reply): suppress repetitive HEARTBEAT_OK loops
by mohandshamada · 2026-02-22
73.2%
#6522: fix(cron): deliver original message when agent response is heartbea...
by sidmohan0 · 2026-02-01
73.0%
#23736: fix(system-prompt): improve prompt cache locality with unique agent ID
by mrx-arafat · 2026-02-22
73.0%