gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

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

@@ -8,6 +8,7 @@ import {
 	getResultErrorMessage,
 	makeAbortedMessage,
 	mergePendingToolCalls,
+	buildFinalAssistantContent,
 	resolveClaudePermissionMode,
 	buildPromptFromContext,
 	buildSdkQueryPrompt,
@@ -24,6 +25,51 @@ import {
 import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
 import type { SDKUserMessage } from "../sdk-types.ts";
 
+// ---------------------------------------------------------------------------
+// Env helpers — `GSD_WORKFLOW_MCP_*` save/restore
+//
+// The naive pattern `process.env.X = prev.X` breaks when `prev.X` is
+// undefined: Node coerces the assignment to the literal string
+// "undefined", which then pollutes subsequent tests that read the var
+// and assume it's absent. Issue #4808 documents the resulting bleed.
+//
+// `setWorkflowMcpEnv` returns a `restore()` closure that either
+// re-assigns the previous string value OR `delete`s the key when the
+// original was absent. Call in a try/finally; restore in the finally.
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_MCP_ENV_KEYS = [
+	"GSD_WORKFLOW_MCP_COMMAND",
+	"GSD_WORKFLOW_MCP_NAME",
+	"GSD_WORKFLOW_MCP_ARGS",
+	"GSD_WORKFLOW_MCP_ENV",
+	"GSD_WORKFLOW_MCP_CWD",
+] as const;
+
+type WorkflowMcpEnvKey = (typeof WORKFLOW_MCP_ENV_KEYS)[number];
+
+function setWorkflowMcpEnv(
+	values: Partial<Record<WorkflowMcpEnvKey, string>>,
+): () => void {
+	const prev: Partial<Record<WorkflowMcpEnvKey, string | undefined>> = {};
+	for (const key of WORKFLOW_MCP_ENV_KEYS) {
+		prev[key] = process.env[key];
+	}
+	for (const [key, value] of Object.entries(values)) {
+		process.env[key] = value;
+	}
+	return function restore() {
+		for (const key of WORKFLOW_MCP_ENV_KEYS) {
+			const previous = prev[key];
+			if (previous === undefined) {
+				delete process.env[key];
+			} else {
+				process.env[key] = previous;
+			}
+		}
+	};
+}
+
 // ---------------------------------------------------------------------------
 // Existing tests — exhausted stream fallback (#2575)
 // ---------------------------------------------------------------------------
@@ -372,13 +418,146 @@ describe("stream-adapter — Claude Code external tool results", () => {
 				toolUseId: "tool-bash-1",
 				result: {
 					content: [{ type: "text", text: "line 1\nline 2" }],
-					details: {},
+					// extractStructuredDetailsFromBlock returns undefined when no
+					// structured payload exists, restoring the pre-#4477 nullable
+					// contract (#4477 review feedback).
+					details: undefined,
 					isError: false,
 				},
 			},
 		]);
 	});
 
