Stanza

Hook Protocol

See what stanza hook reads, prints and exits with.

stanza hook [--braces | --no-braces] [--hunks]

stanza hook is the Stop hook for Claude Code and Codex, the PostToolUse hook on Edit and MultiEdit for Claude Code and on apply_patch for Codex, and the PreToolUse hook on Write for Claude Code. This page is what it does with each input. What to write where is under Claude Code and Codex.

It takes --braces, --no-braces and --hunks in its command, and they mean what they mean for --fix. With AGENT_HOOKS=0 in its environment it prints nothing and exits 0 before reading anything.

Input

The input is one JSON object on stdin. Other fields are ignored.

Prop

Type

Events

hook_event_namewhat runs
absent, Stopthe Stop pass
SubagentStopthe subagent pass
PreToolUseformat the Write
PostToolUsefix the edit
anything elsenothing, exit 0

Stop

The Stop pass runs one --fix pass over changed files, picked as --changed picks them.

With a readable Claude Code transcript at transcript_path, it keeps only the files the agent created or edited with Write, Edit or MultiEdit, so files a human left dirty stay untouched. A tool call that failed does not count. It also reads every .jsonl transcript at any depth below the session's subagents folder (the transcript path without .jsonl, then subagents), so Task subagents and Workflow agents count too. It does not follow a directory symlink there, and a missing or malformed transcript adds nothing. Every Stop reads all of these transcripts, so a session with many agents takes longer to check. With a Codex rollout, it keeps files that completed patches added, updated or moved to. Those files are fixed in whichever repository holds them, which need not be the one at cwd, except a path whose symlink leads out of its repository. Without a transcript, with one Stanza does not recognise, or with a Codex rollout that names no patched file yet, it takes every changed file in the repository at cwd, including ones edited by hand.

It prints nothing when:

  • the files come out clean,
  • stop_hook_active is true,
  • no file it would fix is inside a git repository.

When findings remain that --fix cannot apply, it prints a block decision on stdout:

{ "decision": "block", "reason": "..." }

The reason holds:

  1. the findings, up to twelve, then how many more there are,
  2. a line per rule that fired, with its summary,
  3. an instruction to fix those findings and reply again,
  4. when a file it rewrote still has a finding, an instruction to read that file again before editing it.

A file whose fixes it cannot write is listed with the error, and the rest of the pass still runs.

A file stanza hits an internal error on is left untouched and listed as stanza failed on this file: internal error (...). The rest of the pass still runs, then the hook writes one line on stderr naming the file and exits 1, so Claude Code shows a notice rather than blocking the agent on a bug in stanza.

SubagentStop

SubagentStop runs the same fix and block pass as Stop, but only over files its own agent_transcript_path names. It counts absolute paths from Write, Edit and MultiEdit calls, excluding failed calls, or, in a Codex rollout, files that completed patches added, updated or moved to. It ignores transcript_path and never discovers sibling or descendant transcripts.

It prints nothing, changes no file and exits 0 when agent_transcript_path is absent, unreadable, unrecognised or names no writes. It never falls back to repository changes. A clean pass or stop_hook_active: true also prints nothing. Remaining findings block only on the subagent's own files, using the same decision and reason as Stop.

PreToolUse

For a Write, it formats tool_input.content before the file lands. Edit and MultiEdit are fixed after they land. --braces, --no-braces and lint config apply as for any file.

When it changes the content, it prints on stdout:

fieldvalue
hookSpecificOutput.hookEventNamePreToolUse
hookSpecificOutput.updatedInputthe tool input as sent, with its last content formatted
hookSpecificOutput.additionalContexttells the agent to read the formatted file before editing it

It prints nothing when:

  • nothing changes,
  • the path is not TypeScript or JavaScript,
  • the file is always skipped, generated or ignored by git,
  • the content does not parse,
  • the content holds a lone surrogate, such as an unpaired \ud800 escape,
  • the path is outside git, or a symlink leads it out of its repository,
  • --hunks is set and the file is tracked in HEAD.

It never sets a permission decision, so the user's prompt is unchanged.

PostToolUse

After an Edit or MultiEdit, it runs one --fix pass over tool_input.file_path. After an apply_patch, it runs one over the paths the patch's *** Add File:, *** Update File: and *** Move to: lines name. A relative path is read against cwd, and a *** Delete File: path writes nothing. Files are picked as in the Stop pass, kept to the ones the call wrote, and --hunks narrows the fixes the same way.

When it changes a file, it prints on stdout:

fieldvalue
hookSpecificOutput.hookEventNamePostToolUse
hookSpecificOutput.additionalContextnames each file it changed and asks for a fresh read

It prints nothing when:

  • nothing changes,
  • tool_response has no success line (Codex 0.159 fires no PostToolUse for a failed patch at all),
  • a file does not parse,
  • a file is not TypeScript or JavaScript, is always skipped, generated or ignored by git,
  • a file is outside git.

Findings --fix cannot apply are left for the Stop pass to report.

Exit Status

exitwheneffect in Claude Code
0every run that did not fail, whether or not it printed anythingnone
1bad input, a flag other than --braces, --no-braces or --hunks, both braces flags, a git failure while picking files, a changed file whose name is not valid UTF-8, a relative or missing cwd when stanza cannot read the working directory, an internal error, or a reply on stdout that stanza cannot writea notice, without blocking; under PreToolUse the Write goes ahead unformatted

The message goes to stderr. It never exits 2: a Stop hook that exits 2 blocks the agent, a PreToolUse hook that exits 2 denies the Write, and a PostToolUse hook that exits 2 replaces the tool result.

On this page