gsd-pi 2.71.0-dev.e17e0ce → 2.72.0-dev.3118184

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -187,20 +187,36 @@ function extractMessageText(msg: { role: string; content: unknown }): string {
  * call effectively stateless. This version serialises the complete
  * conversation history (system prompt + all user/assistant turns) so
  * Claude Code has full context for multi-turn continuity.
+ *
+ * History is wrapped in XML-tag structure rather than `[User]`/`[Assistant]`
+ * bracket headers. Bracket headers read to the model as an in-context
+ * demonstration of how turns are delimited, causing it to fabricate fake
+ * user turns in its own output. XML tags read as document structure and
+ * don't get mirrored in free text.
  */
 export function buildPromptFromContext(context: Context): string {
-	const parts: string[] = [];
+	const hasContent = Boolean(context.systemPrompt) || context.messages.some((m) => extractMessageText(m));
+	if (!hasContent) return "";
+
+	const parts: string[] = [
+		"Respond only to the final user message below. " +
+			"Do not emit <user_message>, <assistant_message>, or <prior_system_context> tags in your response.",
+	];
 
 	if (context.systemPrompt) {
-		parts.push(`[System]\n${context.systemPrompt}`);
+		parts.push(`<prior_system_context>\n${context.systemPrompt}\n</prior_system_context>`);
 	}
 
+	const turns: string[] = [];
 	for (const msg of context.messages) {
 		const text = extractMessageText(msg);
 		if (!text) continue;
-
-		const label = msg.role === "user" ? "User" : msg.role === "assistant" ? "Assistant" : "System";
-		parts.push(`[${label}]\n${text}`);
+		const tag =
+			msg.role === "user" ? "user_message" : msg.role === "assistant" ? "assistant_message" : "system_message";
+		turns.push(`<${tag}>\n${text}\n</${tag}>`);
+	}
+	if (turns.length > 0) {
+		parts.push(`<conversation_history>\n${turns.join("\n")}\n</conversation_history>`);
 	}
 
 	return parts.join("\n\n");
@@ -518,34 +534,104 @@ export function createClaudeCodeElicitationHandler(
 	};
 }
 
+/**
+ * Aborted by the caller's AbortSignal — distinct from exhaustion. GSD's
+ * agent loop keys off `stopReason === "aborted"` to treat this as a clean
+ * user cancel instead of a retry-eligible provider failure.
+ */
+export function makeAbortedMessage(model: string, lastTextContent: string): AssistantMessage {
+	const message: AssistantMessage = {
+		role: "assistant",
+		content: lastTextContent
+			? [{ type: "text", text: lastTextContent }]
+			: [{ type: "text", text: "Claude Code stream aborted by caller" }],
+		api: "anthropic-messages",
+		provider: "claude-code",
+		model,
+		usage: { ...ZERO_USAGE },
+		stopReason: "aborted",
+		timestamp: Date.now(),
+	};
+	return message;
+}
+
 // ---------------------------------------------------------------------------
 // SDK options builder
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve the Claude Code permission mode for the current run.
+ *
+ * GSD subagents run underneath a host Claude Code session the user has
+ * already consented to, and their work (edits, shell inspection, MCP calls)
+ * spans the full workflow toolset. Defaulting the inner SDK to
+ * `bypassPermissions` avoids per-tool approval prompts that offer no
+ * meaningful safety beyond what the host session and the subagent prompts
+ * already enforce. `GSD_CLAUDE_CODE_PERMISSION_MODE` lets security-conscious
+ * users opt into a stricter mode (`acceptEdits`, `default`, `plan`).
+ *
+ * Tradeoff: bypass means a prompt-injection payload read from an untrusted
+ * file could trigger tool calls without a second gate. Accepted for GSD
+ * because the workflow is explicit user intent and the alternative
+ * (#4099) is continuous approval fatigue that blocks real work.
+ */
+export async function resolveClaudePermissionMode(
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<"bypassPermissions" | "acceptEdits" | "default" | "plan"> {
+	const override = env.GSD_CLAUDE_CODE_PERMISSION_MODE?.trim();
+	if (override === "bypassPermissions" || override === "acceptEdits" || override === "default" || override === "plan") {
+		return override;
+	}
+	return "bypassPermissions";
+}
+
 /**
  * Build the options object passed to the Claude Agent SDK's `query()` call.
  *
  * Extracted for testability — callers can verify session persistence,
  * beta flags, and other configuration without mocking the full SDK.
+ *
+ * `permissionMode` / `allowDangerouslySkipPermissions` are resolved through
+ * {@link resolveClaudePermissionMode} so interactive runs don't silently
+ * bypass the SDK's permission gate. Callers that want the old always-bypass
+ * behaviour pass `permissionMode: "bypassPermissions"` explicitly.
  */
 export function buildSdkOptions(
 	modelId: string,
 	prompt: string,
+	overrides?: { permissionMode?: "bypassPermissions" | "acceptEdits" | "default" | "plan" },
 	extraOptions: Record<string, unknown> = {},
 ): Record<string, unknown> {
 	const mcpServers = buildWorkflowMcpServers();
+	const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
 	const disallowedTools = ["AskUserQuestion"];
+	// Pre-authorize the safe built-ins and every registered workflow MCP
+	// server's tools. `acceptEdits` mode (the interactive default) only
+	// auto-approves file edits — Read/Glob/Grep, basic shell inspection, and
+	// every `mcp__gsd-workflow__*` call still surface as "This command
+	// requires approval" and block GSD actions (#4099).
+	const allowedTools = [
+		"Read",
+		"Write",
+		"Edit",
+		"Glob",
+		"Grep",
+		"Bash(ls:*)",
+		"Bash(pwd)",
+		...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
+	];
 	return {
 		pathToClaudeCodeExecutable: getClaudePath(),
 		model: modelId,
 		includePartialMessages: true,
 		persistSession: true,
 		cwd: process.cwd(),
-		permissionMode: "bypassPermissions",
-		allowDangerouslySkipPermissions: true,
+		permissionMode,
+		allowDangerouslySkipPermissions: permissionMode === "bypassPermissions",
 		settingSources: ["project"],
 		systemPrompt: { type: "preset", preset: "claude_code" },
 		disallowedTools,
+		...(allowedTools.length > 0 ? { allowedTools } : {}),
 		...(mcpServers ? { mcpServers } : {}),
 		betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
 		...extraOptions,
@@ -656,6 +742,29 @@ function attachExternalResultsToToolBlocks(
 	}
 }
 
+/**
+ * Merge tool-call blocks from the active partial-message builder into the
+ * running list of intermediate tool calls, preserving order and de-duping
+ * by tool-call id. Exposed for testing the F3 fix (final-turn tool calls
+ * dropped when `result` arrives without a preceding synthetic `user`).
+ */
+export function mergePendingToolCalls(
+	intermediate: AssistantMessage["content"],
+	pending: AssistantMessage["content"],
+): AssistantMessage["content"] {
+	const alreadyIncluded = new Set<string>();
+	for (const block of intermediate) {
+		if (block.type === "toolCall") alreadyIncluded.add(block.id);
+	}
+	for (const block of pending) {
+		if (block.type !== "toolCall") continue;
+		if (alreadyIncluded.has(block.id)) continue;
+		alreadyIncluded.add(block.id);
+		intermediate.push(block);
+	}
+	return intermediate;
+}
+
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
@@ -712,9 +821,11 @@ async function pumpSdkMessages(
 		}
 
 		const prompt = buildPromptFromContext(context);
+		const permissionMode = await resolveClaudePermissionMode();
 		const sdkOpts = buildSdkOptions(
 			modelId,
 			prompt,
+			{ permissionMode },
 			typeof (options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext === "object"
 				? {
 						onElicitation: createClaudeCodeElicitationHandler(
@@ -746,7 +857,17 @@ async function pumpSdkMessages(
 		stream.push({ type: "start", partial: initialPartial });
 
 		for await (const msg of queryResult as AsyncIterable<SDKMessage>) {
-			if (options?.signal?.aborted) break;
+			if (options?.signal?.aborted) {
+				// User-initiated cancel — emit an aborted error so the agent
+				// loop classifies this as a deliberate stop, not a transient
+				// provider failure that should be retried.
+				stream.push({
+					type: "error",
+					reason: "aborted",
+					error: makeAbortedMessage(modelId, lastTextContent),
+				});
+				return;
+			}
 
 			switch (msg.type) {
 				// -- Init --
@@ -857,6 +978,16 @@ async function pumpSdkMessages(
 					// events for proper TUI rendering, followed by the text response.
 					const finalContent: AssistantMessage["content"] = [];
 
+					// If the final turn ended without a synthetic user message
+					// (e.g. stop_reason: "tool_use" followed directly by result,
+					// or a turn with text but no tool execution), the `builder`
+					// still holds toolCall blocks that were never pushed into
+					// `intermediateToolBlocks`. Fold them in here so they aren't
+					// dropped from the final AssistantMessage.
+					if (builder) {
+						mergePendingToolCalls(intermediateToolBlocks, builder.message.content);
+					}
+
 					// Add tool calls from intermediate turns first (renders above text)
 					attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById);
 					finalContent.push(...intermediateToolBlocks);

package/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { PartialMessageBuilder } from "../partial-builder.ts";
-import type { BetaRawMessageStreamEvent } from "../sdk-types.ts";
+import { mapContentBlock, parseMcpToolName, PartialMessageBuilder } from "../partial-builder.ts";
+import type { BetaContentBlock, BetaRawMessageStreamEvent } from "../sdk-types.ts";
 
 describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 	/**
@@ -148,3 +148,92 @@ describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => {
 		}
 	});
 });
+
+describe("parseMcpToolName", () => {
+	test("splits mcp__<server>__<tool> into parts", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__gsd-workflow__gsd_plan_milestone"),
+			{ server: "gsd-workflow", tool: "gsd_plan_milestone" },
+		);
+	});
+
+	test("preserves server names containing hyphens", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__my-cool-server__do_thing"),
+			{ server: "my-cool-server", tool: "do_thing" },
+		);
+	});
+
+	test("preserves tool names containing underscores", () => {
+		assert.deepEqual(
+			parseMcpToolName("mcp__srv__a_b_c_d"),
+			{ server: "srv", tool: "a_b_c_d" },
+		);
+	});
+
+	test("returns null for non-prefixed names", () => {
+		assert.equal(parseMcpToolName("Bash"), null);
+		assert.equal(parseMcpToolName("gsd_plan_milestone"), null);
+	});
+
+	test("returns null for malformed prefixes", () => {
+		assert.equal(parseMcpToolName("mcp__"), null);
+		assert.equal(parseMcpToolName("mcp__server"), null);
+		assert.equal(parseMcpToolName("mcp__server__"), null);
+		assert.equal(parseMcpToolName("mcp____tool"), null);
+	});
+});
+
+describe("PartialMessageBuilder — MCP tool name normalization", () => {
+	test("strips mcp__<server>__ prefix on content_block_start", () => {
+		const builder = new PartialMessageBuilder("claude-sonnet-4-20250514");
+		const event = builder.handleEvent({
+			type: "content_block_start",
+			index: 0,
+			content_block: {
+				type: "tool_use",
+				id: "tool_1",
+				name: "mcp__gsd-workflow__gsd_plan_milestone",
+				input: {},
+			},
+		} as BetaRawMessageStreamEvent);
+
+		assert.ok(event, "event should not be null");
+		assert.equal(event!.type, "toolcall_start");
+		if (event!.type === "toolcall_start") {
+			const toolCall = (event.partial.content[event.contentIndex] as any);
+			assert.equal(toolCall.name, "gsd_plan_milestone");
+			assert.equal(toolCall.mcpServer, "gsd-workflow");
+		}
+	});
+
+	test("leaves non-MCP tool names untouched", () => {
+		const builder = new PartialMessageBuilder("claude-sonnet-4-20250514");
+		const event = builder.handleEvent({
+			type: "content_block_start",
+			index: 0,
+			content_block: { type: "tool_use", id: "tool_1", name: "Bash", input: {} },
+		} as BetaRawMessageStreamEvent);
+
+		assert.ok(event);
+		if (event!.type === "toolcall_start") {
+			const toolCall = (event.partial.content[event.contentIndex] as any);
+			assert.equal(toolCall.name, "Bash");
+			assert.equal(toolCall.mcpServer, undefined);
+		}
+	});
+
+	test("mapContentBlock strips MCP prefix on full tool_use blocks", () => {
+		const block: BetaContentBlock = {
+			type: "tool_use",
+			id: "tool_2",
+			name: "mcp__gsd-workflow__gsd_task_complete",
+			input: { taskId: "T001" },
+		};
+		const mapped = mapContentBlock(block) as any;
+		assert.equal(mapped.type, "toolCall");
+		assert.equal(mapped.name, "gsd_task_complete");
+		assert.equal(mapped.mcpServer, "gsd-workflow");
+		assert.deepEqual(mapped.arguments, { taskId: "T001" });
+	});
+});

package/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts

@@ -6,6 +6,9 @@ import { tmpdir } from "node:os";
 import {
 	makeStreamExhaustedErrorMessage,
 	getResultErrorMessage,
+	makeAbortedMessage,
+	mergePendingToolCalls,
+	resolveClaudePermissionMode,
 	buildPromptFromContext,
 	buildSdkOptions,
 	createClaudeCodeElicitationHandler,
@@ -16,7 +19,7 @@ import {
 	parseClaudeLookupOutput,
 	roundResultToElicitationContent,
 } from "../stream-adapter.ts";
-import type { Context, Message } from "@gsd/pi-ai";
+import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
 import type { SDKUserMessage } from "../sdk-types.ts";
 
 // ---------------------------------------------------------------------------
@@ -164,6 +167,98 @@ describe("stream-adapter — full context prompt (#2859)", () => {
 	});
 });
 
+// ---------------------------------------------------------------------------
+// Bug #4102 — transcript fabrication regression tests
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — no transcript fabrication (#4102)", () => {
+	test("buildPromptFromContext never emits forbidden [User]/[Assistant] bracket headers", () => {
+		const context: Context = {
+			systemPrompt: "You are a helpful assistant.",
+			messages: [
+				{ role: "user", content: "First" } as Message,
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "Second" }],
+					api: "anthropic-messages",
+					provider: "claude-code",
+					model: "claude-sonnet-4-20250514",
+					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+					stopReason: "stop",
+					timestamp: Date.now(),
+				} as Message,
+				{ role: "user", content: "Third" } as Message,
+			],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(!prompt.includes("[User]"), "prompt must not include literal [User] bracket header");
+		assert.ok(!prompt.includes("[Assistant]"), "prompt must not include literal [Assistant] bracket header");
+		assert.ok(!prompt.includes("[System]"), "prompt must not include literal [System] bracket header");
+	});
+
+	test("buildPromptFromContext wraps history in XML-tag structure", () => {
+		const context: Context = {
+			systemPrompt: "You are helpful.",
+			messages: [
+				{ role: "user", content: "Hello" } as Message,
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "Hi there" }],
+					api: "anthropic-messages",
+					provider: "claude-code",
+					model: "claude-sonnet-4-20250514",
+					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+					stopReason: "stop",
+					timestamp: Date.now(),
+				} as Message,
+			],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(prompt.includes("<conversation_history>"), "prompt must wrap history in <conversation_history>");
+		assert.ok(prompt.includes("</conversation_history>"), "prompt must close <conversation_history>");
+		assert.ok(prompt.includes("<user_message>\nHello\n</user_message>"), "user turn must use <user_message> tags");
+		assert.ok(prompt.includes("<assistant_message>\nHi there\n</assistant_message>"), "assistant turn must use <assistant_message> tags");
+		assert.ok(prompt.includes("<prior_system_context>\nYou are helpful.\n</prior_system_context>"), "system prompt must use <prior_system_context> tags");
+	});
+
+	test("buildPromptFromContext includes a do-not-echo-tags directive as primary instruction", () => {
+		const context: Context = {
+			messages: [{ role: "user", content: "Anything" } as Message],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(
+			prompt.startsWith("Respond only to the final user message"),
+			"primary directive must lead the prompt",
+		);
+		assert.ok(prompt.includes("Do not emit <user_message>"), "directive must forbid emitting user_message tag");
+		assert.ok(prompt.includes("<assistant_message>"), "directive must mention assistant_message tag");
+	});
+
+	test("buildPromptFromContext omits <conversation_history> when there are no messages but a system prompt", () => {
+		const context: Context = {
+			systemPrompt: "Seed",
+			messages: [],
+		};
+
+		const prompt = buildPromptFromContext(context);
+
+		assert.ok(prompt.includes("<prior_system_context>"), "system prompt must still render");
+		assert.ok(!prompt.includes("<conversation_history>"), "no history wrapper when messages are empty");
+	});
+
+	test("buildPromptFromContext still returns empty string when context is entirely empty", () => {
+		const context: Context = { messages: [] };
+		const prompt = buildPromptFromContext(context);
+		assert.equal(prompt, "", "empty context must not emit a bare directive");
+	});
+});
+
 describe("stream-adapter — Claude Code external tool results", () => {
 	test("extractToolResultsFromSdkUserMessage maps tool_result content to tool payloads", () => {
 		const message: SDKUserMessage = {
@@ -274,6 +369,16 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
 			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
 			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+			assert.deepEqual(options.allowedTools, [
+				"Read",
+				"Write",
+				"Edit",
+				"Glob",
+				"Grep",
+				"Bash(ls:*)",
+				"Bash(pwd)",
+				"mcp__gsd-workflow__*",
+			]);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
@@ -302,6 +407,16 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const mcpServers = options.mcpServers as Record<string, any>;
 			assert.ok(mcpServers?.["custom-workflow"], "expected custom workflow server config");
 			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+			assert.deepEqual(options.allowedTools, [
+				"Read",
+				"Write",
+				"Edit",
+				"Glob",
+				"Grep",
+				"Bash(ls:*)",
+				"Bash(pwd)",
+				"mcp__custom-workflow__*",
+			]);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
@@ -414,7 +529,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			delete process.env.GSD_WORKFLOW_MCP_ARGS;
 			delete process.env.GSD_WORKFLOW_MCP_ENV;
 			delete process.env.GSD_WORKFLOW_MCP_CWD;
-			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", { onElicitation });
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { onElicitation });
 			assert.equal(options.onElicitation, onElicitation);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
@@ -680,6 +795,134 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 	});
 });
 
+// ---------------------------------------------------------------------------
+// F2 — abort vs stream-exhausted classification
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — abort classification (F2)", () => {
+	test("makeAbortedMessage sets stopReason to 'aborted', not 'error'", () => {
+		const message = makeAbortedMessage("claude-sonnet-4-6", "");
+		assert.equal(message.stopReason, "aborted");
+		assert.equal(message.errorMessage, undefined);
+	});
+
+	test("makeAbortedMessage preserves last-seen text content", () => {
+		const message = makeAbortedMessage("claude-sonnet-4-6", "partial mid-stream text");
+		assert.deepEqual(message.content, [{ type: "text", text: "partial mid-stream text" }]);
+	});
+
+	test("aborted message is distinguishable from stream-exhausted error", () => {
+		const aborted = makeAbortedMessage("claude-sonnet-4-6", "");
+		const exhausted = makeStreamExhaustedErrorMessage("claude-sonnet-4-6", "");
+		assert.notEqual(aborted.stopReason, exhausted.stopReason);
+		assert.equal(exhausted.errorMessage, "stream_exhausted_without_result");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// F3 — final-turn tool calls not dropped
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — final-turn tool-call merge (F3)", () => {
+	function toolCall(id: string, name = "bash"): AssistantMessage["content"][number] {
+		return { type: "toolCall", id, name, arguments: {} };
+	}
+
+	test("mergePendingToolCalls appends tool calls not already in intermediate", () => {
+		const intermediate: AssistantMessage["content"] = [toolCall("tool-1")];
+		const pending: AssistantMessage["content"] = [
+			toolCall("tool-2"),
+			{ type: "text", text: "trailing text" },
+		];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 2);
+		assert.equal((merged[0] as any).id, "tool-1");
+		assert.equal((merged[1] as any).id, "tool-2");
+	});
+
+	test("mergePendingToolCalls is idempotent across duplicate ids", () => {
+		const intermediate: AssistantMessage["content"] = [toolCall("tool-1")];
+		const pending: AssistantMessage["content"] = [toolCall("tool-1"), toolCall("tool-2")];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 2);
+		assert.deepEqual(
+			merged.map((b) => (b as any).id),
+			["tool-1", "tool-2"],
+		);
+	});
+
+	test("mergePendingToolCalls ignores non-toolCall blocks from pending", () => {
+		const intermediate: AssistantMessage["content"] = [];
+		const pending: AssistantMessage["content"] = [
+			{ type: "text", text: "hello" },
+			{ type: "thinking", thinking: "pondering" },
+			toolCall("tool-1"),
+		];
+		const merged = mergePendingToolCalls(intermediate, pending);
+		assert.equal(merged.length, 1);
+		assert.equal((merged[0] as any).id, "tool-1");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// F10 — permission mode is configurable
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — permission mode (F10)", () => {
+	// Earlier tests in this file set GSD_WORKFLOW_MCP_* env vars and restore
+	// them by reassigning from `prev.*`. When `prev.*` was undefined, node
+	// coerces the assignment to the literal string "undefined", which then
+	// fails JSON.parse inside buildWorkflowMcpServers. Clear the relevant
+	// slots before each permission-mode test so buildSdkOptions doesn't throw.
+	function clearWorkflowMcpEnv(): void {
+		for (const key of [
+			"GSD_WORKFLOW_MCP_COMMAND",
+			"GSD_WORKFLOW_MCP_NAME",
+			"GSD_WORKFLOW_MCP_ARGS",
+			"GSD_WORKFLOW_MCP_ENV",
+			"GSD_WORKFLOW_MCP_CWD",
+		]) {
+			if (process.env[key] === undefined || process.env[key] === "undefined") {
+				delete process.env[key];
+			}
+		}
+	}
+
+	test("buildSdkOptions defaults to bypassPermissions for backwards compatibility", () => {
+		clearWorkflowMcpEnv();
+		const opts = buildSdkOptions("claude-sonnet-4-6", "test");
+		assert.equal(opts.permissionMode, "bypassPermissions");
+		assert.equal(opts.allowDangerouslySkipPermissions, true);
+	});
+
+	test("buildSdkOptions respects explicit acceptEdits override", () => {
+		clearWorkflowMcpEnv();
+		const opts = buildSdkOptions("claude-sonnet-4-6", "test", { permissionMode: "acceptEdits" });
+		assert.equal(opts.permissionMode, "acceptEdits");
+		assert.equal(
+			opts.allowDangerouslySkipPermissions,
+			false,
+			"allowDangerouslySkipPermissions must be false for non-bypass modes",
+		);
+	});
+
+	test("resolveClaudePermissionMode honours the GSD_CLAUDE_CODE_PERMISSION_MODE env override", async () => {
+		const env = { GSD_CLAUDE_CODE_PERMISSION_MODE: "acceptEdits" } as NodeJS.ProcessEnv;
+		const mode = await resolveClaudePermissionMode(env);
+		assert.equal(mode, "acceptEdits");
+	});
+
+	test("resolveClaudePermissionMode rejects unknown override values (fallback path)", async () => {
+		const env = { GSD_CLAUDE_CODE_PERMISSION_MODE: "nonsense" } as NodeJS.ProcessEnv;
+		const mode = await resolveClaudePermissionMode(env);
+		// Unknown override falls back to auto-detect → either bypass or acceptEdits
+		assert.ok(
+			mode === "bypassPermissions" || mode === "acceptEdits",
+			`expected bypass or acceptEdits, got ${mode}`,
+		);
+	});
+});
+
 describe("stream-adapter — Windows Claude path lookup (#3770)", () => {
 	test("getClaudeLookupCommand uses where on Windows", () => {
 		assert.equal(getClaudeLookupCommand("win32"), "where claude");