Hook Events and the Agent Lifecycle

Before wiring anything up, it helps to know which events actually fire and when. The vocabulary is slightly different on each platform, but the lifecycle they describe is shared.

The Shared Lifecycle

At the abstract level, every agent session moves through the same phases:

┌─────────────────────────────────────────────┐
│ Session starts                              │ ← SessionStart
├─────────────────────────────────────────────┤
│ Repeat for each turn:                       │
│   User submits a prompt                     │ ← UserPromptSubmit
│   Model reasons and may call tools          │
│     Before each tool call                   │ ← PreToolUse
│     After each tool call                    │ ← PostToolUse
│   Turn ends                                 │ ← Stop
├─────────────────────────────────────────────┤
│ Session ends                                │ ← SessionEnd
└─────────────────────────────────────────────┘

This is the shared mental model. The platforms in this course map onto these moments with different names, different configuration surfaces, and a few gaps or extra events.

Events by Platform

Claude Code has the richest event set of the four platforms. Every event uses PascalCase and is configured in .claude/settings.json (or inside a plugin's hooks/hooks.json).

Core lifecycle events:

• SessionStart — New session begins (fresh, resume, or compaction continuation).
• InstructionsLoaded — CLAUDE.md files have been loaded.
• UserPromptSubmit — User submitted a prompt, before the model sees it.
• PreToolUse — Before a tool call runs.
• PermissionRequest — Permission prompt about to be shown.
• PermissionDenied — A tool call was denied by the auto-mode classifier.
• PostToolUse — After a tool call returns.
• PostToolUseFailure — Tool call failed.
• Stop — Turn finished.
• SessionEnd — Session closed.

Subagent and task events:

• SubagentStart, SubagentStop — A delegated subagent starts or finishes.
• TaskCreated, TaskCompleted — The TodoWrite task list changes.

Environment events:

• CwdChanged, FileChanged — Working directory or a tracked file changed.
• WorktreeCreate, WorktreeRemove — Git worktree created or removed.
• PreCompact, PostCompact — Context compaction about to happen / just finished.
• ConfigChange, Notification — Settings changed; Claude raised a notification.

Matcher groups filter on event-specific fields. Tool events match tool names (for example, "matcher": "Bash" or "matcher": "Edit|Write"), while handler-level if conditions can use permission-rule syntax to inspect tool arguments (for example, "if": "Bash(rm *)").

Codex hooks are experimental and must be enabled explicitly. In ~/.codex/config.toml:

[features]
codex_hooks = true

Codex ships a smaller core set of events, all PascalCase, configured in ~/.codex/hooks.json or <repo>/.codex/hooks.json:

• SessionStart — Session begins. Matcher filters the source field: startup, resume, or clear.
• UserPromptSubmit — User prompt submitted.
• PreToolUse — Before a supported tool call, including Bash, apply_patch (Edit|Write aliases), and MCP tools.
• PermissionRequest — Permission prompt about to be shown.
• PostToolUse — After a supported tool call, including Bash, apply_patch (Edit|Write aliases), and MCP tools.
• Stop — Turn finished.

The Codex event set is intentionally close to the classic Claude Code lifecycle, which makes cross-agent hook scripts easier to share — but note that the tool-event surface is still narrower than Claude Code's and does not intercept every tool path.

Matchers are regexes evaluated against tool_name for tool events or source for SessionStart. Codex hooks are changing quickly, so small details may differ between Codex versions. The examples below show the event set used in this course.

OpenCode does not have a JSON event config. Plugins are TypeScript or JavaScript modules in .opencode/plugins/, and each exported plugin returns an object whose keys are event names. The runtime calls the matching key when the event fires.

Typed hook keys (first-class):

• "tool.execute.before" — About to execute a tool.
• "tool.execute.after" — Tool execution finished.
• "shell.env" — About to launch a shell command; mutate the environment.
• "experimental.session.compacting" — Session is being compacted.

Generic event callback — receives \{ event \} with an event.type field. Types include lifecycle and UI events like:

• session.created, session.updated, session.idle, session.compacted, session.deleted, session.error, session.diff, session.status
• message.updated, message.removed, message.part.updated, message.part.removed
• command.executed, file.edited, file.watcher.updated
• permission.asked, permission.replied
• lsp.client.diagnostics, lsp.updated
• todo.updated, server.connected, installation.updated
• tui.prompt.append, tui.command.execute, tui.toast.show

OpenCode has no UserPromptSubmit event. The nearest equivalent is reading the new user message through the generic event callback when message.updated fires.

Pi hooks live inside TS/JS extensions in .pi/extensions/ or ~/.pi/agent/extensions/. The built-in lifecycle is lower_snake_case:

Core lifecycle events:

• session_start — Session begins (startup, reload, new, resume, or fork)
• before_agent_start — User prompt received; can inject messages or edit the system prompt
• agent_start — Agent loop begins
• turn_start, turn_end — One model turn starts or finishes
• tool_call — Before a tool executes; can mutate args or block
• tool_result — After a tool executes; can rewrite the result
• agent_end — Request finished
• session_shutdown — Extension runtime is being torn down

Session/control events:

• session_before_switch, session_before_fork — Intercept /new, /resume, /fork, or /clone
• session_before_compact, session_compact, session_before_tree, session_tree — Context management and tree navigation
• model_select, user_bash — Model changes and user-initiated shell commands

Pi doesn't use a JSON hook file. You register handlers in code with pi.on("event_name", handler) and ship them in an extension or Pi package.

Event Input: What Your Hook Receives

Command hooks receive a JSON payload on stdin. HTTP hooks receive the same payload as the POST body. Common fields across events:

{
  "session_id": "...",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

Tool-related events add tool_name, tool_input, and (on PostToolUse) tool_response. Subagent events add agent_id and agent_type. The project root is also available as an environment variable CLAUDE_PROJECT_DIR.

Command hooks receive JSON on stdin. Common fields:

{
  "session_id": "...",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "model": "gpt-5-codex"
}

Turn-scoped events add turn_id. Tool events add tool_name, tool_use_id, and tool_input; for Bash and apply_patch, the command is in tool_input.command. PostToolUse also includes tool_response. UserPromptSubmit adds prompt. Stop adds stop_hook_active and last_assistant_message.

OpenCode hooks are JS/TS functions, not stdin scripts. Each event type has a typed (input, output) signature:

"tool.execute.before": async (input, output) => {
  // input.tool       — tool name (e.g. "read", "bash")
  // input.sessionID  — session identifier
  // output.args      — tool arguments (mutable)
}

"tool.execute.after" adds the result on output. "shell.env" gives you output.env to mutate. The generic event callback receives \{ event \} where event.type identifies the event.

The plugin also receives a context object at construction time: \{ project, directory, worktree, client, $ }. Use client.app.log({...}) for structured logging and $ (Bun shell) to run commands.

Pi hooks are TS/JS functions registered in an extension. Common event shapes look like this:

pi.on("before_agent_start", async (event, ctx) => {
  // event.prompt        — user prompt text
  // event.systemPrompt  — current system prompt for this turn
  // event.images        — attached images (if any)
});

pi.on("tool_call", async (event, ctx) => {
  // event.toolName      — "bash", "read", "write", etc.
  // event.toolCallId    — unique tool call id
  // event.input         — mutable tool arguments
});

pi.on("tool_result", async (event, ctx) => {
  // event.toolName      — tool name
  // event.input         — final tool arguments
  // event.content       — tool result content blocks
  // event.details       — structured tool details
  // event.isError       — whether the tool failed
});

For nested async work inside a handler, use ctx.signal so Esc can cancel the extension's own fetch() calls or other abort-aware work.

How Hooks Influence the Agent

Hooks are not purely observational — they can change what happens next.

Exit codes (command hooks):

• Exit 0 — allow, no change.
• Exit 2 with a message on stderr — block or continue per event semantics (e.g. block the tool call on PreToolUse, erase the prompt on UserPromptSubmit).

JSON on stdout for finer control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "No network access in this project"
  }
}

