@@ -52,25 +52,55 @@ export default definePluginEntry({
5252Hook handlers run sequentially in descending `priority`. Same-priority hooks
5353keep registration order.
545455-## Common hooks
56-57-| Hook | Use it for |
58-| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
59-| `before_tool_call` | Rewrite tool params, block execution, or request user approval before a tool runs. |
60-| `after_tool_call` | Observe tool results, errors, and duration after execution. |
61-| `before_prompt_build` | Add dynamic context or system prompt text before the model call. |
62-| `before_model_resolve` | Override provider or model before session messages are loaded. |
63-| `before_agent_reply` | Short-circuit the model turn with a synthetic reply or silence. |
64-| `llm_input` / `llm_output` | Observe provider input/output for conversation-aware plugins. |
65-| `agent_end` | Observe final messages, success state, and run duration. |
66-| `message_received` | Observe inbound channel messages after channel parsing. |
67-| `message_sending` | Rewrite or cancel outbound channel messages. |
68-| `message_sent` | Observe outbound delivery success or failure. |
69-| `session_start` / `session_end` | Track session lifecycle boundaries. |
70-| `before_compaction` / `after_compaction` | Observe or annotate compaction cycles. |
71-| `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` | Coordinate subagent routing and completion delivery. |
72-| `gateway_start` / `gateway_stop` | Start or stop plugin services with the Gateway. |
73-| `before_install` | Inspect skill or plugin install scans and optionally block. |
55+## Hook catalog
56+57+Hooks are grouped by the surface they extend. Names in **bold** accept a
58+decision result (block, cancel, override, or require approval); all others are
59+observation-only.
60+61+**Agent turn**
62+63+- `before_model_resolve` — override provider or model before session messages load
64+- `before_prompt_build` — add dynamic context or system-prompt text before the model call
65+- `before_agent_start` — compatibility-only combined phase; prefer the two hooks above
66+- **`before_agent_reply`** — short-circuit the model turn with a synthetic reply or silence
67+- `agent_end` — observe final messages, success state, and run duration
68+69+**Conversation observation**
70+71+- `llm_input` — observe provider input (system prompt, prompt, history)
72+- `llm_output` — observe provider output
73+74+**Tools**
75+76+- **`before_tool_call`** — rewrite tool params, block execution, or require approval
77+- `after_tool_call` — observe tool results, errors, and duration
78+- **`tool_result_persist`** — rewrite the assistant message produced from a tool result
79+- **`before_message_write`** — inspect or block an in-progress message write (rare)
80+81+**Messages and delivery**
82+83+- **`inbound_claim`** — claim an inbound message before agent routing (synthetic replies)
84+- `message_received` — observe inbound content, sender, thread, and metadata
85+- **`message_sending`** — rewrite outbound content or cancel delivery
86+- `message_sent` — observe outbound delivery success or failure
87+- **`before_dispatch`** — inspect or rewrite an outbound dispatch before channel handoff
88+- **`reply_dispatch`** — participate in the final reply-dispatch pipeline
89+90+**Sessions and compaction**
91+92+- `session_start` / `session_end` — track session lifecycle boundaries
93+- `before_compaction` / `after_compaction` — observe or annotate compaction cycles
94+- `before_reset` — observe session-reset events (`/reset`, programmatic resets)
95+96+**Subagents**
97+98+- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordinate subagent routing and completion delivery
99+100+**Lifecycle**
101+102+- `gateway_start` / `gateway_stop` — start or stop plugin-owned services with the Gateway
103+- **`before_install`** — inspect skill or plugin install scans and optionally block
7410475105## Tool call policy
76106@@ -96,7 +126,10 @@ type BeforeToolCallResult = {
96126 severity?: "info" | "warning" | "critical";
97127 timeoutMs?: number;
98128 timeoutBehavior?: "allow" | "deny";
99- onResolution?: (decision: string) => Promise<void> | void;
129+ pluginId?: string;
130+ onResolution?: (
131+decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
132+ ) => Promise<void> | void;
100133 };
101134};
102135```
@@ -110,6 +143,8 @@ Rules:
110143 approvals. The `/approve` command can approve both exec and plugin approvals.
111144- A lower-priority `block: true` can still block after a higher-priority hook
112145 requested approval.
146+- `onResolution` receives the resolved approval decision — `allow-once`,
147+`allow-always`, `deny`, `timeout`, or `cancelled`.
113148114149## Prompt and model hooks
115150此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。