Skip to main content
Use --hook when a host hook should block on submitted annotations and pass when the user approves or closes the session. Use --json when your own wrapper needs to distinguish approved, dismissed, and annotated decisions.
--hook implies --gate, so the review UI includes an Approve action.

​
Output contracts

The contracts apply to annotate and annotate-last.

​
Hook-native output

This contract works directly with Claude Code and Codex PostToolUse or Stop command-hook protocols that treat a block decision as feedback for the agent. If --hook and --json are both present, the hook-native contract wins.

​
Structured JSON

--json does not add the Approve action by itself. Add --gate if approval is part of your wrapper’s contract.

​
Plain text

Without --json or --hook, submitted annotations are printed as feedback. Approval prints the exact line The user approved. and closing prints nothing. Completed user decisions exit with status 0. Invalid input and startup failures can exit nonzero, so wrappers should check both the process status and standard output.

​
Pass input safely

The path to review must come from the hook event or from a trusted wrapper argument. Quote it as one shell argument:
Hook event schemas differ by agent and version. Do not copy an input-field name from another host. Use the host’s current hook documentation to extract the file path, then call the CLI contract above. For a host that sends content rather than a file path, pipe it to annotate-last --stdin:
Avoid expanding untrusted hook content as shell code. Pass values as quoted arguments or standard input.

​
Installed plan hooks

The full installer and agent plugins configure plan review for supported hosts. For example, the Claude Code plugin ships:
  • a PreToolUse hook on EnterPlanMode that calls plannotator improve-context
  • a PermissionRequest hook on ExitPlanMode that calls plannotator and waits for the review decision
Codex uses its experimental Stop hook on macOS, Linux, and WSL. Copilot CLI uses its plugin’s pre-tool hook for exit_plan_mode. Those plan hooks use host-specific event schemas and should normally be managed by the installer or plugin. Restart the agent after changing hook configuration. Desktop applications may not inherit your shell PATH; use the absolute path to the Plannotator binary if a hook reports that the command is missing.

​
Timeouts

A review is intentionally long-running. The shipped plan hooks use a timeout of 345600 seconds. If you write a custom hook, choose a timeout that allows a person to review without leaving an orphaned process. Last verified against Plannotator OSS v0.23.1 on July 18, 2026. Maintained by the Plannotator project.
Last modified on July 19, 2026