From 5d7d5ca2a9bf62063fb8649a8d30a4662dd52dfc Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Fri, 24 Apr 2026 11:02:38 -0700 Subject: [PATCH] docs(plugins/hooks): regroup hook catalog by surface, mark decision hooks, sync before_tool_call result type with code --- docs/plugins/hooks.md | 73 ++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 19 deletions(-) diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md index 3a4cf69c129..843b6771990 100644 --- a/docs/plugins/hooks.md +++ b/docs/plugins/hooks.md @@ -52,25 +52,55 @@ export default definePluginEntry({ Hook handlers run sequentially in descending `priority`. Same-priority hooks keep registration order. -## Common hooks +## Hook catalog -| Hook | Use it for | -| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `before_tool_call` | Rewrite tool params, block execution, or request user approval before a tool runs. | -| `after_tool_call` | Observe tool results, errors, and duration after execution. | -| `before_prompt_build` | Add dynamic context or system prompt text before the model call. | -| `before_model_resolve` | Override provider or model before session messages are loaded. | -| `before_agent_reply` | Short-circuit the model turn with a synthetic reply or silence. | -| `llm_input` / `llm_output` | Observe provider input/output for conversation-aware plugins. | -| `agent_end` | Observe final messages, success state, and run duration. | -| `message_received` | Observe inbound channel messages after channel parsing. | -| `message_sending` | Rewrite or cancel outbound channel messages. | -| `message_sent` | Observe outbound delivery success or failure. | -| `session_start` / `session_end` | Track session lifecycle boundaries. | -| `before_compaction` / `after_compaction` | Observe or annotate compaction cycles. | -| `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` | Coordinate subagent routing and completion delivery. | -| `gateway_start` / `gateway_stop` | Start or stop plugin services with the Gateway. | -| `before_install` | Inspect skill or plugin install scans and optionally block. | +Hooks are grouped by the surface they extend. Names in **bold** accept a +decision result (block, cancel, override, or require approval); all others are +observation-only. + +**Agent turn** + +- `before_model_resolve` — override provider or model before session messages load +- `before_prompt_build` — add dynamic context or system-prompt text before the model call +- `before_agent_start` — compatibility-only combined phase; prefer the two hooks above +- **`before_agent_reply`** — short-circuit the model turn with a synthetic reply or silence +- `agent_end` — observe final messages, success state, and run duration + +**Conversation observation** + +- `llm_input` — observe provider input (system prompt, prompt, history) +- `llm_output` — observe provider output + +**Tools** + +- **`before_tool_call`** — rewrite tool params, block execution, or require approval +- `after_tool_call` — observe tool results, errors, and duration +- **`tool_result_persist`** — rewrite the assistant message produced from a tool result +- **`before_message_write`** — inspect or block an in-progress message write (rare) + +**Messages and delivery** + +- **`inbound_claim`** — claim an inbound message before agent routing (synthetic replies) +- `message_received` — observe inbound content, sender, thread, and metadata +- **`message_sending`** — rewrite outbound content or cancel delivery +- `message_sent` — observe outbound delivery success or failure +- **`before_dispatch`** — inspect or rewrite an outbound dispatch before channel handoff +- **`reply_dispatch`** — participate in the final reply-dispatch pipeline + +**Sessions and compaction** + +- `session_start` / `session_end` — track session lifecycle boundaries +- `before_compaction` / `after_compaction` — observe or annotate compaction cycles +- `before_reset` — observe session-reset events (`/reset`, programmatic resets) + +**Subagents** + +- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordinate subagent routing and completion delivery + +**Lifecycle** + +- `gateway_start` / `gateway_stop` — start or stop plugin-owned services with the Gateway +- **`before_install`** — inspect skill or plugin install scans and optionally block ## Tool call policy @@ -96,7 +126,10 @@ type BeforeToolCallResult = { severity?: "info" | "warning" | "critical"; timeoutMs?: number; timeoutBehavior?: "allow" | "deny"; - onResolution?: (decision: string) => Promise | void; + pluginId?: string; + onResolution?: ( + decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled", + ) => Promise | void; }; }; ``` @@ -110,6 +143,8 @@ Rules: approvals. The `/approve` command can approve both exec and plugin approvals. - A lower-priority `block: true` can still block after a higher-priority hook requested approval. +- `onResolution` receives the resolved approval decision — `allow-once`, + `allow-always`, `deny`, `timeout`, or `cancelled`. ## Prompt and model hooks