+	test("extractToolResultsFromSdkUserMessage reads structuredContent as a sibling field (#4472)", () => {
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-mcp-1",
+			message: {
+				role: "user",
+				content: [
+					{
+						type: "mcp_tool_result",
+						tool_use_id: "tool-mcp-1",
+						content: [{ type: "text", text: "Gate Q3 result saved: verdict=pass" }],
+						is_error: false,
+						structuredContent: { gateId: "Q3", verdict: "pass" },
+					} as unknown as Record<string, unknown>,
+				],
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.deepEqual(results[0].result.details, { gateId: "Q3", verdict: "pass" });
+	});
+
+	test("extractToolResultsFromSdkUserMessage reads structuredContent from a content sub-block (#4472)", () => {
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-mcp-2",
+			message: {
+				role: "user",
+				content: [
+					{
+						type: "mcp_tool_result",
+						tool_use_id: "tool-mcp-2",
+						content: [
+							{ type: "text", text: "Gate Q4 result saved: verdict=flag" },
+							{ type: "structuredContent", structuredContent: { gateId: "Q4", verdict: "flag" } },
+						],
+						is_error: false,
+					} as unknown as Record<string, unknown>,
+				],
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.deepEqual(results[0].result.details, { gateId: "Q4", verdict: "flag" });
+	});
+
+	test("#4477 extractToolResultsFromSdkUserMessage does NOT leak structuredContent pseudo-blocks into visible content", () => {
+		// Regression: when a content sub-block carries `type: "structuredContent"`,
+		// it carries the structured payload (extracted separately into `details`)
+		// and must NOT appear in the visible `content` array — otherwise the
+		// renderer stringifies the JSON pseudo-block and shows it next to the
+		// actual tool output. See PR #4477 review (CodeRabbit, post-fix-round).
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-mcp-strip",
+			message: {
+				role: "user",
+				content: [
+					{
+						type: "mcp_tool_result",
+						tool_use_id: "tool-mcp-strip",
+						content: [
+							{ type: "text", text: "Gate Q5 result saved: verdict=pass" },
+							{ type: "structuredContent", structuredContent: { gateId: "Q5", verdict: "pass" } },
+							{ type: "text", text: "second visible line" },
+							// snake_case variant — also a pseudo-block; also must be stripped
+							{ type: "structured_content", structured_content: { extra: "data" } },
+						],
+						is_error: false,
+					} as unknown as Record<string, unknown>,
+				],
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.equal(results.length, 1, "should extract one result");
+		const result = results[0].result;
+
+		// The structured payload IS extracted to `details`.
+		assert.deepEqual(result.details, { gateId: "Q5", verdict: "pass" });
+
+		// The visible content has the two text blocks but NEITHER pseudo-block.
+		const visibleTexts = result.content.map((c: any) => c.text);
+		assert.deepEqual(
+			visibleTexts,
+			["Gate Q5 result saved: verdict=pass", "second visible line"],
+			"visible content must include only the two text blocks; both structuredContent variants must be stripped",
+		);
+
+		// Belt-and-suspenders: assert no rendered text shows the JSON serialization
+		// of a pseudo-block. We don't check for bare keys like "gateId" or "verdict"
+		// because those are legitimate words in the gate-result message text. The
+		// regression signature would be a JSON-shaped substring that could only
+		// appear via stringification.
+		const allText = visibleTexts.join("\n");
+		assert.ok(
+			!allText.includes('"structuredContent"'),
+			"rendered content must not include the pseudo-block type marker as JSON text",
+		);
+		assert.ok(
+			!allText.includes('"structured_content"'),
+			"rendered content must not include the snake_case pseudo-block type marker as JSON text",
+		);
+	});
+
+	test("extractToolResultsFromSdkUserMessage accepts snake_case structured_content defensively (#4472)", () => {
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-mcp-3",
+			message: {
+				role: "user",
+				content: [
+					{
+						type: "mcp_tool_result",
+						tool_use_id: "tool-mcp-3",
+						content: [{ type: "text", text: "ok" }],
+						structured_content: { operation: "save_gate_result" },
+					} as unknown as Record<string, unknown>,
+				],
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.deepEqual(results[0].result.details, { operation: "save_gate_result" });
+	});
+
 	test("extractToolResultsFromSdkUserMessage falls back to tool_use_result", () => {
 		const message: SDKUserMessage = {
 			type: "user",
@@ -398,12 +577,79 @@ describe("stream-adapter — Claude Code external tool results", () => {
 				toolUseId: "tool-read-1",
 				result: {
 					content: [{ type: "text", text: "file contents" }],
-					details: {},
+					// undefined (not {}) per the restored nullable contract — see
+					// the analogous assertion in the tool_result test above.
+					details: undefined,
 					isError: true,
 				},
 			},
 		]);
 	});
+
+	test("buildFinalAssistantContent preserves intermediate tool calls with attached external results", () => {
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{
+					type: "toolCall",
+					id: "tool-bash-1",
+					name: "bash",
+					arguments: { command: "echo hi" },
+				} as any,
+			],
+			pendingContent: [{ type: "text", text: "All done." }],
+			toolResultsById: new Map([
+				[
+					"tool-bash-1",
+					{
+						content: [{ type: "text", text: "hi\n" }],
+						details: { source: "claude-code" },
+						isError: false,
+					},
+				],
+			]),
+		});
+
+		assert.equal(finalContent[0]?.type, "toolCall");
+		assert.deepEqual((finalContent[0] as any).externalResult, {
+			content: [{ type: "text", text: "hi\n" }],
+			details: { source: "claude-code" },
+			isError: false,
+		});
+		assert.deepEqual(finalContent[1], { type: "text", text: "All done." });
+	});
+
+	test("buildFinalAssistantContent keeps final-turn tool calls when result arrives without a synthetic user boundary", () => {
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [],
+			pendingContent: [
+				{
+					type: "toolCall",
+					id: "tool-read-1",
+					name: "read",
+					arguments: { path: "README.md" },
+				} as any,
+				{ type: "text", text: "Read complete." },
+			],
+			toolResultsById: new Map([
+				[
+					"tool-read-1",
+					{
+						content: [{ type: "text", text: "file contents" }],
+						details: { path: "README.md" },
+						isError: false,
+					},
+				],
+			]),
+		});
+
+		assert.equal(finalContent[0]?.type, "toolCall");
+		assert.deepEqual((finalContent[0] as any).externalResult, {
+			content: [{ type: "text", text: "file contents" }],
+			details: { path: "README.md" },
+			isError: false,
+		});
+		assert.deepEqual(finalContent[1], { type: "text", text: "Read complete." });
+	});
 });
 
 describe("stream-adapter — session persistence (#2859)", () => {
@@ -536,19 +782,14 @@ describe("stream-adapter — session persistence (#2859)", () => {
 	});
 
 	test("buildSdkOptions includes workflow MCP server config when env is set", () => {
-		const prev = {
-			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
-			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
-			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
-			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
-			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
-		};
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
 		try {
-			process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
-			process.env.GSD_WORKFLOW_MCP_NAME = "gsd-workflow";
-			process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify(["packages/mcp-server/dist/cli.js"]);
-			process.env.GSD_WORKFLOW_MCP_ENV = JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" });
-			process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project";
 
 			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
 			const mcpServers = options.mcpServers as Record<string, any>;
@@ -560,72 +801,63 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
 			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.disallowedTools, []);
 			assert.deepEqual(options.allowedTools, [
 				"Read",
 				"Write",
 				"Edit",
 				"Glob",
 				"Grep",
-				"Bash(ls:*)",
-				"Bash(pwd)",
+				"Bash",
+				"Agent",
+				"WebFetch",
+				"WebSearch",
+				"AskUserQuestion",
 				"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;
-			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
-			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
-			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
+			restore();
 		}
 	});
 
-	test("buildSdkOptions disables AskUserQuestion for custom workflow MCP server names", () => {
-		const prev = {
-			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
-			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
-			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
-			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
-			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
-		};
+	test("buildSdkOptions auto-approves every tool for custom workflow MCP server names", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "custom-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
 		try {
-			process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
-			process.env.GSD_WORKFLOW_MCP_NAME = "custom-workflow";
-			process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify(["packages/mcp-server/dist/cli.js"]);
-			process.env.GSD_WORKFLOW_MCP_ENV = JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" });
-			process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project";
 
 			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
 			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.disallowedTools, []);
 			assert.deepEqual(options.allowedTools, [
 				"Read",
 				"Write",
 				"Edit",
 				"Glob",
 				"Grep",
-				"Bash(ls:*)",
-				"Bash(pwd)",
+				"Bash",
+				"Agent",
+				"WebFetch",
+				"WebSearch",
+				"AskUserQuestion",
 				"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;
-			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
-			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
-			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
+			restore();
 		}
 	});
 
 	test("buildSdkOptions auto-discovers bundled MCP server even without env hints", () => {
-		const prev = {
-			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
-			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
-			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
-			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
-			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
-		};
+		// Use setWorkflowMcpEnv with no values to save current state;
+		// restore() in finally will put it back correctly (including
+		// deleting any keys that started as undefined — the #4808 bug
+		// the naive `process.env.X = prev.X` pattern introduced).
+		const restore = setWorkflowMcpEnv({});
 		try {
 			delete process.env.GSD_WORKFLOW_MCP_COMMAND;
 			delete process.env.GSD_WORKFLOW_MCP_NAME;
@@ -644,29 +876,21 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const mcpServers = (options as any).mcpServers;
 			if (mcpServers) {
 				assert.ok(mcpServers["gsd-workflow"], "if present, must be gsd-workflow");
-				assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]);
+				assert.deepEqual((options as any).disallowedTools, []);
 			} else {
-				assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]);
+				assert.deepEqual((options as any).disallowedTools, []);
 			}
 			rmSync(emptyDir, { recursive: true, force: true });
 		} finally {
-			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
-			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
-			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
-			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
-			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
+			restore();
 		}
 	});
 
 	test("buildSdkOptions auto-detects local workflow MCP dist CLI when present", () => {
-		const prev = {
-			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
-			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
-			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
-			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
-			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
-			GSD_CLI_PATH: process.env.GSD_CLI_PATH,
-		};
+		// GSD_CLI_PATH isn't in WORKFLOW_MCP_ENV_KEYS, so save+restore it
+		// manually around setWorkflowMcpEnv which handles the MCP keys.
+		const prevCliPath = process.env.GSD_CLI_PATH;
+		const restore = setWorkflowMcpEnv({});
 		const originalCwd = process.cwd();
 		const repoDir = mkdtempSync(join(tmpdir(), "claude-mcp-detect-"));
 		try {
@@ -693,27 +917,22 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
 			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
 			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, resolvedRepoDir);
-			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+			assert.deepEqual(options.disallowedTools, []);
 		} finally {
 			process.chdir(originalCwd);
 			rmSync(repoDir, { recursive: true, force: true });
-			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
-			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
-			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
-			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
-			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
-			process.env.GSD_CLI_PATH = prev.GSD_CLI_PATH;
+			restore();
+			// GSD_CLI_PATH isn't in setWorkflowMcpEnv's scope — restore it here.
+			if (prevCliPath === undefined) {
+				delete process.env.GSD_CLI_PATH;
+			} else {
+				process.env.GSD_CLI_PATH = prevCliPath;
+			}
 		}
 	});
 
 	test("buildSdkOptions preserves runtime callbacks such as onElicitation", () => {
-		const prev = {
-			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
-			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
-			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
-			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
-			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
-		};
+		const restore = setWorkflowMcpEnv({});
 		const onElicitation = async () => ({ action: "decline" as const });
 		try {
 			delete process.env.GSD_WORKFLOW_MCP_COMMAND;
@@ -724,11 +943,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			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;
-			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
-			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
-			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
-			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
+			restore();
 		}
 	});
 });
