Repository navigation
Add configurable blocking for hook failures - #94
jonathanhefner wants to merge 1 commit into
Conversation
|
No, I don't think it's enough. It's still only "SHOULD report", and the example that names the hook is just an example. Mycelium's SessionStart handler is the case I mentioned on #89. It was cancelled on 32 of 33 starts between August 9 and September 10. The client did write that down, in the session transcript. Nobody read it. I guess that might count as reporting under a SHOULD. I wouldn't ask for a new format. When Rejecting the whole plugin, I'd keep. Half a plugin with its checks missing is worse. But our handlers cover the agent's writes in general, not only our own skills, so when the plugin is rejected those writes go through unchecked. Item 5 of §7.3.2 only has a SHOULD report there too. I'd make that a MUST as well. I should say that the timeout was on an event that can't block. When I measured 40 transcripts last month, our PreToolUse handlers hadn't failed once. So I haven't actually seen a denial like this go unnoticed, I'm reasoning from the event next to it. |
|
My take on the open questions: 1. I think rejecting the whole plugin is right. If my hook config is broken, I'd rather the plugin fail to load and tell me, so I fix it once. Loading it without the hook is worse. I'd do this for any invalid hook config, whether or not it uses 2. I'd make this a MUST. When my hook denies a call, the agent gets my reason. When my hook crashes, the agent may just see "blocked". It can't tell a policy no from a broken hook, so it may retry or work around it. One line like your example ("Tool call blocked because the check-tool-policy hook timed out.") would do. |
Let authors require failure-based denial for individual handlers where the event permits it. Cover command-resolution and launch failures as well as failures after launch, while preserving successful-denial precedence and existing client policy when the setting is omitted. Reject invalid portable hook configuration before making any plugin components available or executing them. Skipping malformed checks could otherwise expose plugin skills and MCP servers without the governance intended for their use. Reserve `continue` in the shared schema without assigning it an explicit nonblocking meaning. Illustrate failure feedback through existing client response paths without requiring a new diagnostic format or delivery behavior.
a6a93f8 to
ddf8217
Compare
a67d5db to
300ea67
Compare
Note
This is based on top of the changes from #89.
Summary
Add an optional
onFailure: "block"setting to individual hook handlers. When that handler fails, the client must prevent the associated operation from proceeding. Leaving the field unset preserves the event's existing failure policy.The setting is available only where the event permits failure-based blocking, currently
PreToolUseandUserPromptSubmit. It covers executable-resolution and launch failures, timeouts, output limits, nonzero exits, and invalid output. A successfulallowfrom another handler cannot override the blocking requirement.Also require clients that support portable hooks to reject the entire plugin when its portable hook configuration is invalid, before making any of its components available.
Motivation
A plugin may check proposed tool calls or submitted requests before allowing them to proceed. The current contract permits a client to block when such a handler fails, but gives the author no way to require that behavior across clients. A policy check that crashes or times out can therefore prevent an operation in one client while allowing it in another.
Configuration errors can remove the check altogether. Skipping a malformed handler while loading the plugin's remaining components can make its skills and MCP servers available without the hooks intended to govern their use.
Rationale
Preserving client policy when the setting is omitted reduces the changes needed to adopt portable hooks. Authors can still require blocking for individual handlers that enforce governance. Limiting the setting to events that already permit failure-based blocking preserves the defined behavior of the other events.
A plugin may rely on a hook to govern use of its skills and MCP servers. If clients simply skipped invalid handlers, a misspelled
onFailuresetting could remove that check while leaving those components available. Rejecting the plugin prevents a configuration mistake from bypassing the intended protection.Rejecting the plugin because an executable is unavailable would also disable its other usable components. Treating this as an invocation failure instead keeps the handler subject to its configured failure policy.
A named value makes the requested outcome explicit and leaves room for a future nonblocking policy. The spelling
"continue"is reserved without defining an explicit nonblocking policy now: authors must not use it, and clients encountering it on an eligible event treat the field as omitted while processing the handler normally. Including the reserved spelling in the schema lets clients validate the configuration directly, at the cost of leaving that authoring prohibition to the specification text.Open Questions
Should invalid portable hook configuration require rejection of the entire plugin? This proposal makes that requirement broader than the setting itself. It changes hook configuration errors from isolated failures into plugin-loading failures, including for plugins that do not use
onFailure. MCP configuration errors retain their existing failure boundaries. An alternative would permit stricter client loading policy without requiring every hooks-capable client to reject the plugin.Is the guidance for reporting failure-based denials sufficient? The examples use the client’s normal blocked-operation and submission-error paths. They do not introduce a new diagnostic format or feedback-delivery requirement.