Let the agent self-pause on an unrecoverable blocker

[dqtz5vpvj9-create]

Motivation — observed runaway loop

The original STOP_HOOK_REASON told only the user how to stop the loop:

If the goal cannot continue productively because user input is required, explain the blocker clearly. The user can run /goal pause or /goal clear to stop automatic continuation.

When the agent encountered a real hard blocker (target device offline, missing external resource, user input required), it followed the instruction literally: it wrote "please run /goal pause" in chat and stopped. But chat text does not trigger user-side slash commands — the agent cannot invoke /goal pause. So the Stop hook re-fired, the same STOP_HOOK_REASON was re-injected, the agent re-explained the same blocker, and the loop tightened until either CLAUDE_GOAL_MAX_STOP_CONTINUES (500) was hit or the user's API budget ran out.

Shape of one real incident (Claude Opus 4.7 + Claude Code, May 2026), anonymized:

● Cannot make productive progress: target device is offline / unavailable,
  cannot continue flashing or run the verification step. Please /goal pause.
● Ran 1 stop hook
  ⎿ Stop hook error: An active /goal is still running.
    <objective>[install component X on device and verify it runs]</objective>
    ...
    The user can run /goal pause or /goal clear to stop automatic continuation.
● Cannot continue: target device is still unavailable... please run /goal pause.
● Ran 1 stop hook
  ...
[~24 retries of the same exchange]
...
⎿ Please run /login · API Error: 403 — insufficient pre-charge balance, the
  remaining account credit is below what the next request needs.

The runaway guard at 500 is far above the budget burn-through threshold for many users — the loop tightens fast enough to drain credit in well under 100 turns.

Fix — prompt only, no logic change

The backend already supports python3 claude_goal.py pause. The agent simply was never told it could use that path. This PR fixes the prompts:

• STOP_HOOK_REASON now offers both paths and explicitly warns about the failure mode that caused the loop:

  If you cannot continue (need user input, device offline, missing resource), pause it: user runs /goal pause, or you run python3 ~/.claude/skills/goal/scripts/claude_goal.py pause yourself. "Please run /goal pause" written in chat does NOT pause — this hook will re-fire until the DB status changes. If the same blocker repeats across multiple Stop re-entries, the user has not seen your message yet; self-pause.

• CONTINUATION_INSTRUCTIONS gets a matching paragraph so the same guidance is in scope from the moment a goal is set, not only after the Stop hook has already fired.

• SKILL.md mirrors the rule so the skill-loaded view is consistent with the runtime prompt.

The user-side /goal pause path is unchanged and remains the right action when the user is present and responsive.

Verification

• python3 -m pytest tests — 9/9 pass before and after.
• Manual end-to-end on Linux + Claude Code Opus 4.7 (1M context): with the patched prompts, a goal whose blocker is "objective is ambiguous, need user clarification" triggers a single self-pause via the agent's shell tool instead of repeating the blocker explanation across Stop-hook re-entries.

Diff size

2 files changed, 5 insertions(+), 1 deletion(-).

---

Generated with Claude Code.