@@ -1081,11 +1296,15 @@ describe("stream-adapter — permission mode (F10)", () => {
 		}
 	}
 
-	test("buildSdkOptions defaults to bypassPermissions for backwards compatibility", () => {
+	test("buildSdkOptions defaults to bypassPermissions (globally unblocks all tools)", () => {
 		clearWorkflowMcpEnv();
 		const opts = buildSdkOptions("claude-sonnet-4-6", "test");
 		assert.equal(opts.permissionMode, "bypassPermissions");
-		assert.equal(opts.allowDangerouslySkipPermissions, true);
+		assert.equal(
+			opts.allowDangerouslySkipPermissions,
+			true,
+			"allowDangerouslySkipPermissions must be true when permissionMode is bypassPermissions",
+		);
 	});
 
 	test("buildSdkOptions respects explicit acceptEdits override", () => {
@@ -1099,6 +1318,11 @@ describe("stream-adapter — permission mode (F10)", () => {
 		);
 	});
 
+	test("resolveClaudePermissionMode defaults to bypassPermissions when no env var is set (globally unblocks all tools)", async () => {
+		const mode = await resolveClaudePermissionMode({});
+		assert.equal(mode, "bypassPermissions");
+	});
+
 	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);
@@ -1114,6 +1338,27 @@ describe("stream-adapter — permission mode (F10)", () => {
 			`expected bypass or acceptEdits, got ${mode}`,
 		);
 	});
+
+	test("resolveClaudePermissionMode flips to bypassPermissions when GSD_HEADLESS=1 (#4657)", async () => {
+		const originalWarn = console.warn;
+		console.warn = () => {};
+		try {
+			const env = { GSD_HEADLESS: "1" } as NodeJS.ProcessEnv;
+			const mode = await resolveClaudePermissionMode(env);
+			assert.equal(mode, "bypassPermissions");
+		} finally {
+			console.warn = originalWarn;
+		}
+	});
+
+	test("resolveClaudePermissionMode: explicit override wins over GSD_HEADLESS=1", async () => {
+		const env = {
+			GSD_HEADLESS: "1",
+			GSD_CLAUDE_CODE_PERMISSION_MODE: "acceptEdits",
+		} as NodeJS.ProcessEnv;
+		const mode = await resolveClaudePermissionMode(env);
+		assert.equal(mode, "acceptEdits");
+	});
 });
 
 describe("stream-adapter — Windows Claude path lookup (#3770)", () => {

package/src/resources/extensions/cmux/index.ts

@@ -2,8 +2,12 @@ import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { GSDPreferences } from "../gsd/preferences.js";
-import type { GSDState, Phase } from "../gsd/types.js";
+import { CMUX_CHANNELS, type CmuxSidebarEvent, type CmuxLogEvent, type CmuxPreferencesInput, type CmuxStateInput } from "../shared/cmux-events.js";
+import type { EventBus } from "@gsd/pi-coding-agent";
+
+type CmuxPreferences = CmuxPreferencesInput;
+type CmuxState = CmuxStateInput;
+type Phase = string;
 const DEFAULT_SOCKET_PATH = "/tmp/cmux.sock";
 const STATUS_KEY = "gsd";
 const lastSidebarSnapshots = new Map<string, string>();
@@ -52,7 +56,7 @@ export function detectCmuxEnvironment(
 }
 
 export function resolveCmuxConfig(
-  preferences: GSDPreferences | undefined,
+  preferences: CmuxPreferences | undefined,
   env: NodeJS.ProcessEnv = process.env,
   socketExists: (path: string) => boolean = existsSync,
   cliAvailable: () => boolean = isCmuxCliAvailable,
@@ -71,7 +75,7 @@ export function resolveCmuxConfig(
 }
 
 export function shouldPromptToEnableCmux(
-  preferences: GSDPreferences | undefined,
+  preferences: CmuxPreferences | undefined,
   env: NodeJS.ProcessEnv = process.env,
   socketExists: (path: string) => boolean = existsSync,
   cliAvailable: () => boolean = isCmuxCliAvailable,
@@ -113,7 +117,7 @@ export function emitOsc777Notification(title: string, body: string): void {
   process.stdout.write(`\x1b]777;notify;${safeTitle};${safeBody}\x07`);
 }
 
-export function buildCmuxStatusLabel(state: GSDState): string {
+export function buildCmuxStatusLabel(state: CmuxState): string {
   const parts: string[] = [];
   if (state.activeMilestone) parts.push(state.activeMilestone.id);
   if (state.activeSlice) parts.push(state.activeSlice.id);
@@ -125,7 +129,7 @@ export function buildCmuxStatusLabel(state: GSDState): string {
   return `${parts.join(" ")} · ${state.phase}`;
 }
 
-export function buildCmuxProgress(state: GSDState): CmuxSidebarProgress | null {
+export function buildCmuxProgress(state: CmuxState): CmuxSidebarProgress | null {
   const progress = state.progress;
   if (!progress) return null;
 
@@ -171,7 +175,7 @@ export class CmuxClient {
     this.config = config;
   }
 
-  static fromPreferences(preferences: GSDPreferences | undefined): CmuxClient {
+  static fromPreferences(preferences: CmuxPreferences | undefined): CmuxClient {
     return new CmuxClient(resolveCmuxConfig(preferences));
   }
 
@@ -372,7 +376,7 @@ export class CmuxClient {
   }
 }
 
-export function syncCmuxSidebar(preferences: GSDPreferences | undefined, state: GSDState): void {
+export function syncCmuxSidebar(preferences: CmuxPreferences | undefined, state: CmuxState): void {
   const client = CmuxClient.fromPreferences(preferences);
   const config = client.getConfig();
   if (!config.sidebar) return;
@@ -388,7 +392,7 @@ export function syncCmuxSidebar(preferences: GSDPreferences | undefined, state:
   lastSidebarSnapshots.set(key, snapshot);
 }
 
-export function clearCmuxSidebar(preferences: GSDPreferences | undefined): void {
+export function clearCmuxSidebar(preferences: CmuxPreferences | undefined): void {
   const config = resolveCmuxConfig(preferences);
   if (!config.available || !config.cliAvailable) return;
   const client = new CmuxClient({ ...config, enabled: true, sidebar: true });
@@ -399,7 +403,7 @@ export function clearCmuxSidebar(preferences: GSDPreferences | undefined): void
 }
 
 export function logCmuxEvent(
-  preferences: GSDPreferences | undefined,
+  preferences: CmuxPreferences | undefined,
   message: string,
   level: CmuxLogLevel = "info",
 ): void {
@@ -446,3 +450,24 @@ function extractSurfaceIds(value: unknown): string[] {
   visit(value);
   return Array.from(found);
 }
+
+/**
+ * Wire event subscriptions so cmux reacts to gsd events.
+ * Called by the gsd extension during registration, passing pi.events.
+ */
+export function initCmuxEventListeners(events: EventBus): void {
+  events.on(CMUX_CHANNELS.SIDEBAR, (data) => {
+    const event = data as CmuxSidebarEvent;
+    if (event.action === "sync" && event.state) {
+      syncCmuxSidebar(event.preferences as CmuxPreferences | undefined, event.state as CmuxState);
+    }
+    if (event.action === "clear") {
+      clearCmuxSidebar(event.preferences as CmuxPreferences | undefined);
+    }
+  });
+
+  events.on(CMUX_CHANNELS.LOG, (data) => {
+    const event = data as CmuxLogEvent;
+    logCmuxEvent(event.preferences as CmuxPreferences | undefined, event.message, event.level);
+  });
+}