The most frustrating failure mode in AI-assisted coding isn't a bad edit; it's the agent confidently declaring the job "all done" while the build remains red. A new post on DEV.to by vildandenai provides a practical solution using Claude Code's Stop hook, a mechanism that intercepts the agent's attempt to finish a turn. By configuring the hook to run a type checker, developers can force the agent to acknowledge and fix errors before it is allowed to stop.

The Mechanics of the Stop Hook

The core of this technique relies on the specific behavior of the Stop hook when it exits with status code 2. In this scenario, the stop action is blocked, and any output printed to stderr is fed back to the agent as the reason for the rejection. The provided Python script executes npx tsc --noEmit --pretty false to check for TypeScript errors. If the return code is non-zero, the script prints the last 1500 characters of the standard output to stderr and exits with status 2, effectively telling the agent, "Type check still fails. Fix these before finishing."

Configuration and Loop Prevention

To implement this, developers must update their .claude/settings.json file to include a hooks object with a Stop array. This array calls the custom Python script located in the .claude/hooks/ directory. A critical detail in the script is the stop_hook_active guard. The script checks if this event flag is true; if so, it exits with status 0. This prevents an endless loop where the agent is blocked repeatedly for errors it cannot fix in the current context, ensuring the system remains responsive rather than stuck in a validation cycle.

Best Practices for Agent Guardrails

The author emphasizes that performance matters. Running a full test suite on every stop attempt is too slow and annoying for most workflows. Instead, a fast type check or lint pass is recommended as the primary gate. For comprehensive safety, the post suggests pairing this Stop hook with a PostToolUse hook for per-edit checks and a PreToolUse deny list for dangerous commands. This combination creates three small, boring guardrails that are far more effective and maintainable than one long, complex system prompt.

Key Takeaways

  • Use Stop hooks with exit status 2 to block premature agent completion.
  • Always include a stop_hook_active guard to prevent infinite validation loops.
  • Keep checks fast; use type checking or linting instead of full test suites for stop gates.
  • Combine Stop, PostToolUse, and PreToolUse hooks for layered agent safety.

The Bottom Line

This approach transforms Claude Code from a confident liar into a disciplined worker, proving that simple exit codes are often more reliable than complex prompt engineering.