feat(telemetry): Phase 2 — tool.blocked_on_user + hook spans (#3731)

packages/core/src/core/toolHookTriggers.test.ts

@@ -215,7 +215,13 @@ describe('toolHookTriggers', () => {
         'auto',
       );
 
-      expect(result).toEqual({ shouldProceed: true });
+      // #4321 review: hookError surfaces the swallowed transport error so
+      // observers (telemetry spans, debug logs) can distinguish a failed
+      // hook from a successful "allow" decision.
+      expect(result).toEqual({
+        shouldProceed: true,
+        hookError: 'Network error',
+      });
     });
   });
 
@@ -338,7 +344,9 @@ describe('toolHookTriggers', () => {
         'auto',
       );
 
-      expect(result).toEqual({ shouldStop: false });
+      // #4321 review: hookError now surfaced to caller (see PreToolUse parallel test).
+      expect(result.shouldStop).toBe(false);
+      expect(result.hookError).toBeDefined();
     });
   });
 
@@ -429,7 +437,9 @@ describe('toolHookTriggers', () => {
         'error message',
       );
 
-      expect(result).toEqual({});
+      // #4321 review: hookError now surfaced to caller.
+      expect(result.hookError).toBeDefined();
+      expect(result.additionalContext).toBeUndefined();
     });
   });
 

packages/core/src/core/toolHookTriggers.ts

@@ -43,6 +43,14 @@ export interface PreToolUseHookResult {
   blockType?: 'denied' | 'ask' | 'stop';
   /** Additional context to add */
   additionalContext?: string;
+  /**
+   * Set when the hook helper caught and absorbed a transport / dispatch
+   * error. The tool execution still proceeds (existing non-blocking
+   * contract), but observers (telemetry spans, debug logs) can detect
+   * that the hook itself failed instead of treating the safe-default
+   * response as a successful "allow" decision (#4321 review).
+   */
+  hookError?: string;
 }
 
 /**
@@ -55,6 +63,8 @@ export interface PostToolUseHookResult {
   stopReason?: string;
   /** Additional context to append to tool response */
   additionalContext?: string;
+  /** See PreToolUseHookResult.hookError. */
+  hookError?: string;
 }
 
 /**
@@ -63,6 +73,8 @@ export interface PostToolUseHookResult {
 export interface PostToolUseFailureHookResult {
   /** Additional context about the failure */
   additionalContext?: string;
+  /** See PreToolUseHookResult.hookError. */
+  hookError?: string;
 }
 
 /**
@@ -107,7 +119,15 @@ export async function firePreToolUseHook(
     );
 
     if (!response.success || !response.output) {
-      return { shouldProceed: true };
+      // Hook runner reported failure (URL validation, fn exception,
+      // prompt-runner crash, ...). The `response.error` from the runner
+      // is the canonical cause — forward it so telemetry and operators
+      // see the actual failure instead of a fake "allow" success
+      // (#4321 review silent-failure-hunter HIGH).
+      const message = response.error?.message;
+      return message
+        ? { shouldProceed: true, hookError: message }
+        : { shouldProceed: true };
     }
 
     const preToolOutput = createHookOutput(
@@ -155,10 +175,9 @@ export async function firePreToolUseHook(
     };
   } catch (error) {
     // Hook errors should not block tool execution
-    debugLogger.warn(
-      `PreToolUse hook error for ${toolName}: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return { shouldProceed: true };
+    const message = error instanceof Error ? error.message : String(error);
+    debugLogger.warn(`PreToolUse hook error for ${toolName}: ${message}`);
+    return { shouldProceed: true, hookError: message };
   }
 }
 
@@ -207,7 +226,11 @@ export async function firePostToolUseHook(
     );
 
     if (!response.success || !response.output) {
-      return { shouldStop: false };
+      // See firePreToolUseHook for the rationale.
+      const message = response.error?.message;
+      return message
+        ? { shouldStop: false, hookError: message }
+        : { shouldStop: false };
     }
 
     const postToolOutput = createHookOutput(
@@ -232,10 +255,9 @@ export async function firePostToolUseHook(
     };
   } catch (error) {
     // Hook errors should not affect tool result
-    debugLogger.warn(
-      `PostToolUse hook error for ${toolName}: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return { shouldStop: false };
+    const message = error instanceof Error ? error.message : String(error);
+    debugLogger.warn(`PostToolUse hook error for ${toolName}: ${message}`);
+    return { shouldStop: false, hookError: message };
   }
 }
 
@@ -287,7 +309,9 @@ export async function firePostToolUseFailureHook(
     );
 
     if (!response.success || !response.output) {
-      return {};
+      // See firePreToolUseHook for the rationale.
+      const message = response.error?.message;
+      return message ? { hookError: message } : {};
     }
 
     const failureOutput = createHookOutput(
@@ -301,10 +325,11 @@ export async function firePostToolUseFailureHook(
     };
   } catch (error) {
     // Hook errors should not affect error handling
+    const message = error instanceof Error ? error.message : String(error);
     debugLogger.warn(
-      `PostToolUseFailure hook error for ${toolName}: ${error instanceof Error ? error.message : String(error)}`,
+      `PostToolUseFailure hook error for ${toolName}: ${message}`,
     );
-    return {};
+    return { hookError: message };
   }
 }
 

packages/core/src/telemetry/constants.ts

@@ -64,3 +64,7 @@ export const SPAN_INTERACTION = 'qwen-code.interaction';
 export const SPAN_LLM_REQUEST = 'qwen-code.llm_request';
 export const SPAN_TOOL = 'qwen-code.tool';
 export const SPAN_TOOL_EXECUTION = 'qwen-code.tool.execution';
+/** Brackets the time a tool spends in `awaiting_approval` waiting on the user. */
+export const SPAN_TOOL_BLOCKED_ON_USER = 'qwen-code.tool.blocked_on_user';
+/** Wraps each pre/post-tool-use hook fire site for per-hook latency / decision tracking. */
+export const SPAN_HOOK = 'qwen-code.hook';

packages/core/src/telemetry/index.ts

@@ -146,13 +146,22 @@ export {
   runInToolSpanContext,
   startToolExecutionSpan,
   endToolExecutionSpan,
+  startToolBlockedOnUserSpan,
+  endToolBlockedOnUserSpan,
+  startHookSpan,
+  endHookSpan,
   getActiveInteractionSpan,
 } from './session-tracing.js';
 export type {
   StartInteractionOptions,
   EndInteractionOptions,
   LLMRequestMetadata,
   ToolSpanMetadata,
+  ToolBlockedDecision,
+  ToolBlockedSource,
+  HookEvent,
+  StartHookSpanOptions,
+  HookSpanMetadata,
 } from './session-tracing.js';
 export {
   addUserPromptAttributes,