Hooks

Hooks are event handlers that respond to lifecycle events in the agent tool. They enable plugins to automate actions like formatting code after edits, running linters, validating outputs, or enforcing policies.

Configuration Format

Hooks are configured in hooks/hooks.json at the plugin root.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Hook Rules

A hook rule matches events and dispatches to one or more hook actions.

Field	Required	Type	Description
`matcher`	No	string	Regex pattern to filter events. Matches all if omitted.
`hooks`	Yes	HookAction[]	Actions to execute when the rule matches.

The matcher tests against event-specific context: tool name for tool events, file path for file events, command string for shell events.

Core Events

Event	When It Fires	Matcher Context
`PreToolUse`	Before the agent uses a tool	Tool name
`PostToolUse`	After a tool is used successfully	Tool name
`PostToolUseFailure`	After a tool use fails	Tool name
`SessionStart`	At the beginning of a session	—
`SessionEnd`	At the end of a session	—

Extended Events

Event	When It Fires	Matcher Context
`BeforeReadFile`	Before reading a file	File path
`AfterFileEdit`	After a file is written or edited	File path
`BeforeShellExecution`	Before executing a shell command	Command string
`AfterShellExecution`	After a shell command completes	Command string
`UserPromptSubmit`	When the user submits a prompt	—
`Stop`	When the agent attempts to stop	—
`SubagentStart` / `SubagentStop`	Sub-agent lifecycle	—

Tools MUST ignore event names they do not recognize.

Hook Action Types

`command`

{ "type": "command", "command": "${PLUGIN_ROOT}/scripts/lint.sh" }

Receives event context as JSON on stdin. Exit code 0 = success.

`prompt`

{ "type": "prompt", "prompt": "Review the following change for security issues: $ARGUMENTS" }

Sends the prompt to the LLM. $ARGUMENTS is replaced with event context.

`agent`

{ "type": "agent", "prompt": "Verify the code changes follow the style guide." }

Like prompt, but with tool access for multi-step verification.

Script Requirements

Hook scripts MUST be executable, include a shebang line, and use ${PLUGIN_ROOT} for internal paths. Exit 0 on success, write errors to stderr.

Execution Model

Multiple rules MAY match the same event. All are executed.
Within a rule, hooks execute in array order.
Tools SHOULD enforce timeouts. Failures MUST NOT crash the host tool.

Hooks

On this page