Extension SessionHooks missing onPostToolUseFailure handler — failed tool results are invisible

[pacovidal]

Summary

Extensions registering hook handlers via joinSession({ hooks }) cannot observe non-success tool results. onPostToolUse only fires for resultType === "success" — failure / rejected / denied / timeout outcomes are silently invisible to extensions.

The underlying CLI does emit a postToolUseFailure hook event for failed tool calls, but the SDK never dispatches it: it is missing from both the SessionHooks interface and the runtime _handleHooksInvoke handler map.

Repro

1. In an extension, register a session via joinSession with handlers for both onPostToolUse and (attempting) onPostToolUseFailure:

   import { joinSession } from "@github/copilot-sdk/extension";
   const session = await joinSession({
     hooks: {
       onPostToolUse: async (input) => {
         console.log("post:", input.toolName, input.toolResult?.resultType);
       },
       // Not declared on SessionHooks, but try anyway:
       onPostToolUseFailure: async (input) => {
         console.log("post-failure:", input.toolName);
       },
     },
   });

2. Have Copilot run a tool that fails (e.g. a shell command that exits non-zero, then a tool that times out, then one that triggers a "rejected" / "denied" outcome).

3. Observe: onPostToolUse fires only for the successful tool calls. onPostToolUseFailure never fires for any of the failure modes.

Expected

Extensions should be able to observe all terminal tool outcomes — success, failure, rejected, denied, timeout — through the hooks system. Either:

• Add onPostToolUseFailure to SessionHooks and dispatch it from _handleHooksInvoke, or
• Always fire onPostToolUse regardless of resultType (with the resultType field on the input distinguishing outcomes).

Evidence in shipped CLI 1.0.43-0

Path: <copilot-pkg>/copilot-sdk/extension.js (the bundled SDK shipped with the Copilot CLI).

The runtime hook dispatcher exposes only 6 hook types:

async _handleHooksInvoke(hookType, input) {
  if (!this.hooks) return void 0;
  const handlerMap = {
    preToolUse: this.hooks.onPreToolUse,
    postToolUse: this.hooks.onPostToolUse,
    userPromptSubmitted: this.hooks.onUserPromptSubmitted,
    sessionStart: this.hooks.onSessionStart,
    sessionEnd: this.hooks.onSessionEnd,
    errorOccurred: this.hooks.onErrorOccurred,
  };
  const handler = handlerMap[hookType];
  if (!handler) return void 0; // silently dropped
  ...
}

The matching TypeScript declaration in copilot-sdk/types.d.ts SessionHooks declares the same 6 handlers, so authors using TypeScript can't even discover the missing types.

Meanwhile, the host CLI (app.js in the same package) builds a hook proxy per connected extension that DOES include postToolUseFailure:

// createHooksProxy(sessionId, connection)
return {
  preToolUse: [o => n("preToolUse", o)],
  postToolUse: [o => n("postToolUse", o)],
  postToolUseFailure: [o => n("postToolUseFailure", o)],
  userPromptSubmitted: [o => n("userPromptSubmitted", o)],
  sessionStart: [o => n("sessionStart", o)],
  sessionEnd: [o => n("sessionEnd", o)],
  errorOccurred: [o => n("errorOccurred", o)],
};

And the host's processToolExecutionResult explicitly gates postToolUse on success, routing failures elsewhere:

async processToolExecutionResult(toolName, toolArgs, toolResult) {
  let s = (toolResult.resultType === "success"
    ? await h1(this.getEffectiveHooks()?.postToolUse, ...)
    : void 0)?.modifiedResult ?? toolResult;

  let a = s.resultType === "failure"
    ? await this.runPostToolUseFailureHooks(toolName, toolArgs, s)
    : void 0;
  ...
}

So the CLI sends hooks.invoke requests with hookType: "postToolUseFailure" to the extension over IPC, but the SDK's _handleHooksInvoke doesn't recognize that hook type and returns undefined without invoking any handler.

The full set of hook types the CLI knows about (app.js):

