@introspection-sdk/introspection-node 0.20.0 → 0.21.1

package/src/otel/claude-hooks.ts

@@ -1,1116 +0,0 @@
-/**
- * Claude Agent SDK Instrumentation Hooks
- *
- * Provides OpenTelemetry instrumentation for the Claude Agent SDK via its hooks system.
- * Creates spans for sessions, tool uses, and subagent executions with gen_ai.* attributes.
- *
- * @see https://platform.claude.com/docs/en/agent-sdk/typescript
- */
-
-import {
-  context as otelContext,
-  propagation,
-  trace as otelTrace,
-  Span as OtelSpan,
-  SpanKind,
-  SpanStatusCode,
-  type Attributes,
-} from "@opentelemetry/api";
-import {
-  BasicTracerProvider,
-  BatchSpanProcessor,
-  SimpleSpanProcessor,
-  type SpanExporter,
-  type IdGenerator,
-} from "@opentelemetry/sdk-trace-base";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import {
-  resourceFromAttributes,
-  defaultResource,
-} from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-
-import { logger, withOtlpHttpsProxy } from "../utils.js";
-import { VERSION } from "../version.js";
-import {
-  convertClaudeSessionToOtelAttributes,
-  type ClaudeContentBlock,
-} from "../converters/claude.js";
-
-// ---------------------------------------------------------------------------
-// Claude Agent SDK Hook types
-// Defined locally to avoid requiring the SDK as a compile-time dependency.
-// ---------------------------------------------------------------------------
-
-/** Common fields present on every hook input payload. */
-export interface BaseHookInput {
-  /** Active session identifier. */
-  session_id: string;
-  /** Path to the session transcript file. */
-  transcript_path: string;
-  /** Working directory of the agent process. */
-  cwd: string;
-  /** Permission mode the session is running in. */
-  permission_mode?: string;
-}
-
-/** Input payload for the `SessionStart` hook. */
-export interface SessionStartHookInput extends BaseHookInput {
-  hook_event_name: "SessionStart";
-  /** How the session was initiated. */
-  source: "startup" | "resume" | "clear" | "compact";
-  /** Agent type (e.g. `"main"`, `"subagent"`). */
-  agent_type?: string;
-  /** Model used for this session. */
-  model?: string;
-}
-
-/** Input payload for the `SessionEnd` hook. */
-export interface SessionEndHookInput extends BaseHookInput {
-  hook_event_name: "SessionEnd";
-  /** Reason the session ended. */
-  reason: string;
-}
-
-/** Input payload for the `PreToolUse` hook. */
-export interface PreToolUseHookInput extends BaseHookInput {
-  hook_event_name: "PreToolUse";
-  /** Name of the tool about to be invoked. */
-  tool_name: string;
-  /** Input data passed to the tool. */
-  tool_input: unknown;
-  /** Unique identifier for this tool invocation. */
-  tool_use_id: string;
-}
-
-/** Input payload for the `PostToolUse` hook. */
-export interface PostToolUseHookInput extends BaseHookInput {
-  hook_event_name: "PostToolUse";
-  /** Name of the tool that was invoked. */
-  tool_name: string;
-  /** Input data that was passed to the tool. */
-  tool_input: unknown;
-  /** Response returned by the tool. */
-  tool_response: unknown;
-  /** Unique identifier for this tool invocation. */
-  tool_use_id: string;
-}
-
-/** Input payload for the `SubagentStart` hook. */
-export interface SubagentStartHookInput extends BaseHookInput {
-  hook_event_name: "SubagentStart";
-  /** Identifier of the sub-agent. */
-  agent_id: string;
-  /** Type / name of the sub-agent. */
-  agent_type: string;
-}
-
-/** Input payload for the `SubagentStop` hook. */
-export interface SubagentStopHookInput extends BaseHookInput {
-  hook_event_name: "SubagentStop";
-  /** Identifier of the sub-agent. */
-  agent_id: string;
-  /** Type / name of the sub-agent. */
-  agent_type: string;
-  /** Path to the sub-agent's transcript. */
-  agent_transcript_path: string;
-}
-
-/** Discriminated union of all possible hook input payloads. */
-export type ClaudeHookInput =
-  | SessionStartHookInput
-  | SessionEndHookInput
-  | PreToolUseHookInput
-  | PostToolUseHookInput
-  | SubagentStartHookInput
-  | SubagentStopHookInput;
-
-/**
- * JSON-serialisable output returned by a hook callback
- * (`SyncHookJSONOutput` in the SDK).
- */
-export type ClaudeHookOutput = {
-  /** Whether the SDK should continue processing. */
-  continue?: boolean;
-  /** Suppress the default output for this hook event. */
-  suppressOutput?: boolean;
-  /** Reason to stop the session. */
-  stopReason?: string;
-  /** Approval decision for `PreToolUse` hooks. */
-  decision?: "approve" | "block";
-  /** System message to inject into the conversation. */
-  systemMessage?: string;
-  /** Human-readable reason for the decision. */
-  reason?: string;
-};
-
-/**
- * Async callback signature for a Claude Agent SDK hook.
- *
- * @param input - The hook input payload.
- * @param toolUseID - The tool-use ID (set for `PreToolUse` / `PostToolUse`).
- * @param options - Abort signal for cancellation.
- * @returns A {@link ClaudeHookOutput} controlling the SDK's behaviour.
- */
-export type ClaudeHookCallback = (
-  input: ClaudeHookInput,
-  toolUseID: string | undefined,
-  options: { signal: AbortSignal },
-) => Promise<ClaudeHookOutput>;
-
-/** Pairs an optional glob matcher with one or more hook callbacks. */
-export interface ClaudeHookCallbackMatcher {
-  /** Glob pattern to match tool names (only relevant for tool hooks). */
-  matcher?: string;
-  /** Callbacks to invoke when the matcher (or all events) match. */
-  hooks: ClaudeHookCallback[];
-  /** Timeout in milliseconds for hook execution. */
-  timeout?: number;
-}
-
-/** String literal union of all Claude Agent SDK hook event names. */
-export type ClaudeHookEvent =
-  | "PreToolUse"
-  | "PostToolUse"
-  | "SessionStart"
-  | "SessionEnd"
-  | "SubagentStart"
-  | "SubagentStop";
-
-/**
- * Full hooks configuration object accepted by the Claude Agent SDK
- * `query()` options. Maps each event name to an array of
- * {@link ClaudeHookCallbackMatcher} entries.
- */
-export type ClaudeHooksConfig = Partial<
-  Record<ClaudeHookEvent, ClaudeHookCallbackMatcher[]>
->;
-
-// ---------------------------------------------------------------------------
-// Claude Agent SDK message types (for extracting usage info)
-// ---------------------------------------------------------------------------
-
-/** Token-level usage counters reported by the Claude API. */
-export interface ClaudeUsage {
-  /** Number of input tokens consumed. */
-  input_tokens: number;
-  /** Number of output tokens generated. */
-  output_tokens: number;
-  /** Tokens used to create new cache entries. */
-  cache_creation_input_tokens?: number;
-  /** Tokens read from cache. */
-  cache_read_input_tokens?: number;
-}
-
-/** Per-model usage breakdown reported in a result message. */
-export interface ClaudeModelUsage {
-  /** Input tokens for this model. */
-  inputTokens: number;
-  /** Output tokens for this model. */
-  outputTokens: number;
-  /** Tokens read from cache for this model. */
-  cacheReadInputTokens: number;
-  /** Tokens used to create cache for this model. */
-  cacheCreationInputTokens: number;
-  /** Estimated cost in USD for this model. */
-  costUSD: number;
-}
-
-/** A `"result"` message yielded at the end of a `query()` stream. */
-export interface ClaudeResultMessage {
-  type: "result";
-  /** Aggregate token usage for the session. */
-  usage?: ClaudeUsage;
-  /** Total estimated cost in USD. */
-  total_cost_usd?: number;
-  /** Per-model usage breakdown. */
-  modelUsage?: Record<string, ClaudeModelUsage>;
-  /** Final text result (if any). */
-  result?: string;
-  /** Whether the session ended with an error. */
-  is_error?: boolean;
-  /** Session identifier. */
-  session_id: string;
-}
-
-/** An `"assistant"` message yielded during a `query()` stream. */
-export interface ClaudeAssistantMessage {
-  type: "assistant";
-  /** The underlying API message with optional usage and content. */
-  message?: {
-    id?: string;
-    model?: string;
-    usage?: {
-      input_tokens?: number;
-      output_tokens?: number;
-      cache_read_input_tokens?: number;
-      cache_creation_input_tokens?: number;
-    };
-    content?: Array<{ type: string; text?: string }>;
-  };
-  /** Session identifier. */
-  session_id: string;
-}
-
-/**
- * Discriminated union of all messages that can be yielded by a Claude Agent
- * SDK `query()` stream.
- */
-export type ClaudeSDKMessage =
-  | ClaudeResultMessage
-  | ClaudeAssistantMessage
-  | { type: string; session_id?: string };
-
-/** Advanced options for testing and customization of {@link IntrospectionClaudeHooks}. */
-export interface ClaudeHooksAdvancedOptions {
-  /** Custom span exporter (for testing) */
-  spanExporter?: SpanExporter;
-  /** Custom ID generator (for testing) */
-  idGenerator?: IdGenerator;
-  /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing) */
-  useSimpleSpanProcessor?: boolean;
-}
-
-/** Configuration for {@link IntrospectionClaudeHooks}. */
-export interface IntrospectionClaudeHooksOptions {
-  /** Authentication token (env: INTROSPECTION_TOKEN) */
-  token?: string;
-  /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL) */
-  baseUrl?: string;
-  /** Service name for the OTel resource (defaults to "claude-agent") */
-  serviceName?: string;
-  /** Agent name set on session spans as gen_ai.agent.name (defaults to serviceName) */
-  agentName?: string;
-  /** Agent ID set on session spans as gen_ai.agent.id */
-  agentId?: string;
-  /** Conversation ID set on session spans as gen_ai.conversation.id */
-  conversationId?: string;
-  /** Additional headers to include in requests */
-  additionalHeaders?: Record<string, string>;
-  /** Advanced options for testing and customization */
-  advanced?: ClaudeHooksAdvancedOptions;
-}
-
-/**
- * Provides instrumented hooks for Claude Agent SDK.
- *
- * Creates OpenTelemetry spans with gen_ai.* semantic convention attributes:
- * - Session spans: gen_ai.provider.name, gen_ai.request.model
- * - Tool spans: gen_ai.tool.name, gen_ai.tool.call.arguments, gen_ai.tool.call.result
- * - Subagent spans: gen_ai.agent.name
- *
- * Usage tracking is captured from streamed messages via recordUsage().
- *
- * @example
- * ```typescript
- * import { query } from "@anthropic-ai/claude-agent-sdk";
- * import { IntrospectionClaudeHooks } from "@introspection-sdk/introspection-node";
- *
- * const hooks = new IntrospectionClaudeHooks();
- *
- * const stream = query({
- *   prompt: "Hello",
- *   options: {
- *     hooks: hooks.getHooks(),
- *   },
- * });
- *
- * for await (const message of stream) {
- *   hooks.recordUsage(message);
- *   // handle message...
- * }
- *
- * await hooks.shutdown();
- * ```
- */
-export class IntrospectionClaudeHooks {
-  private _tracerProvider: BasicTracerProvider;
-  private _tracer: ReturnType<BasicTracerProvider["getTracer"]>;
-  private _agentName: string;
-  private _agentId?: string;
-  private _conversationId?: string;
-  private _sessionSpans: Map<string, OtelSpan> = new Map();
-  private _toolSpans: Map<string, OtelSpan> = new Map();
-  private _subagentSpans: Map<string, OtelSpan> = new Map();
-  private _sessionUsage: Map<
-    string,
-    {
-      input: number;
-      output: number;
-      cacheRead: number;
-      cacheCreation: number;
-      cost?: number;
-      model?: string;
-      inputPrompt?: string;
-      responseContent?: string;
-      responseBlocks?: ClaudeContentBlock[];
-      stopReason?: string;
-      responseId?: string;
-      toolNames?: string[];
-      systemInstructions?: string;
-    }
-  > = new Map();
-
-  constructor(options: IntrospectionClaudeHooksOptions = {}) {
-    const advanced = options.advanced;
-    const serviceName = options.serviceName || "claude-agent";
-    this._agentName = options.agentName || serviceName;
-    this._agentId = options.agentId;
-    this._conversationId = options.conversationId;
-    const resource = defaultResource().merge(
-      resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName }),
-    );
-
-    if (!advanced?.spanExporter) {
-      const token = options.token || process.env.INTROSPECTION_TOKEN;
-      if (!token) {
-        throw new Error("INTROSPECTION_TOKEN is required");
-      }
-
-      const baseUrl =
-        options.baseUrl ||
-        process.env.INTROSPECTION_BASE_OTEL_URL ||
-        "https://otel.introspection.dev";
-
-      const headers: Record<string, string> = {
-        "User-Agent": `introspection-sdk/${VERSION}`,
-        Authorization: `Bearer ${token}`,
-        ...options.additionalHeaders,
-      };
-
-      const endpoint = baseUrl.endsWith("/v1/traces")
-        ? baseUrl
-        : `${baseUrl.replace(/\/$/, "")}/v1/traces`;
-
-      logger.info(
-        `IntrospectionClaudeHooks initialized: service=${serviceName}, endpoint=${endpoint}`,
-      );
-
-      const spanExporter = new OTLPTraceExporter(
-        withOtlpHttpsProxy({
-          url: endpoint,
-          headers,
-        }),
-      );
-
-      // Default to sequential export for dev/staging tokens.
-      const useSimple =
-        advanced?.useSimpleSpanProcessor ||
-        token.startsWith("intro_dev") ||
-        token.startsWith("intro_staging");
-      const spanProcessor = useSimple
-        ? new SimpleSpanProcessor(spanExporter)
-        : new BatchSpanProcessor(spanExporter, { scheduledDelayMillis: 1000 });
-
-      this._tracerProvider = new BasicTracerProvider({
-        resource,
-        idGenerator: advanced?.idGenerator,
-        spanProcessors: [spanProcessor],
-      });
-    } else {
-      logger.info(
-        `IntrospectionClaudeHooks initialized in test mode with custom exporter`,
-      );
-
-      const spanProcessor = advanced.useSimpleSpanProcessor
-        ? new SimpleSpanProcessor(advanced.spanExporter)
-        : new BatchSpanProcessor(advanced.spanExporter, {
-            scheduledDelayMillis: 100,
-          });
-
-      this._tracerProvider = new BasicTracerProvider({
-        resource,
-        idGenerator: advanced.idGenerator,
-        spanProcessors: [spanProcessor],
-      });
-    }
-
-    this._tracer = this._tracerProvider.getTracer("claude-agent-sdk", VERSION);
-  }
-
-  /**
-   * Build the hooks configuration object to pass to Claude Agent SDK
-   * `query()` options.
-   *
-   * @returns A {@link ClaudeHooksConfig} wired to this instance's tracing.
-   */
-  getHooks(): ClaudeHooksConfig {
-    return {
-      SessionStart: [
-        {
-          hooks: [this._onSessionStart.bind(this)],
-        },
-      ],
-      SessionEnd: [
-        {
-          hooks: [this._onSessionEnd.bind(this)],
-        },
-      ],
-      PreToolUse: [
-        {
-          hooks: [this._onPreToolUse.bind(this)],
-        },
-      ],
-      PostToolUse: [
-        {
-          hooks: [this._onPostToolUse.bind(this)],
-        },
-      ],
-      SubagentStart: [
-        {
-          hooks: [this._onSubagentStart.bind(this)],
-        },
-      ],
-      SubagentStop: [
-        {
-          hooks: [this._onSubagentStop.bind(this)],
-        },
-      ],
-    };
-  }
-
-  /**
-   * Resolve effective agent / conversation identity for a session, in order
-   * of precedence: OTel baggage on the active context > constructor option >
-   * the Claude session ID. Lets callers override identity per-invocation via
-   * `IntrospectionClient.withAgent()` / `.withConversation()` without
-   * having to construct a new hooks instance per call.
-   *
-   * Requires an active context manager — see {@link setupTracing}.
-   */
-  private _resolveIdentity(sessionId: string): {
-    agentName: string;
-    agentId?: string;
-    conversationId: string;
-  } {
-    const baggage = propagation.getBaggage(otelContext.active());
-    const baggageAgentName = baggage?.getEntry("gen_ai.agent.name")?.value;
-    const baggageAgentId = baggage?.getEntry("gen_ai.agent.id")?.value;
-    const baggageConvId = baggage?.getEntry("gen_ai.conversation.id")?.value;
-
-    return {
-      agentName: baggageAgentName || this._agentName,
-      agentId: baggageAgentId || this._agentId,
-      conversationId: baggageConvId || this._conversationId || sessionId,
-    };
-  }
-
-  /**
-   * Set the input prompt for a session so it appears as
-   * `gen_ai.input.messages` on the session span.
-   *
-   * If `sessionId` is not provided the prompt is buffered and associated
-   * with the next session that starts via an `init` message.
-   *
-   * @param prompt - The user prompt string passed to `query()`.
-   * @param sessionId - Optional session ID if already known.
-   */
-  setInputPrompt(prompt: string, sessionId?: string): void {
-    if (sessionId) {
-      const existing = this._sessionUsage.get(sessionId) || {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheCreation: 0,
-      };
-      existing.inputPrompt = prompt;
-      this._sessionUsage.set(sessionId, existing);
-    } else {
-      // Store for when session starts
-      this._pendingInputPrompt = prompt;
-    }
-  }
-
-  private _pendingInputPrompt?: string;
-
-  /**
-   * Set system instructions for a session so they appear as
-   * `gen_ai.system_instructions` on the session span.
-   *
-   * If `sessionId` is not provided the value is buffered and associated
-   * with the next session that starts via an `init` message.
-   *
-   * @param instructions - The system prompt / instructions string.
-   * @param sessionId - Optional session ID if already known.
-   */
-  setSystemInstructions(instructions: string, sessionId?: string): void {
-    if (sessionId) {
-      const existing = this._sessionUsage.get(sessionId) || {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheCreation: 0,
-      };
-      existing.systemInstructions = instructions;
-      this._sessionUsage.set(sessionId, existing);
-    } else {
-      this._pendingSystemInstructions = instructions;
-    }
-    logger.info(
-      `System instructions set (${instructions.length} chars)${sessionId ? ` for session ${sessionId}` : " (pending)"}`,
-    );
-  }
-
-  private _pendingSystemInstructions?: string;
-
-  /**
-   * Record usage from a streamed SDK message.
-   *
-   * Call this for **every** message yielded by `query()` to capture token
-   * usage. Session spans are automatically created on `init` messages and
-   * ended on `result` messages.
-   *
-   * @param message - A {@link ClaudeSDKMessage} yielded by the `query()` stream.
-   */
-  recordUsage(message: ClaudeSDKMessage): void {
-    const sessionId = message.session_id || "default";
-    const msg = message as Record<string, unknown>;
-
-    // Handle system init message - start session span
-    if (message.type === "system" && msg.subtype === "init") {
-      this._startSessionFromMessage(sessionId, msg);
-      return;
-    }
-
-    if (message.type === "assistant") {
-      const assistantMsg = message as ClaudeAssistantMessage;
-      const existing = this._sessionUsage.get(sessionId) || {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheCreation: 0,
-      };
-
-      // Track usage
-      const usage = assistantMsg.message?.usage;
-      if (usage) {
-        existing.input += usage.input_tokens || 0;
-        existing.output += usage.output_tokens || 0;
-        existing.cacheRead += usage.cache_read_input_tokens || 0;
-        existing.cacheCreation += usage.cache_creation_input_tokens || 0;
-        if (assistantMsg.message?.model) {
-          existing.model = assistantMsg.message.model;
-        }
-        logger.debug(
-          `Recorded usage for session ${sessionId}: +${usage.input_tokens || 0} input, +${usage.output_tokens || 0} output`,
-        );
-      }
-
-      // Capture response ID from assistant message
-      if (assistantMsg.message?.id) {
-        existing.responseId = assistantMsg.message.id;
-      }
-
-      // Extract response content from assistant message
-      const content = assistantMsg.message?.content;
-      if (content && Array.isArray(content)) {
-        // Store content blocks for proper conversion
-        existing.responseBlocks = [
-          ...(existing.responseBlocks || []),
-          ...(content as ClaudeContentBlock[]),
-        ];
-        // Also extract text for backwards compatibility
-        const textContent = content
-          .filter((block) => block.type === "text" && block.text)
-          .map((block) => block.text)
-          .join("");
-        if (textContent) {
-          existing.responseContent =
-            (existing.responseContent || "") + textContent;
-        }
-      }
-
-      this._sessionUsage.set(sessionId, existing);
-    } else if (message.type === "result") {
-      const resultMsg = message as ClaudeResultMessage;
-      const existing = this._sessionUsage.get(sessionId) || {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheCreation: 0,
-      };
-
-      if (resultMsg.usage) {
-        // Result message has final totals
-        existing.input = resultMsg.usage.input_tokens || existing.input;
-        existing.output = resultMsg.usage.output_tokens || existing.output;
-        if (resultMsg.usage.cache_read_input_tokens != null) {
-          existing.cacheRead = resultMsg.usage.cache_read_input_tokens;
-        }
-        if (resultMsg.usage.cache_creation_input_tokens != null) {
-          existing.cacheCreation = resultMsg.usage.cache_creation_input_tokens;
-        }
-      }
-      // Fallback: aggregate cache tokens from per-model breakdown when top-level usage omits them
-      if (
-        resultMsg.modelUsage &&
-        existing.cacheRead === 0 &&
-        existing.cacheCreation === 0
-      ) {
-        for (const modelData of Object.values(resultMsg.modelUsage)) {
-          existing.cacheRead += modelData.cacheReadInputTokens || 0;
-          existing.cacheCreation += modelData.cacheCreationInputTokens || 0;
-        }
-      }
-      if (resultMsg.total_cost_usd !== undefined) {
-        existing.cost = resultMsg.total_cost_usd;
-      }
-
-      // Capture stop reason from result subtype
-      const subtype = msg.subtype as string | undefined;
-      if (subtype) {
-        existing.stopReason = subtype;
-      }
-
-      this._sessionUsage.set(sessionId, existing);
-      logger.debug(
-        `Recorded final usage for session ${sessionId}: ${existing.input} input, ${existing.output} output, $${existing.cost || 0}`,
-      );
-
-      // End session span on result message
-      this._endSessionFromMessage(sessionId, msg);
-    }
-  }
-
-  /**
-   * Start a session span from an init system message.
-   * This provides an alternative to the SessionStart hook which has timing issues.
-   */
-  private _startSessionFromMessage(
-    sessionId: string,
-    msg: Record<string, unknown>,
-  ): void {
-    // Don't create duplicate spans if hook already created one
-    if (this._sessionSpans.has(sessionId)) {
-      logger.debug(`Session span already exists for ${sessionId}, skipping`);
-      return;
-    }
-
-    logger.debug(`Starting session span from init message: ${sessionId}`);
-    const ids = this._resolveIdentity(sessionId);
-    const attrs: Attributes = {
-      "gen_ai.provider.name": "anthropic",
-      "gen_ai.operation.name": "chat",
-      "gen_ai.agent.name": ids.agentName,
-      "gen_ai.conversation.id": ids.conversationId,
-      "claude.session_id": sessionId,
-      "claude.source": "message",
-    };
-
-    if (ids.agentId) {
-      attrs["gen_ai.agent.id"] = ids.agentId;
-    }
-
-    const span = this._tracer.startSpan("claude.session", {
-      kind: SpanKind.CLIENT,
-      attributes: attrs,
-    });
-
-    // Add model if present in init message
-    const model = msg.model as string | undefined;
-    if (model) {
-      span.setAttribute("gen_ai.request.model", model);
-    }
-
-    // Add tools if present
-    const tools = msg.tools as string[] | undefined;
-    if (tools && tools.length > 0) {
-      span.setAttribute("claude.tools", tools.join(","));
-      span.setAttribute(
-        "gen_ai.tool.definitions",
-        JSON.stringify(tools.map((name) => ({ name }))),
-      );
-    }
-
-    this._sessionSpans.set(sessionId, span);
-
-    // Initialize session usage, including any pending input prompt and system instructions
-    const sessionData: {
-      input: number;
-      output: number;
-      cacheRead: number;
-      cacheCreation: number;
-      model?: string;
-      inputPrompt?: string;
-      responseContent?: string;
-      toolNames?: string[];
-      systemInstructions?: string;
-    } = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, model };
-
-    if (tools && tools.length > 0) {
-      sessionData.toolNames = tools;
-    }
-
-    if (this._pendingInputPrompt) {
-      sessionData.inputPrompt = this._pendingInputPrompt;
-      this._pendingInputPrompt = undefined;
-    }
-
-    if (this._pendingSystemInstructions) {
-      sessionData.systemInstructions = this._pendingSystemInstructions;
-      this._pendingSystemInstructions = undefined;
-    }
-
-    this._sessionUsage.set(sessionId, sessionData);
-    logger.info(`Created session span for ${sessionId}`);
-  }
-
-  /**
-   * End a session span from a result message.
-   * This provides an alternative to the SessionEnd hook which has timing issues.
-   */
-  private _endSessionFromMessage(
-    sessionId: string,
-    msg: Record<string, unknown>,
-  ): void {
-    const span = this._sessionSpans.get(sessionId);
-    if (!span) {
-      logger.debug(`No session span found for ${sessionId}, nothing to end`);
-      return;
-    }
-
-    const usage = this._sessionUsage.get(sessionId);
-
-    // Use converter to set GenAI semantic convention attributes
-    const otelAttrs = convertClaudeSessionToOtelAttributes({
-      sessionId,
-      inputPrompt: usage?.inputPrompt,
-      responseContent: usage?.responseContent,
-      responseBlocks: usage?.responseBlocks,
-      model: usage?.model,
-      inputTokens: usage?.input,
-      outputTokens: usage?.output,
-      cacheReadInputTokens: usage?.cacheRead || undefined,
-      cacheCreationInputTokens: usage?.cacheCreation || undefined,
-      costUsd: usage?.cost,
-      stopReason: usage?.stopReason,
-      responseId: usage?.responseId,
-      toolNames: usage?.toolNames,
-      systemInstructions: usage?.systemInstructions,
-    });
-
-    // Apply all converted attributes to the span
-    for (const [key, value] of Object.entries(otelAttrs)) {
-      span.setAttribute(key, value);
-    }
-
-    // Set subtype/reason from result message
-    const subtype = msg.subtype as string | undefined;
-    if (subtype) {
-      span.setAttribute("claude.result_subtype", subtype);
-      if (subtype === "success") {
-        span.setStatus({ code: SpanStatusCode.OK });
-      } else {
-        span.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: subtype,
-        });
-      }
-    } else {
-      span.setStatus({ code: SpanStatusCode.OK });
-    }
-
-    span.end();
-    this._sessionSpans.delete(sessionId);
-    this._sessionUsage.delete(sessionId);
-    logger.info(
-      `Ended session span for ${sessionId}: ${usage?.input || 0} input, ${usage?.output || 0} output tokens`,
-    );
-  }
-
-  private async _onSessionStart(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const sessionInput = input as SessionStartHookInput;
-    logger.debug(`SessionStart hook: ${sessionInput.session_id}`);
-
-    // Resolve identity via _resolveIdentity so baggage on the active context
-    // takes precedence over constructor defaults, matching the message-init
-    // path in _startSessionFromMessage. Without this, the SessionStart hook
-    // would always stamp the constructor-time agentName / sessionId even
-    // when the caller wrapped the query in withAgent() / withConversation().
-    const ids = this._resolveIdentity(sessionInput.session_id);
-    const attrs: Attributes = {
-      "gen_ai.provider.name": "anthropic",
-      "gen_ai.operation.name": "chat",
-      "gen_ai.agent.name": ids.agentName,
-      "gen_ai.conversation.id": ids.conversationId,
-      "claude.session_id": sessionInput.session_id,
-      "claude.source": sessionInput.source,
-    };
-    if (ids.agentId) {
-      attrs["gen_ai.agent.id"] = ids.agentId;
-    }
-
-    const span = this._tracer.startSpan("claude.session", {
-      kind: SpanKind.CLIENT,
-      attributes: attrs,
-    });
-
-    if (sessionInput.model) {
-      span.setAttribute("gen_ai.request.model", sessionInput.model);
-    }
-    if (sessionInput.agent_type) {
-      span.setAttribute("claude.agent_type", sessionInput.agent_type);
-    }
-
-    this._sessionSpans.set(sessionInput.session_id, span);
-
-    // Initialize session usage, consuming any pending prompts/instructions
-    const sessionUsage: {
-      input: number;
-      output: number;
-      cacheRead: number;
-      cacheCreation: number;
-      inputPrompt?: string;
-      systemInstructions?: string;
-    } = {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheCreation: 0,
-    };
-    if (this._pendingInputPrompt) {
-      sessionUsage.inputPrompt = this._pendingInputPrompt;
-      this._pendingInputPrompt = undefined;
-    }
-    if (this._pendingSystemInstructions) {
-      sessionUsage.systemInstructions = this._pendingSystemInstructions;
-      this._pendingSystemInstructions = undefined;
-    }
-    this._sessionUsage.set(sessionInput.session_id, sessionUsage);
-
-    return { continue: true };
-  }
-
-  private async _onSessionEnd(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const sessionInput = input as SessionEndHookInput;
-    logger.debug(`SessionEnd hook: ${sessionInput.session_id}`);
-
-    const span = this._sessionSpans.get(sessionInput.session_id);
-    if (span) {
-      const usage = this._sessionUsage.get(sessionInput.session_id);
-      if (usage) {
-        // Use converter for consistent gen_ai attribute mapping
-        const otelAttrs = convertClaudeSessionToOtelAttributes({
-          sessionId: sessionInput.session_id,
-          inputPrompt: usage.inputPrompt,
-          responseContent: usage.responseContent,
-          responseBlocks: usage.responseBlocks,
-          model: usage.model,
-          inputTokens: usage.input,
-          outputTokens: usage.output,
-          cacheReadInputTokens: usage.cacheRead || undefined,
-          cacheCreationInputTokens: usage.cacheCreation || undefined,
-          costUsd: usage.cost,
-          stopReason: usage.stopReason,
-          responseId: usage.responseId,
-          toolNames: usage.toolNames,
-          systemInstructions: usage.systemInstructions,
-        });
-        for (const [key, value] of Object.entries(otelAttrs)) {
-          span.setAttribute(key, value);
-        }
-      }
-
-      span.setAttribute("claude.exit_reason", sessionInput.reason);
-      span.setStatus({ code: SpanStatusCode.OK });
-      span.end();
-      this._sessionSpans.delete(sessionInput.session_id);
-      this._sessionUsage.delete(sessionInput.session_id);
-      logger.debug(`Ended session span for ${sessionInput.session_id}`);
-    }
-
-    return { continue: true };
-  }
-
-  private async _onPreToolUse(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const toolInput = input as PreToolUseHookInput;
-    logger.debug(
-      `PreToolUse: ${toolInput.tool_name} (${toolInput.tool_use_id})`,
-    );
-
-    const parentSpan = this._sessionSpans.get(toolInput.session_id);
-    const ctx = parentSpan
-      ? otelTrace.setSpan(otelContext.active(), parentSpan)
-      : undefined;
-
-    const span = this._tracer.startSpan(
-      `execute_tool ${toolInput.tool_name}`,
-      {
-        kind: SpanKind.INTERNAL,
-        attributes: {
-          "gen_ai.operation.name": "execute_tool",
-          "gen_ai.tool.name": toolInput.tool_name,
-          "gen_ai.tool.type": "function",
-          "gen_ai.tool.call.id": toolInput.tool_use_id,
-          "claude.session_id": toolInput.session_id,
-          "claude.tool_use_id": toolInput.tool_use_id,
-        },
-      },
-      ctx,
-    );
-
-    if (toolInput.tool_input) {
-      try {
-        span.setAttribute(
-          "gen_ai.tool.call.arguments",
-          JSON.stringify(toolInput.tool_input),
-        );
-      } catch {
-        span.setAttribute(
-          "gen_ai.tool.call.arguments",
-          String(toolInput.tool_input),
-        );
-      }
-    }
-
-    this._toolSpans.set(toolInput.tool_use_id, span);
-
-    return { continue: true };
-  }
-
-  private async _onPostToolUse(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const toolInput = input as PostToolUseHookInput;
-    logger.debug(
-      `PostToolUse: ${toolInput.tool_name} (${toolInput.tool_use_id})`,
-    );
-
-    const span = this._toolSpans.get(toolInput.tool_use_id);
-
-    if (span) {
-      if (toolInput.tool_response !== undefined) {
-        try {
-          span.setAttribute(
-            "gen_ai.tool.call.result",
-            JSON.stringify(toolInput.tool_response),
-          );
-        } catch {
-          span.setAttribute(
-            "gen_ai.tool.call.result",
-            String(toolInput.tool_response),
-          );
-        }
-      }
-      span.end();
-      this._toolSpans.delete(toolInput.tool_use_id);
-    }
-
-    return { continue: true };
-  }
-
-  private async _onSubagentStart(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const subagentInput = input as SubagentStartHookInput;
-    logger.debug(
-      `SubagentStart: ${subagentInput.agent_type} (${subagentInput.agent_id})`,
-    );
-
-    const parentSpan = this._sessionSpans.get(subagentInput.session_id);
-    const ctx = parentSpan
-      ? otelTrace.setSpan(otelContext.active(), parentSpan)
-      : undefined;
-
-    const span = this._tracer.startSpan(
-      `subagent.${subagentInput.agent_type}`,
-      {
-        kind: SpanKind.INTERNAL,
-        attributes: {
-          "gen_ai.agent.name": subagentInput.agent_type,
-          "claude.session_id": subagentInput.session_id,
-          "claude.agent_id": subagentInput.agent_id,
-        },
-      },
-      ctx,
-    );
-
-    this._subagentSpans.set(subagentInput.agent_id, span);
-
-    return { continue: true };
-  }
-
-  private async _onSubagentStop(
-    input: ClaudeHookInput,
-    _toolUseID?: string,
-    _options?: { signal: AbortSignal },
-  ): Promise<ClaudeHookOutput> {
-    void _toolUseID;
-    void _options;
-    const subagentInput = input as SubagentStopHookInput;
-    logger.debug(
-      `SubagentStop: ${subagentInput.agent_type} (${subagentInput.agent_id})`,
-    );
-
-    const span = this._subagentSpans.get(subagentInput.agent_id);
-
-    if (span) {
-      span.setStatus({ code: SpanStatusCode.OK });
-      span.end();
-      this._subagentSpans.delete(subagentInput.agent_id);
-    }
-
-    return { continue: true };
-  }
-
-  /**
-   * Force-flush any buffered spans to the Introspection backend.
-   *
-   * @returns A promise that resolves once the flush completes.
-   */
-  async forceFlush(): Promise<void> {
-    await this._tracerProvider.forceFlush();
-  }
-
-  /**
-   * Shut down the hooks, ending any in-flight spans and flushing all
-   * pending data.
-   *
-   * @returns A promise that resolves once shutdown is complete.
-   */
-  async shutdown(): Promise<void> {
-    // End any remaining spans
-    for (const [, span] of this._sessionSpans) {
-      span.end();
-    }
-    for (const [, span] of this._toolSpans) {
-      span.end();
-    }
-    for (const [, span] of this._subagentSpans) {
-      span.end();
-    }
-
-    this._sessionSpans.clear();
-    this._toolSpans.clear();
-    this._subagentSpans.clear();
-    this._sessionUsage.clear();
-
-    await this._tracerProvider.shutdown();
-  }
-}