agent-framework/references/stop-hook-pattern.md

# Stop-Hook Pattern (How to Enforce Task Completion)

This pattern prevents the agent from ending a session until the contract is satisfied, matching the article's recommendation.

## Core Idea
Instead of relying on the agent to voluntarily output "CONTRACT_MET", the orchestration layer (you or a thin wrapper) only allows the session to terminate when the stop condition is met.

## Implementation Options

### Option 1: Explicit Stop Condition in Every Prompt (Recommended)
Add this block to the end of `implement.md`, `research.md`, and any other phase that produces a deliverable:

```
## Stop Condition (MANDATORY)
You are not allowed to end this session until one of the following is true:
- You have produced the required output file(s) AND output the exact phrase "CONTRACT_MET"
- You have explicitly stated that the contract cannot be met and explained why

Until then, continue working or ask clarifying questions.
```

### Option 2: Contract File as Gate
Every task folder must contain a `{task-name}_CONTRACT.md`.

The agent is instructed:
- Read the contract at the start of the session
- Only output "CONTRACT_MET" after every item in the contract has been verified (tests pass, files exist, acceptance criteria checked)

### Option 3: External Orchestrator Hook (Strongest)
If using a thin wrapper script around the agent CLI:

```bash
# Example pseudo-wrapper
while true; do
  agent run --prompt "$(render_prompt implement.md)"
  if grep -q "CONTRACT_MET" last_output.txt; then
    break
  fi
  # Otherwise feed the failure back into the same session or new one
done
```

## Recommended Addition to referee.md and implement.md
After the verdict or implementation, add:

```
## Final Gate
Before finishing, re-read the CONTRACT.md (if present) and confirm every line item is satisfied.
Only then output "CONTRACT_MET".
```

## Files to Update
- Add the stop condition block to:
  - prompts/implement.md
  - prompts/research.md
  - prompts/bug_finder.md (optional)
- Update .onboarding.md to document this pattern under "Define Clear End States"

This turns the voluntary "CONTRACT_MET" into a hard mechanical requirement.