docs(plugins/hooks): regroup hook catalog by surface, mark decision hooks, sync before_tool_call result type with code

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> | void;
+    pluginId?: string;
+    onResolution?: (
+      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
+    ) => Promise<void> | 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