Product case study · November 13, 2026

Claude Code: Catch a Missing Acceptance Check Before Starting

Build a small Claude Code prompt hook that rejects practice tasks without an acceptance line. Test its limits before enabling it in a disposable project.

Reading time
8 min
Checked
Nov 13, 2026
Ochre task cards approach a charcoal paper gate while a blue evidence card accompanies a task through the opening
Put the acceptance check beside the task before work starts.
Bottom line

A prompt hook can catch a missing field; deciding whether that field describes a useful test still needs judgment.

“Fix the total” gives a coding agent a task but leaves you without a clear way to judge the result. A better request names an observable check: “For the supplied expenses, the total must be 35.00.” Forgetting that second sentence is easy when you are moving quickly.

This exercise adds a small reminder at submission time. Prompts beginning with [practice-task] must contain a nonempty Acceptance: line. Ordinary questions pass through. The result is a prompt-format check you can inspect and test yourself.

Sources checked November 13, 2026. We ran the Python checks below locally. We did not run an authenticated Claude session or verify hook loading in the app. The integration steps describe what you should observe, not a reported model result.

Give the reminder a narrow job

Anthropic documents UserPromptSubmit as running before Claude processes a submitted prompt. Command hooks receive JSON on standard input; this event includes a prompt field. Exiting with code 2 blocks submission and displays the script’s error message. See the hook reference.

Our rule is deliberately mechanical. It checks a marker and one line of text. It cannot judge whether a test is sensible, whether an implementation passes, or whether the user has authorization to request a change. Someone can omit the marker or write Acceptance: looks good and pass. That limitation is part of the exercise.

Use Bash and Python 3 on Linux or macOS. The optional integration step also needs an installed, authenticated Claude Code CLI. Follow the first-session lesson if you have not prepared one.

In a terminal, create an empty practice folder:

prompt_lab=$(mktemp -d)
cd "$prompt_lab"
mkdir -p .claude/hooks
printf 'Practice folder: %s\n' "$prompt_lab"

Keep this terminal open so the variable remains available. Put only synthetic practice material here.

Write the check before connecting it

Save this as .claude/hooks/check-acceptance.py in that folder:

import json
import sys


def block(message):
    print(message, file=sys.stderr)
    raise SystemExit(2)


try:
    event = json.load(sys.stdin)
except (ValueError, UnicodeError):
    block("Practice hook: invalid JSON input; inspect the hook setup.")

if not isinstance(event, dict):
    block("Practice hook: expected a JSON object.")

prompt = event.get("prompt")
if not isinstance(prompt, str):
    block("Practice hook: expected a text prompt field.")

if not prompt.lstrip().startswith("[practice-task]"):
    raise SystemExit(0)

for line in prompt.splitlines():
    label, separator, value = line.strip().partition(":")
    if separator and label == "Acceptance" and value.strip():
        raise SystemExit(0)

block("Practice task needs an Acceptance: line with an observable check.")

The script never executes prompt text, reads project files or writes a transcript. It emits no stdout. Capitalization is intentional: acceptance: does not match Acceptance:. The acceptance text must start on the same line as the label.

Do not expand this into a secret detector. A block is not a promise that submitted text disappears from local history; Anthropic documents transcript behavior for blocked prompts in the same reference.

Exercise the parser with seven inputs

Run this from the practice folder. It feeds synthetic events directly to the script, so no model or Claude account is involved:

python3 - <<'PY'
import json
import subprocess
import sys

cases = [
    ("ordinary question", {"prompt": "Explain an acceptance check."}, 0),
    ("missing line", {"prompt": "[practice-task] Explain the total."}, 2),
    ("empty line", {"prompt": "[practice-task] Explain it.\nAcceptance:   "}, 2),
    ("concrete check", {"prompt": "[practice-task] Add 12 and 23.\nAcceptance: answer is 35."}, 0),
    ("wrong field type", {"prompt": 42}, 2),
    ("wrong container", [], 2),
    ("weak check still passes", {"prompt": "[practice-task] Explain it.\nAcceptance: looks good"}, 0),
]
for name, event, expected in cases:
    run = subprocess.run(
        [sys.executable, ".claude/hooks/check-acceptance.py"],
        input=json.dumps(event), text=True, capture_output=True,
    )
    assert run.returncode == expected, (name, run.returncode, run.stderr)
    assert run.stdout == "", (name, run.stdout)
    assert bool(run.stderr.strip()) == (expected == 2), name
    print(f"PASS: {name}")

