@ai-sdk/harness-claude-code 1.0.103 → 1.0.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-claude-code",
-  "version": "1.0.103",
+  "version": "1.0.105",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.99",
+    "@ai-sdk/harness": "1.0.101",
     "@ai-sdk/provider-utils": "5.0.36",
     "ws": "^8.21.0"
   },

package/src/bridge/create-emit-stream-event.ts

@@ -38,6 +38,9 @@ export type ClaudeMessage = {
     usage?: Record<string, unknown>;
   };
   result?: string;
+  /** Result-message error flags; distinct from `error_status` (`api_retry`). */
+  is_error?: boolean;
+  api_error_status?: number | null;
   errors?: ReadonlyArray<string>;
   usage?: Record<string, unknown>;
   total_cost_usd?: number;
@@ -246,6 +249,11 @@ export function createEmitStreamEvent({
             continue;
           }
           state.nativeToolCallNames.set(block.id, block.name);
+          if (block.name === 'AskUserQuestion') {
+            state.pendingStepToolUseIds.add(block.id);
+            opensStep = true;
+            continue;
+          }
           const dynamic = isExternalMcpTool(block.name);
           if (dynamic) state.externalMcpToolUseIds.add(block.id);
           if (state.approvalRequestedToolUseIds.has(block.id)) {
@@ -298,25 +306,15 @@ export function createEmitStreamEvent({
           const toolName = toCommonName(nativeName);
           const dynamic = state.externalMcpToolUseIds.delete(block.tool_use_id);
           const isError = !!block.is_error;
-          const content = stringifyContent(block.content);
-          /*
-           * Claude Code's Bash tool does not report the command's real
-           * numeric exit code — the SDK exposes only stdout/stderr text and
-           * an is_error flag. Consumers (and the example UI) render bash
-           * failures from an `exitCode` field on a structured result, the
-           * shape Codex's shell tool provides natively. When Claude omits
-           * `tool_use_result`, derive a binary code from is_error: 1 on
-           * failure, 0 on success. This fallback is a stand-in for
-           * failed/succeeded, not the process's true exit status.
-           */
-          const contentResult =
-            toolName === 'bash'
-              ? { exitCode: isError ? 1 : 0, stdout: content }
-              : dynamic
-                ? parseMcpToolResult(content)
-                : content;
           const result =
-            toolUseResult !== undefined ? toolUseResult : contentResult;
+            toolUseResult !== undefined
+              ? toolUseResult
+              : resolveToolResult({
+                  toolName,
+                  dynamic,
+                  isError,
+                  rawContent: block.content,
+                });
           emit({
             type: 'tool-result',
             toolCallId: block.tool_use_id,
@@ -438,6 +436,9 @@ function handleStreamEvent({
       if (nativeName === 'StructuredOutput') {
         return;
       }
+      if (nativeName === 'AskUserQuestion') {
+        return;
+      }
       const hostToolName = nativeName.startsWith(HOST_TOOL_PREFIX)
         ? nativeName.slice(HOST_TOOL_PREFIX.length)
         : undefined;
@@ -501,23 +502,61 @@ function handleStreamEvent({
   }
 }
 
+function isTextEntry(entry: unknown): entry is { text?: unknown } {
+  return entry != null && typeof entry === 'object' && 'text' in entry;
+}
+
 function stringifyContent(content: unknown): string {
   if (typeof content === 'string') return content;
   if (Array.isArray(content)) {
     return content
       .map(entry =>
-        entry && typeof entry === 'object' && 'text' in entry
-          ? String((entry as { text?: unknown }).text ?? '')
-          : JSON.stringify(entry),
+        isTextEntry(entry) ? String(entry.text ?? '') : JSON.stringify(entry),
       )
       .join('');
   }
   return JSON.stringify(content);
 }
 
+function hasNonTextContent(content: unknown): boolean {
+  return Array.isArray(content) && content.some(entry => !isTextEntry(entry));
+}
+
+function resolveToolResult({
+  toolName,
+  dynamic,
+  isError,
+  rawContent,
+}: {
+  toolName: string;
+  dynamic: boolean;
+  isError: boolean;
+  rawContent: unknown;
+}): unknown {
+  /*
+   * Claude Code's Bash tool does not report the command's real numeric exit
+   * code — the SDK exposes only stdout/stderr text and an is_error flag.
+   * Consumers (and the example UI) render bash failures from an `exitCode`
+   * field on a structured result, the shape Codex's shell tool provides
+   * natively. When Claude omits `tool_use_result`, derive a binary code from
+   * is_error: 1 on failure, 0 on success. This fallback is a stand-in for
+   * failed/succeeded, not the process's true exit status.
+   */
+  if (toolName === 'bash') {
+    return { exitCode: isError ? 1 : 0, stdout: stringifyContent(rawContent) };
+  }
+  // Must precede the MCP branch: flattening a non-text block to base64 text
+  // is not recoverable by parsing it back.
+  if (hasNonTextContent(rawContent)) return rawContent;
+  const content = stringifyContent(rawContent);
+  return dynamic ? parseMcpToolResult(content) : content;
+}
+
 function parseMcpToolResult(content: string): unknown {
   try {
-    return JSON.parse(content);
+    const parsed = JSON.parse(content);
+    // `JSON.parse` also succeeds on scalars; keep those as the string sent.
+    return parsed !== null && typeof parsed === 'object' ? parsed : content;
   } catch {
     return content;
   }

package/src/bridge/index.ts

@@ -34,6 +34,10 @@ import { argv, env as procEnv, stdout } from 'node:process';
  *   3. the dependency entry in `src/bridge/package.json`.
  */
 import * as claudeAgentSdk from '@anthropic-ai/claude-agent-sdk';
+import type {
+  HookCallback,
+  HookJSONOutput,
+} from '@anthropic-ai/claude-agent-sdk';
 import * as mcpServerModule from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createClaudeCodeSystemPrompt } from './claude-code-system-prompt';
 import { toClaudeSkillsOption } from './claude-skills-option';
@@ -52,6 +56,11 @@ import {
   resolveInactiveNativeTools,
   resolveNativeTools,
 } from './tool-filtering';
+import {
+  claudeCodeQuestionKey,
+  toClaudeCodeQuestionResult,
+  toHarnessQuestionsInput,
+} from './question-tool';
 
 /*
  * Native Claude Code tool name → cross-harness common name. Tools outside this
@@ -65,7 +74,8 @@ type CommonBuiltinToolName =
   | 'bash'
   | 'glob'
   | 'grep'
-  | 'webSearch';
+  | 'webSearch'
+  | 'askUserQuestions';
 
 const NATIVE_TO_COMMON: Readonly<Record<string, CommonBuiltinToolName>> = {
   Read: 'read',
@@ -75,6 +85,7 @@ const NATIVE_TO_COMMON: Readonly<Record<string, CommonBuiltinToolName>> = {
   Glob: 'glob',
   Grep: 'grep',
   WebSearch: 'webSearch',
+  AskUserQuestion: 'askUserQuestions',
 };
 
 const NATIVE_TOOL_KINDS: Readonly<
@@ -162,17 +173,15 @@ function createPermissionOptions(input: {
     permissionMode,
     inactiveNativeTools,
   });
-  if (permissionMode === 'allow-all' && inactiveNativeTools.size === 0) {
-    return {
-      permissionMode: 'bypassPermissions',
-      allowDangerouslySkipPermissions: true,
-    };
-  }
 
   return {
     permissionMode:
-      permissionMode === 'allow-edits' ? 'acceptEdits' : 'default',
-    allowDangerouslySkipPermissions: false,
+      permissionMode === 'allow-all'
+        ? 'bypassPermissions'
+        : permissionMode === 'allow-edits'
+          ? 'acceptEdits'
+          : 'default',
+    allowDangerouslySkipPermissions: permissionMode === 'allow-all',
     ...(permissionSettings ? { settings: permissionSettings } : {}),
     canUseTool: async (
       toolName: string,
@@ -223,6 +232,80 @@ function createPermissionOptions(input: {
   };
 }
 
+function createQuestionPreToolUseHook(input: {
+  turn: BridgeTurn;
+  emit: Emit;
+  nativeToolCallNames: Map<string, string>;
+}): HookCallback {
+  return async (hookInput, toolUseID): Promise<HookJSONOutput> => {
+    if (
+      hookInput.hook_event_name !== 'PreToolUse' ||
+      hookInput.tool_name !== 'AskUserQuestion'
+    ) {
+      return {};
+    }
+
+    const nativeInput = hookInput.tool_input as Parameters<
+      typeof toHarnessQuestionsInput
+    >[0];
+    const canonicalInput = toHarnessQuestionsInput(nativeInput);
+    const toolCallId = toolUseID ?? hookInput.tool_use_id;
+    input.nativeToolCallNames.set(toolCallId, hookInput.tool_name);
+    input.emit({
+      type: 'tool-call',
+      toolCallId,
+      toolName: 'askUserQuestions',
+      nativeName: hookInput.tool_name,
+      input: JSON.stringify(canonicalInput),
+      providerExecuted: false,
+      providerMetadata: {
+        'claude-code': {
+          nativeRequest: nativeInput,
+        },
+      },
+    });
+
+    const questionKey = claudeCodeQuestionKey(nativeInput);
+    const result = await input.turn.requestToolResult({
+      toolCallId,
+      matches: candidate => {
+        const nativeRequest = candidate.toolResult?.providerOptions?.[
+          'claude-code'
+        ]?.nativeRequest as
+          | Parameters<typeof claudeCodeQuestionKey>[0]
+          | undefined;
+        return (
+          nativeRequest != null &&
+          claudeCodeQuestionKey(nativeRequest) === questionKey
+        );
+      },
+    });
+    const nativeResult = toClaudeCodeQuestionResult({
+      nativeInput,
+      output: result.output as Parameters<
+        typeof toClaudeCodeQuestionResult
+      >[0]['output'],
+    });
+
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        ...(nativeResult.behavior === 'allow'
+          ? {
+              permissionDecision: 'allow',
+              updatedInput: {
+                ...nativeResult.updatedInput,
+              } as Record<string, unknown>,
+            }
+          : {
+              permissionDecision: 'deny',
+              permissionDecisionReason: nativeResult.message,
+            }),
+      },
+    };
+  };
+}
+
 function createPermissionSettings(input: {
   permissionMode: 'allow-reads' | 'allow-edits' | 'allow-all';
   inactiveNativeTools: ReadonlySet<string>;
@@ -372,6 +455,11 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
     nativeToolCallNames: streamEventState.nativeToolCallNames,
     approvalRequestedToolUseIds: streamEventState.approvalRequestedToolUseIds,
   });
+  const questionPreToolUseHook = createQuestionPreToolUseHook({
+    turn,
+    emit,
+    nativeToolCallNames: streamEventState.nativeToolCallNames,
+  });
 
   const q = claudeSdk.query({
     prompt: queryInput.input,
@@ -401,6 +489,12 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
       // `compact_boundary` system message does not. Latch it for the unified
       // `compaction` event; return an empty output so compaction proceeds.
       hooks: {
+        PreToolUse: [
+          {
+            matcher: 'AskUserQuestion',
+            hooks: [questionPreToolUseHook],
+          },
+        ],
         PostCompact: [
           {
             hooks: [
@@ -507,6 +601,19 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
 
       if (type === 'result') {
         if (msg.subtype === 'success') {
+          // `success` does not mean the turn succeeded: the CLI flags a rejected
+          // request with `is_error` and puts the message in `result`, which the
+          // empty-result rescue below cannot catch.
+          if (msg.is_error) {
+            emitTerminalError(
+              msg.result?.trim() ||
+                streamEventState.observedTerminalError ||
+                (typeof msg.api_error_status === 'number'
+                  ? `Claude Code reported an API error (HTTP ${msg.api_error_status})`
+                  : 'Claude Code reported a failed result'),
+            );
+            continue;
+          }
           const emptyResult = !msg.result?.trim?.();
           if (emptyResult && streamEventState.observedTerminalError) {
             emitTerminalError(streamEventState.observedTerminalError);

package/src/bridge/question-tool.ts

@@ -0,0 +1,104 @@
+import type {
+  HarnessV1QuestionsToolInput,
+  HarnessV1QuestionsToolOutput,
+} from '@ai-sdk/harness';
+import type { AskUserQuestionInput } from '@anthropic-ai/claude-agent-sdk/sdk-tools.js';
+
+type ClaudeCodeQuestion = AskUserQuestionInput['questions'][number];
+
+export function claudeCodeQuestionKey(
+  nativeInput: AskUserQuestionInput,
+): string {
+  return JSON.stringify(nativeInput.questions);
+}
+
+export function toHarnessQuestionsInput(
+  nativeInput: AskUserQuestionInput,
+): HarnessV1QuestionsToolInput {
+  return {
+    allowPartialAnswers: true,
+    questions: nativeInput.questions.map((question, questionIndex) => ({
+      id: `question-${questionIndex + 1}`,
+      question: question.question,
+      header: question.header,
+      options: question.options.map((option, optionIndex) => ({
+        id: `option-${optionIndex + 1}`,
+        label: option.label,
+        description: option.description,
+        ...(option.preview !== undefined ? { preview: option.preview } : {}),
+      })),
+      allowMultiple: question.multiSelect,
+      allowFreeForm: true,
+    })),
+  };
+}
+
+export function toClaudeCodeQuestionResult(input: {
+  nativeInput: AskUserQuestionInput;
+  output: HarnessV1QuestionsToolOutput;
+}):
+  | {
+      behavior: 'allow';
+      updatedInput: AskUserQuestionInput & { answers: Record<string, string> };
+    }
+  | { behavior: 'deny'; message: string } {
+  const output = input.output;
+  if (output.action === 'declined' || output.action === 'cancelled') {
+    return {
+      behavior: 'deny',
+      message: `The user ${output.action} the questions.`,
+    };
+  }
+
+  const canonicalInput = toHarnessQuestionsInput(input.nativeInput);
+  const answers = Object.fromEntries(
+    canonicalInput.questions.flatMap((question, questionIndex) => {
+      const answer = output.answers[question.id];
+      if (answer == null) return [];
+      const nativeQuestion = input.nativeInput.questions[questionIndex];
+      return [
+        [
+          nativeQuestion.question,
+          toClaudeCodeAnswer({
+            nativeQuestion,
+            optionIds: answer.optionIds,
+            freeform: answer.freeform,
+          }),
+        ],
+      ];
+    }),
+  );
+
+  return {
+    behavior: 'allow',
+    updatedInput: { ...input.nativeInput, answers },
+  };
+}
+
+function toClaudeCodeAnswer(input: {
+  nativeQuestion: ClaudeCodeQuestion;
+  optionIds: string[];
+  freeform: string | undefined;
+}): string {
+  if (input.freeform !== undefined) return input.freeform;
+  const labels = input.optionIds.flatMap(optionId => {
+    const index = positionalIdIndex({ id: optionId, prefix: 'option-' });
+    const option =
+      index == null ? undefined : input.nativeQuestion.options[index];
+    return option == null ? [] : [option.label];
+  });
+  return input.nativeQuestion.multiSelect
+    ? labels.join(', ')
+    : (labels[0] ?? '');
+}
+
+function positionalIdIndex(input: {
+  id: string;
+  prefix: string;
+}): number | undefined {
+  if (!input.id.startsWith(input.prefix)) return undefined;
+  const oneBasedIndex = Number(input.id.slice(input.prefix.length));
+  return Number.isInteger(oneBasedIndex) && oneBasedIndex > 0
+    ? oneBasedIndex - 1
+    : undefined;
+}

package/src/bridge/tool-filtering.ts

@@ -26,7 +26,7 @@ const PUBLIC_TO_NATIVE: Readonly<Record<string, string>> = {
   ExitPlanMode: 'ExitPlanMode',
   EnterWorktree: 'EnterWorktree',
   ExitWorktree: 'ExitWorktree',
-  AskUserQuestion: 'AskUserQuestion',
+  askUserQuestions: 'AskUserQuestion',
   Skill: 'Skill',
   ToolSearch: 'ToolSearch',
 };

package/src/claude-code-harness.ts

@@ -1,6 +1,7 @@
 import { posix } from 'node:path';
 import {
   commonTool,
+  HARNESS_V1_BUILTIN_TOOLS,
   harnessV1DiagnosticFromBridgeFrame,
   HarnessCapabilityUnsupportedError,
   type HarnessV1,
@@ -461,39 +462,14 @@ const CLAUDE_CODE_BUILTIN_TOOLS = {
       discard_changes: z.boolean().optional(),
     }),
   }),
-  AskUserQuestion: tool({
-    description: 'Ask the user multiple-choice questions via a structured UI',
-    inputSchema: z.object({
-      questions: z
-        .array(
-          z.object({
-            question: z.string(),
-            header: z.string(),
-            options: z.array(
-              z.object({
-                label: z.string(),
-                description: z.string(),
-                preview: z.string().optional(),
-              }),
-            ),
-            multiSelect: z.boolean(),
-          }),
-        )
-        .min(1)
-        .max(4),
-      answers: z.record(z.string(), z.string()).optional(),
-      annotations: z
-        .record(
-          z.string(),
-          z.object({
-            preview: z.string().optional(),
-            notes: z.string().optional(),
-          }),
-        )
-        .optional(),
-      metadata: z.object({ source: z.string().optional() }).optional(),
-    }),
-  }),
+  askUserQuestions: {
+    ...HARNESS_V1_BUILTIN_TOOLS.askUserQuestions,
+    nativeName: 'AskUserQuestion',
+    toolUseKind: 'readonly',
+  } as typeof HARNESS_V1_BUILTIN_TOOLS.askUserQuestions & {
+    readonly nativeName: 'AskUserQuestion';
+    readonly toolUseKind: 'readonly';
+  },
   Skill: {
     ...tool({
       description: 'Activate a skill by name',
@@ -921,13 +897,18 @@ export function createClaudeCode(
           );
         }
       } else {
-        warnCredentialBrokeringUnavailable();
         sandboxClaudeEnvironment = await applyCredentialForwarding({
           environment: sandboxClaudeEnvironment,
           credentialEnvironmentVariables:
             CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES,
           credentialForwarding: settings.credentialForwarding,
         });
+        warnCredentialBrokeringUnavailable({
+          environment: claudeEnvironment,
+          forwardedEnvironment: sandboxClaudeEnvironment,
+          credentialEnvironmentVariables:
+            CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES,
+        });
       }
       const bootstrapDir = posix.resolve(
         defaultWorkingDirectory,
@@ -1692,6 +1673,9 @@ function createSession({
           toolCallId: input.toolCallId,
           output: input.output,
           isError: input.isError,
+          ...(input.toolResult !== undefined
+            ? { toolResult: input.toolResult }
+            : {}),
         });
       },
       submitToolApproval: async input => {