5K

Stop Hook Auto-Continue Pattern

Runs a stop hook after each agent turn that checks success criteria and makes the agent continue until tests or checks pass

emerging Updated 2026-10-13 By Nikola Balic (@nibzard) Based on Boris Cherny (Anthropic), Reflexion (Shinn et al., NeurIPS 2023), Self-Refine (Madaan et al., ICLR 2023)
View .md Edit on GitHub
Add to Pack
or

Saved locally in this browser for now.

Cite This Pattern
APA 
Nikola Balic (@nibzard) (2026). Stop Hook Auto-Continue Pattern. In *Awesome Agentic Patterns*. Retrieved October 14, 2026, from https://agentic-patterns.com/patterns/stop-hook-auto-continue-pattern
BibTeX 
@misc{agentic_patterns_stop-hook-auto-continue-pattern,
  title = {Stop Hook Auto-Continue Pattern},
  author = {Nikola Balic (@nibzard)},
  year = {2026},
  howpublished = {\url{https://agentic-patterns.com/patterns/stop-hook-auto-continue-pattern}},
  note = {Awesome Agentic Patterns}
}

Use when

  • Agent stops before tests, builds, or linters pass
  • Success criteria can be checked by a script
  • Agent runs in a sandbox or container

Avoid when

  • No reliable automated success check exists
  • Criteria may be impossible to meet, which causes endless loops
  • No timeout or token budget can be set

Problem

Agents complete their turn and return control to the user even when the task isn't truly done. Common scenarios:

  • Code compiles but tests fail
  • Changes made but quality checks haven't passed
  • Feature implemented but integration tests broken
  • Migrations run but verification steps not completed

Without intervention, the user must manually check and re-prompt the agent, creating friction.

Solution

Use stop hooks to programmatically check success criteria after each agent turn. If criteria aren't met, automatically continue the agent's execution until the task is genuinely complete.

Stop hook: A script that runs when the agent finishes a turn. It can inspect state and decide whether to return control to the user or keep the agent running.

define_stop_hook() {
    # Runs after every agent turn completion

    test_result = run_tests()

    if test_result.failed:
        agent.continue_with_prompt(
            "Tests failed with: {test_result.errors}. Fix these issues."
        )
    else:
        agent.stop()  # Return control to user
}

Combined with dangerous mode: In containerized/sandboxed environments, this enables fully autonomous operation until success.

Evidence

  • Evidence Grade: high
  • Most Valuable Findings:
    • Academic foundations: Reflexion (NeurIPS 2023) and Self-Refine (ICLR 2023) establish the generate → verify → continue if needed loop structure
    • Hook-based execution control formally validated as a security pattern (Beurer-Kellner et al., 2025)
    • Production implementations: Claude Code, LangGraph, AutoGen, GitHub Agentic Workflows
  • Unverified / Unclear: Cost vs. reliability trade-offs lack empirical quantification

How to use it

Basic implementation:

  1. Define success criteria (tests pass, build succeeds, linter clean, etc.)
  2. Create stop hook that checks these criteria
  3. If criteria fail, inject feedback and continue agent execution
  4. If criteria pass, return control to user

Claude Code configuration:

Claude Code runs stop hooks on the Stop event, which fires when the main agent finishes responding. Configure the command in the settings JSON:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/check_success.sh" }
        ]
      }
    ]
  }
}

The script continues the agent by printing a decision block with a reason:

{
  "decision": "block",
  "reason": "Tests failed: 2 assertions. Fix these issues."
}

Exit code 0 with no output lets the turn end. Stop hooks receive a stop_hook_active flag that is true when the agent is already continuing because of a stop hook; check it to avoid blocking on a condition that will never resolve. Claude Code also caps consecutive stop-hook continuations at eight.

Power user pattern (from transcript):

"You can define a stop hook that's like, if the tests don't pass, keep going. Essentially make the model keep going until the thing is done."

Advanced usage with programmatic SDK:

Combine with dangerous mode in containers for autonomous operation:

  • Agent makes changes
  • Stop hook checks tests
  • If failing, agent continues autonomously
  • Loops until tests pass or timeout
  • Result: "Deterministic outcomes from non-deterministic processes"

Trade-offs

Pros:

  • True task completion: Don't stop until actually done
  • Reduced human intervention: No manual re-prompting needed
  • Systematic quality: Encoded success criteria, not human judgment
  • Autonomous operation: Combined with SDK, enables fully hands-off tasks
  • Prevents premature completion: Agent can't declare victory too early

Cons:

  • Runaway costs: Agent might loop indefinitely if criteria impossible
  • Models can ignore the hook: practitioner reports describe models bypassing stop hooks, so treat auto-continue as best-effort rather than a guarantee (Hacker News reports)
  • Requires good criteria: Bad success checks lead to infinite loops
  • Container overhead: Safest in sandboxed environments
  • Debugging challenges: Harder to inspect mid-execution state
  • Timeout management: Need sensible limits to prevent infinite execution

Safety considerations:

  • Use timeouts to bound execution
  • Monitor token usage during loops
  • Test hooks in safe environments first
  • Start with simple criteria before complex checks
  • Log all auto-continue decisions for debugging

References