Also supported: top-level continue, stopReason, suppressOutput, systemMessage, and the legacy \{ "decision": "block", "reason": "..." \} form.

HTTP hooks return the same JSON as a 2xx response body. Non-2xx responses or timeouts are treated as non-blocking errors.

Exit codes:

• 0 — success.
• 2 with stderr message — block or continue per event.

JSON on stdout uses a shape similar to Claude Code's:

{
  "systemMessage": "Injected context for the model",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "No network access in this project"
  }
}

For SessionStart, UserPromptSubmit, and PostToolUse, hookSpecificOutput can include additionalContext to inject text into the conversation.

OpenCode hooks influence the agent by mutating the output object or by throwing. To rewrite a tool call, mutate output.args. To block it, throw an error:

"tool.execute.before": async (input, output) => {
  if (input.tool === "bash" && /rm -rf/.test(output.args.command ?? "")) {
    throw new Error("dangerous command blocked by policy")
  }
}

There are no exit codes or JSON-over-stdin. All influence happens through code.

Pi hooks influence the agent by returning structured values or mutating event state in code.

• Return \{ block: true, reason: "..." \} from tool_call to cancel a tool.
• Mutate event.input inside tool_call to rewrite arguments before execution.
• Return \{ content, details, isError \} from tool_result to rewrite a tool result.
• Return message or systemPrompt from before_agent_start to inject context into the next turn.

pi.on("tool_call", async (event) => {
  if (event.toolName === "bash" && /rm -rf/.test(event.input.command as string)) {
    return { block: true, reason: "dangerous command blocked by policy" };
  }
});

pi.on("before_agent_start", async (event) => ({
  systemPrompt: event.systemPrompt + "\n\nAlways explain risky shell commands before running them.",
}));

Choosing the Right Event

A quick reference for common goals:

• Log every tool call → PreToolUse / tool.execute.before / tool_call.
• Run a linter after an edit → PostToolUse (match Edit|Write) / tool.execute.after / tool_result.
• Block dangerous commands → PreToolUse with exit code 2, a thrown error, or tool_call with \{ block: true \}.
• Inject repo context on each turn → UserPromptSubmit with additionalContext (Claude Code / Codex), the event callback on message.updated (OpenCode), or before_agent_start (Pi).
• Persist conversation state → Stop / SessionEnd, session.idle on OpenCode, or agent_end / session_shutdown on Pi.
• Add environment variables to shells → shell.env (OpenCode), or mutate tool_call / wrap user bash handling in an extension on Pi.

Key Takeaways

The platforms expose the same underlying lifecycle with different vocabulary and different levels of granularity. Claude Code has the richest event set and supports four handler types. Codex has a smaller, tightly focused set behind a feature flag. OpenCode folds hooks into its plugin system as typed function keys rather than a JSON config. Pi uses extension events such as before_agent_start, tool_call, and tool_result. Once you pick an event for the goal at hand, the rest of the work is the same across them.

Next, a quick quiz before we wire these events into a live Gradio dashboard.