new Set([
  "sessionStart", "sessionEnd", "userPromptSubmitted",
  "preToolUse", "postToolUse", "postToolUseFailure",
  "errorOccurred",
  "agentStop", "subagentStop", "subagentStart",
  "preCompact", "permissionRequest", "notification",
])

The SDK's hooks API exposes 6 of these to extensions. Several of the missing ones (like permissionRequest) are intentionally exposed via different APIs (onPermissionRequest in the JoinSessionConfig), so this report intentionally focuses on the most clear-cut gap: postToolUseFailure.

Impact

Extensions that want to observe or react to tool failures — for telemetry, replay buffers, fault-injection tests, or UI that visualizes tool execution — have no reliable way to do so. Since post-only-on-success silently drops the failure cases, extensions can wrongly report "no result" or, if pairing pre with post, leak resources tracking calls whose post will never come.

Suggested fix

Add the missing handler to _handleHooksInvoke's map and to the SessionHooks TypeScript interface:

 export interface SessionHooks {
   onPreToolUse?: PreToolUseHandler;
   onPostToolUse?: PostToolUseHandler;
+  onPostToolUseFailure?: PostToolUseFailureHandler;
   onUserPromptSubmitted?: UserPromptSubmittedHandler;
   onSessionStart?: SessionStartHandler;
   onSessionEnd?: SessionEndHandler;
   onErrorOccurred?: ErrorOccurredHandler;
 }

 const handlerMap = {
   preToolUse: this.hooks.onPreToolUse,
   postToolUse: this.hooks.onPostToolUse,
+  postToolUseFailure: this.hooks.onPostToolUseFailure,
   userPromptSubmitted: this.hooks.onUserPromptSubmitted,
   sessionStart: this.hooks.onSessionStart,
   sessionEnd: this.hooks.onSessionEnd,
   errorOccurred: this.hooks.onErrorOccurred,
 };

The input shape can mirror PostToolUseHookInput (toolName + toolArgs + toolResult), since the CLI's emit site already provides the same payload.

Environment

• @github/copilot 1.0.43-0 (Windows win32-x64 package).
• Bundled SDK at <install>/copilot-sdk/extension.js.
• Confirmed by inspecting the shipped JS and the TypeScript declarations in the same package.

[github-actions]

Investigation findings: confirmed bug 🐛

I've verified this is a genuine bug by inspecting the relevant source files.

What I investigated

nodejs/src/types.ts — SessionHooks interface (lines 1018–1048):
The interface declares exactly 6 handlers: onPreToolUse, onPostToolUse, onUserPromptSubmitted, onSessionStart, onSessionEnd, onErrorOccurred. There is no onPostToolUseFailure declaration anywhere in the file.

nodejs/src/session.ts — _handleHooksInvoke (lines 885–917):
The handlerMap inside the dispatcher maps exactly those same 6 hook type strings. postToolUseFailure is not present. When the CLI sends a hooks.invoke RPC call with hookType: "postToolUseFailure", the lookup produces undefined and the method silently returns without calling any handler.

What I found

The bug is exactly as described:

1. The Copilot CLI does emit postToolUseFailure hook events to connected extensions over IPC (the CLI's createHooksProxy and processToolExecutionResult confirm this, as detailed in the issue).
2. The SDK's _handleHooksInvoke dispatch table has no entry for "postToolUseFailure", so all such events are silently swallowed.
3. The SessionHooks TypeScript interface has no onPostToolUseFailure property, so extension authors cannot even declare a handler that would work if the dispatch were fixed.

There is no PostToolUseFailureHandler type or any related type in types.ts, so the fix requires both a new type and wiring it up in the dispatch map.

Root cause

postToolUseFailure was added to the CLI's hook proxy but the corresponding handler slot was never added to the SDK extension surface (SessionHooks) or its runtime dispatcher (_handleHooksInvoke).

Label applied: bug

This is a clear implementation gap — the protocol sends events the SDK cannot receive. The suggested fix in the issue (add onPostToolUseFailure to SessionHooks and to handlerMap) is correct and sufficient.

Generated by Bug Handler for issue #1220 · ● 283.8K · ◷