bad_json = subprocess.run(
    [sys.executable, ".claude/hooks/check-acceptance.py"],
    input="{", text=True, capture_output=True,
)
assert bad_json.returncode == 2
assert "invalid JSON" in bad_json.stderr
print("PASS: malformed JSON")
PY

Expect eight PASS lines: seven structured inputs and one malformed JSON case. The weak-check case matters as much as the rejection cases. It demonstrates exactly where this automation stops helping.

A failure here is a script problem to resolve before enabling the hook. A pass proves the local parser behavior, not that Claude discovers or invokes it.

Enable it only in the practice folder

Create .claude/settings.local.json with the following content. This is a new file in an empty lab; do not overwrite an existing project’s settings with it.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-acceptance.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

CLAUDE_PROJECT_DIR provides the project path when Claude launches the hook. No matcher is needed for this event; the script filters the prompt itself. These details are covered in the hook configuration reference.

The settings guide distinguishes project-local settings from shared project and user settings. A fresh folder does not remove inherited user configuration or managed policy. Review the setup you actually run. If you later copy this manually created local settings file into a Git project, exclude it from version control before committing.

Check the JSON, record your CLI version, and start a fresh session from the lab:

python3 -m json.tool .claude/settings.local.json > /dev/null
claude --version
claude

Open /hooks and inspect the UserPromptSubmit entry. Anthropic’s hooks setup guide uses this menu to verify configuration. Check the script path before trusting the practice folder. Hooks run local commands, so reviewing their source matters.

Compare the incomplete and complete requests

First type this short prompt directly into Claude:

[practice-task] Explain what 12 plus 23 equals. Do not use tools.

The expected observation is a block message requesting an Acceptance: line, without a model answer to that task. If Claude answers, stop and investigate hook loading; do not mark the integration successful because the arithmetic is right.

Now submit:

[practice-task] Explain what 12 plus 23 equals. Do not use tools.
Acceptance: state that the sum is 35 and show the addition.

The format check should allow this prompt. Inspect the answer separately: it should contain the correct sum and addition. If another hook blocks it, or account access fails, record that outcome. A local parser pass cannot establish that the model step completed.

Keep a short evidence note outside the prompt:

CheckWhat to record
ParserEight PASS lines or the exact failing case
ConfigurationCLI version and the hook entry shown in /hooks
Incomplete taskObserved block message, or the unexpected response
Complete taskWhether it reached the model and whether the answer met the check

This is a useful habit for larger tasks too: record submission acceptance separately from task completion.

Recover without weakening the rule silently

If /hooks has no entry, confirm the terminal is in the lab directory and the settings file parses. If the command fails, verify Python 3 is available and the script is at the configured path. Restart the practice session after correcting configuration, then inspect /hooks again. The hooks troubleshooting guide covers loading and execution problems.

If a marked prompt is rejected unexpectedly, look for the exact capitalized label and nonempty text on that line. If an unmarked prompt passes, that is the intended behavior. Do not describe this voluntary marker as a mandatory project-wide policy.

To finish the lab, exit Claude, move this lab’s .claude/settings.local.json to settings.local.disabled.json in the lab root, and start a fresh session if you want to verify removal. Leave the script and test evidence available for review. In a real project with other settings, remove only the specific hook entry instead of moving the entire file.

For your next task, write the acceptance line yourself before asking the agent to work. The hook can remind you to include it; the actual check still has to be worth running.

Official sources checked

All three sources were checked November 13, 2026:

Put this to work

Use a UserPromptSubmit command hook for a narrow prompt-format check.

Try

Run the Python fixture checks, then compare a blocked and an accepted prompt in a disposable project.

Prove it worked

Keep local test output and record whether Claude actually blocks the incomplete prompt.

Keep in view

  • Require a nonempty Acceptance line on prompts marked [practice-task].
  • Test missing, empty and malformed inputs without calling a model.
  • Separate a working parser from a hook verified inside Claude Code.
Learn the workflow: Prepare a Claude Code project session