> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Plannotator from automation hooks

> Gate documents and agent messages with Plannotator using plain text, structured JSON, or hook-native output.

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.

```bash theme={null}
plannotator annotate path/to/spec.md --hook
plannotator annotate-last --hook
```

`--hook` implies `--gate`, so the review UI includes an Approve action.

## Output contracts

The contracts apply to `annotate` and `annotate-last`.

### Hook-native output

```bash theme={null}
plannotator annotate path/to/spec.md --hook
```

| User action        | Standard output                              |
| ------------------ | -------------------------------------------- |
| Submit annotations | `{"decision":"block","reason":"<feedback>"}` |
| Approve            | Empty                                        |
| Close              | Empty                                        |

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

```bash theme={null}
plannotator annotate path/to/spec.md --gate --json
```

| User action        | Standard output                                    |
| ------------------ | -------------------------------------------------- |
| Submit annotations | `{"decision":"annotated","feedback":"<feedback>"}` |
| Approve            | `{"decision":"approved"}`                          |
| Close              | `{"decision":"dismissed"}`                         |

`--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:

```bash theme={null}
artifact_path="path supplied by the host"
plannotator annotate "$artifact_path" --hook
```

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`:

```bash theme={null}
printf '%s' "$artifact_text" | plannotator annotate-last --stdin --hook
```

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.