gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -8,10 +8,15 @@ import {
 	getResultErrorMessage,
 	makeAbortedMessage,
 	mergePendingToolCalls,
+	buildFinalAssistantContent,
 	resolveClaudePermissionMode,
 	buildPromptFromContext,
 	buildSdkQueryPrompt,
 	buildSdkOptions,
+	createClaudeCodeCanUseToolHandler,
+	buildBashPermissionPattern,
+	buildBashPermissionPatternOptions,
+	bashCommandMatchesSavedRules,
 	createClaudeCodeElicitationHandler,
 	extractImageBlocksFromContext,
 	extractToolResultsFromSdkUserMessage,
@@ -19,11 +24,58 @@ import {
 	parseAskUserQuestionsElicitation,
 	parseTextInputElicitation,
 	parseClaudeLookupOutput,
+	resolveBundledClaudeCliPath,
+	normalizeClaudePathForSdk,
 	roundResultToElicitationContent,
 } from "../stream-adapter.ts";
 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 +424,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 +583,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 +788,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 +807,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 +882,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 +923,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 +949,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 +1302,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 +1324,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 +1344,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)", () => {
@@ -1126,8 +1377,838 @@ describe("stream-adapter — Windows Claude path lookup (#3770)", () => {
 		assert.equal(getClaudeLookupCommand("linux"), "which claude");
 	});
 
-	test("parseClaudeLookupOutput keeps the first native path from multi-line lookup output", () => {
-		const output = "C:\\Users\\Binoy\\.local\\bin\\claude.exe\r\nC:\\Program Files\\Claude\\claude.exe\r\n";
-		assert.equal(parseClaudeLookupOutput(output), "C:\\Users\\Binoy\\.local\\bin\\claude.exe");
+	test("parseClaudeLookupOutput prefers .exe on win32 when where output includes shims", () => {
+		const output = [
+			"C:\\Users\\djeff\\AppData\\Roaming\\npm\\claude",
+			"C:\\Users\\djeff\\AppData\\Roaming\\npm\\claude.cmd",
+			"C:\\Program Files\\Claude\\claude.exe",
+		].join("\r\n");
+		assert.equal(parseClaudeLookupOutput(output, "win32"), "C:\\Program Files\\Claude\\claude.exe");
+	});
+
+	test("parseClaudeLookupOutput keeps first line on non-win32 platforms", () => {
+		const output = "/usr/local/bin/claude\n/opt/homebrew/bin/claude\n";
+		assert.equal(parseClaudeLookupOutput(output, "darwin"), "/usr/local/bin/claude");
+	});
+
+	test("normalizeClaudePathForSdk swaps Windows shim paths to bundled cli.js", () => {
+		const shimPath = "C:\\Users\\djeff\\AppData\\Roaming\\npm\\claude";
+		const bundled = "C:\\repo\\node_modules\\@anthropic-ai\\claude-agent-sdk\\cli.js";
+		assert.equal(normalizeClaudePathForSdk(shimPath, "win32", bundled), bundled);
+		assert.equal(normalizeClaudePathForSdk("C:\\Program Files\\Claude\\claude.exe", "win32", bundled), "C:\\Program Files\\Claude\\claude.exe");
+	});
+
+	test("resolveBundledClaudeCliPath returns a .js path when SDK package is present", () => {
+		const resolved = resolveBundledClaudeCliPath();
+		assert.ok(resolved, "expected sdk cli.js to be resolvable in test workspace");
+		assert.match(resolved!, /[\\/]@anthropic-ai[\\/]claude-agent-sdk[\\/]cli\.js$/);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// canUseTool handler (#4383)
+// ---------------------------------------------------------------------------
+
+describe("stream-adapter — canUseTool handler", () => {
+	function makeOptions(overrides: Partial<{ signal: AbortSignal; suggestions: Array<Record<string, unknown>>; title: string; description: string; toolUseID: string }> = {}) {
+		return {
+			signal: overrides.signal ?? new AbortController().signal,
+			toolUseID: overrides.toolUseID ?? "toolu_test123",
+			...(overrides.title !== undefined ? { title: overrides.title } : {}),
+			...(overrides.description !== undefined ? { description: overrides.description } : {}),
+			...(overrides.suggestions !== undefined ? { suggestions: overrides.suggestions } : {}),
+		};
+	}
+
+	// Point process.cwd() at an empty temp dir so the real repo's
+	// .claude/settings.local.json (which may already contain rules like
+	// "Bash(gh pr list:*)") does not short-circuit the permission flow.
+	// Returns a cleanup function that restores cwd and removes the temp dir.
+	// biome-ignore lint/suspicious/noExplicitAny: test-only monkey-patch
+	function withIsolatedCwd(): () => void {
+		const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-canusetool-")));
+		const orig = process.cwd;
+		process.cwd = () => dir;
+		return () => {
+			process.cwd = orig;
+			rmSync(dir, { recursive: true, force: true });
+		};
+	}
+
+	test("returns undefined when no UI context is provided", () => {
+		const handler = createClaudeCodeCanUseToolHandler(undefined);
+		assert.equal(handler, undefined);
+	});
+
+	test("shows select dialog with Allow/Always Allow/Deny and returns allow", async () => {
+		let selectPrompt = "";
+		let selectOptions: string[] = [];
+		const ui = {
+			select: async (prompt: string, options: string[]) => {
+				selectPrompt = prompt;
+				selectOptions = options;
+				return "Allow";
+			},
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		assert.ok(handler);
+
+		const input = { command: "ls -la" };
+		const result = await handler!("Bash", input, makeOptions({
+			title: "Claude wants to run: ls -la",
+			description: "List directory contents",
+		}));
+
+		assert.equal(result.behavior, "allow");
+		assert.deepEqual((result as any).updatedInput, input);
+		assert.equal((result as any).toolUseID, "toolu_test123");
+		// Allow (one-time) should NOT include updatedPermissions
+		assert.equal((result as any).updatedPermissions, undefined);
+		assert.deepEqual(selectOptions, ["Allow", "Always Allow", "Deny"]);
+		// Prompt includes title and input summary
+		assert.ok(selectPrompt.includes("Claude wants to run: ls -la"));
+		assert.ok(selectPrompt.includes("ls -la"));
+	});
+
+	test("returns deny when user selects Deny", async () => {
+		const ui = {
+			select: async () => "Deny",
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Bash", { command: "rm -rf /" }, makeOptions());
+
+		assert.equal(result.behavior, "deny");
+		assert.equal((result as any).message, "User denied");
+		assert.equal((result as any).toolUseID, "toolu_test123");
+	});
+
+	test("returns deny when user dismisses dialog (undefined)", async () => {
+		const ui = {
+			select: async () => undefined,
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Bash", { command: "echo hi" }, makeOptions());
+
+		assert.equal(result.behavior, "deny");
+		assert.equal((result as any).message, "User denied");
+	});
+
+	test("Always Allow for Bash patches SDK suggestions with smart ruleContent", async () => {
+		const notified: string[] = [];
+		const ui = { select: async (_p: string, opts: string[]) => opts.find((o) => o.startsWith("Always Allow"))!, notify: (msg: string) => notified.push(msg) };
+		const suggestions = [{
+			type: "addRules",
+			rules: [{ toolName: "Bash", ruleContent: "ls -la /tmp" }],
+			behavior: "allow",
+			destination: "localSettings",
+		}];
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Bash", { command: "ls -la /tmp" }, makeOptions({ suggestions }));
+
+		assert.equal(result.behavior, "allow");
+		// Should patch ruleContent with our smart pattern, preserving SDK structure
+		assert.deepEqual((result as any).updatedPermissions, [{
+			type: "addRules",
+			rules: [{ toolName: "Bash", ruleContent: "ls:*" }],
+			behavior: "allow",
+			destination: "localSettings",
+		}]);
+		assert.equal(notified.length, 1);
+		assert.ok(notified[0].includes("Saved:") && notified[0].includes("Bash(ls:*)"));
+	});
+
+	test("Always Allow for Bash with subcommand-sensitive CLI captures verb", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			const notified: string[] = [];
+			// First select call: pick "Always Allow ..."; second call (level
+			// picker): pick the "git push" granularity explicitly.
+			let selectCall = 0;
+			const ui = {
+				select: async (_p: string, opts: string[]) => {
+					selectCall++;
+					if (selectCall === 1) return opts.find((o) => o.startsWith("Always Allow"))!;
+					return "Bash(git push:*)";
+				},
+				notify: (msg: string) => notified.push(msg),
+			};
+			const suggestions = [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "git push origin main" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}];
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "git push origin main" }, makeOptions({ suggestions }));
+
+			assert.equal(result.behavior, "allow");
+			assert.deepEqual((result as any).updatedPermissions, [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "git push:*" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}]);
+			assert.ok(notified[0].includes("Saved:") && notified[0].includes("Bash(git push:*)"));
+		} finally {
+			cleanup();
+		}
+	});
+
+	test("Always Allow for Bash without suggestions builds proper PermissionUpdate", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			const notified: string[] = [];
+			let selectCall = 0;
+			const ui = {
+				select: async (_p: string, opts: string[]) => {
+					selectCall++;
+					if (selectCall === 1) return opts.find((o) => o.startsWith("Always Allow"))!;
+					return "Bash(gh pr list:*)";
+				},
+				notify: (msg: string) => notified.push(msg),
+			};
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "gh pr list" }, makeOptions());
+
+			assert.equal(result.behavior, "allow");
+			// No SDK suggestions → builds PermissionUpdate from scratch
+			assert.deepEqual((result as any).updatedPermissions, [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "gh pr list:*" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}]);
+			assert.ok(notified[0].includes("Saved:") && notified[0].includes("Bash(gh pr list:*)"));
+		} finally {
+			cleanup();
+		}
+	});
+
+	test("Always Allow for non-Bash tools passes SDK suggestions through", async () => {
+		const notified: string[] = [];
+		const ui = { select: async (_p: string, opts: string[]) => opts.find((o) => o.startsWith("Always Allow"))!, notify: (msg: string) => notified.push(msg) };
+		const suggestions = [{
+			type: "addRules",
+			rules: [{ toolName: "Write" }],
+			behavior: "allow",
+			destination: "localSettings",
+		}];
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Write", { file_path: "/tmp/test.txt" }, makeOptions({ suggestions }));
+
+		assert.equal(result.behavior, "allow");
+		assert.deepEqual((result as any).updatedPermissions, suggestions);
+		// Non-Bash tools don't emit a post-selection notification (only Bash runs the level picker)
+		assert.equal(notified.length, 0);
+	});
+
+	test("Always Allow for non-Bash without suggestions omits updatedPermissions", async () => {
+		const notified: string[] = [];
+		const ui = { select: async (_p: string, opts: string[]) => opts.find((o) => o.startsWith("Always Allow"))!, notify: (msg: string) => notified.push(msg) };
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Write", { file_path: "/tmp/test.txt" }, makeOptions());
+
+		assert.equal(result.behavior, "allow");
+		assert.equal((result as any).updatedPermissions, undefined);
+		// No suggestions → no notification
+		assert.equal(notified.length, 0);
+	});
+
+	test("prompt includes command text for Bash tools", async () => {
+		let selectPrompt = "";
+		const ui = {
+			select: async (prompt: string) => {
+				selectPrompt = prompt;
+				return "Allow";
+			},
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		await handler!("Bash", { command: "git status" }, makeOptions());
+		assert.ok(selectPrompt.includes("git status"), `prompt should include command: ${selectPrompt}`);
+	});
+
+	test("prompt includes file_path for file tools", async () => {
+		let selectPrompt = "";
+		const ui = {
+			select: async (prompt: string) => {
+				selectPrompt = prompt;
+				return "Allow";
+			},
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		await handler!("Write", { file_path: "/tmp/test.txt", content: "hello" }, makeOptions());
+		assert.ok(selectPrompt.includes("/tmp/test.txt"), `prompt should include file path: ${selectPrompt}`);
+	});
+
+	test("uses title from options when available", async () => {
+		let selectPrompt = "";
+		const ui = {
+			select: async (prompt: string) => {
+				selectPrompt = prompt;
+				return "Allow";
+			},
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		await handler!("WebFetch", {}, makeOptions({ title: "Claude wants to fetch: https://example.com" }));
+		assert.ok(selectPrompt.includes("Claude wants to fetch: https://example.com"));
+	});
+
+	test("falls back to default title when options.title is missing", async () => {
+		let selectPrompt = "";
+		const ui = {
+			select: async (prompt: string) => {
+				selectPrompt = prompt;
+				return "Allow";
+			},
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		await handler!("WebFetch", { url: "https://example.com" }, makeOptions());
+		assert.ok(selectPrompt.includes("Allow Claude Code to use: WebFetch?"));
+	});
+
+	test("returns deny when signal is already aborted", async () => {
+		const ui = {
+			select: async () => { throw new Error("should not be called"); },
+		};
+
+		const controller = new AbortController();
+		controller.abort();
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Bash", {}, makeOptions({ signal: controller.signal }));
+
+		assert.equal(result.behavior, "deny");
+		assert.equal((result as any).message, "Aborted");
+	});
+
+	test("returns deny when ui.select throws", async () => {
+		const ui = {
+			select: async () => { throw new Error("dialog crashed"); },
+		};
+
+		const handler = createClaudeCodeCanUseToolHandler(ui as any);
+		const result = await handler!("Bash", {}, makeOptions());
+
+		assert.equal(result.behavior, "deny");
+		assert.equal((result as any).message, "Aborted");
+	});
+
+	test("buildSdkOptions passes canUseTool through extraOptions", () => {
+		const canUseTool = async () => ({ behavior: "allow" as const, updatedInput: {}, toolUseID: "test" });
+		const opts = buildSdkOptions("claude-sonnet-4-6", "test", undefined, { canUseTool });
+		assert.equal(opts.canUseTool, canUseTool);
+	});
+
+	test("Always Allow shows level picker and user broadens to base command", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			const prompts: string[] = [];
+			const levelOpts: string[][] = [];
+			let selectCall = 0;
+			const ui = {
+				select: async (prompt: string, opts: string[]) => {
+					prompts.push(prompt);
+					selectCall++;
+					if (selectCall === 1) return opts.find((o) => o.startsWith("Always Allow"))!;
+					levelOpts.push(opts);
+					return "Bash(gh:*)";
+				},
+				notify: () => {},
+			};
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "gh pr list" }, makeOptions());
+
+			assert.equal(result.behavior, "allow");
+			assert.deepEqual((result as any).updatedPermissions, [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "gh:*" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}]);
+			// Second dialog offered every granularity level
+			assert.deepEqual(levelOpts[0], [
+				"Bash(gh:*)",
+				"Bash(gh pr:*)",
+				"Bash(gh pr list:*)",
+			]);
+			assert.ok(prompts[1].includes("Save permission at which level?"));
+		} finally {
+			cleanup();
+		}
+	});
+
+	test("Always Allow narrows to mid-level pattern when user picks Bash(gh pr:*)", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			let selectCall = 0;
+			const ui = {
+				select: async (_p: string, opts: string[]) => {
+					selectCall++;
+					if (selectCall === 1) return opts.find((o) => o.startsWith("Always Allow"))!;
+					return "Bash(gh pr:*)";
+				},
+				notify: () => {},
+			};
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "gh pr list --limit 5" }, makeOptions());
+
+			assert.equal(result.behavior, "allow");
+			assert.deepEqual((result as any).updatedPermissions, [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "gh pr:*" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}]);
+		} finally {
+			cleanup();
+		}
+	});
+
+	test("Always Allow skips level picker when only one pattern is available", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			const prompts: string[] = [];
+			const ui = {
+				select: async (prompt: string, opts: string[]) => {
+					prompts.push(prompt);
+					return opts.find((o) => o.startsWith("Always Allow"))!;
+				},
+				notify: () => {},
+			};
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "ls -la /tmp" }, makeOptions());
+
+			assert.equal(result.behavior, "allow");
+			// "ls" has no subcommand tokens before the flag → single-option path
+			assert.equal(prompts.length, 1, "should not show a second dialog");
+			assert.deepEqual((result as any).updatedPermissions, [{
+				type: "addRules",
+				rules: [{ toolName: "Bash", ruleContent: "ls:*" }],
+				behavior: "allow",
+				destination: "localSettings",
+			}]);
+		} finally {
+			cleanup();
+		}
+	});
+
+	test("Always Allow denies the tool when level picker is dismissed", async () => {
+		const cleanup = withIsolatedCwd();
+		try {
+			const notified: string[] = [];
+			let selectCall = 0;
+			const ui = {
+				select: async (_p: string, opts: string[]) => {
+					selectCall++;
+					if (selectCall === 1) return opts.find((o) => o.startsWith("Always Allow"))!;
+					return undefined; // user dismissed level picker
+				},
+				notify: (msg: string) => notified.push(msg),
+			};
+
+			const handler = createClaudeCodeCanUseToolHandler(ui as any);
+			const result = await handler!("Bash", { command: "gh pr list" }, makeOptions());
+
+			// Dismissing the level picker cancels the tool use — a one-time allow
+			// would leave the spawned agent running even though the user bailed.
+			assert.equal(result.behavior, "deny");
+			assert.equal((result as any).updatedPermissions, undefined);
+			assert.equal(notified.length, 0, "no 'Saved:' notification when nothing was saved");
+		} finally {
+			cleanup();
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// buildBashPermissionPattern — smart permission granularity
+// ---------------------------------------------------------------------------
+
+describe("buildBashPermissionPattern", () => {
+	test("simple command wildcards all args", () => {
+		assert.equal(buildBashPermissionPattern("ping -n 4 localhost"), "Bash(ping:*)");
+		assert.equal(buildBashPermissionPattern("echo hello world"), "Bash(echo:*)");
+		assert.equal(buildBashPermissionPattern("ls -la /tmp"), "Bash(ls:*)");
+		assert.equal(buildBashPermissionPattern("node server.js"), "Bash(node:*)");
+	});
+
+	test("git captures one subcommand", () => {
+		assert.equal(buildBashPermissionPattern("git push origin main"), "Bash(git push:*)");
+		assert.equal(buildBashPermissionPattern("git log --oneline"), "Bash(git log:*)");
+		assert.equal(buildBashPermissionPattern("git status"), "Bash(git status:*)");
+	});
+
+	test("gh captures two subcommands", () => {
+		assert.equal(buildBashPermissionPattern("gh pr list"), "Bash(gh pr list:*)");
+		assert.equal(buildBashPermissionPattern("gh pr create --title foo"), "Bash(gh pr create:*)");
+		assert.equal(buildBashPermissionPattern("gh issue view 123"), "Bash(gh issue view:*)");
+	});
+
+	test("npm captures one subcommand", () => {
+		assert.equal(buildBashPermissionPattern("npm install lodash"), "Bash(npm install:*)");
+		assert.equal(buildBashPermissionPattern("npm publish"), "Bash(npm publish:*)");
+		assert.equal(buildBashPermissionPattern("npm run test"), "Bash(npm run:*)");
+	});
+
+	test("npx captures package name", () => {
+		assert.equal(buildBashPermissionPattern("npx vitest run"), "Bash(npx vitest:*)");
+		assert.equal(buildBashPermissionPattern("npx --version"), "Bash(npx --version:*)");
+	});
+
+	test("docker captures one subcommand", () => {
+		assert.equal(buildBashPermissionPattern("docker ps -a"), "Bash(docker ps:*)");
+		assert.equal(buildBashPermissionPattern("docker rm container1"), "Bash(docker rm:*)");
+	});
+
+	test("aws captures two subcommands", () => {
+		assert.equal(buildBashPermissionPattern("aws s3 cp file.txt s3://bucket/"), "Bash(aws s3 cp:*)");
+		assert.equal(buildBashPermissionPattern("aws ec2 describe-instances"), "Bash(aws ec2 describe-instances:*)");
+	});
+
+	test("skips sudo wrapper", () => {
+		assert.equal(buildBashPermissionPattern("sudo ping localhost"), "Bash(ping:*)");
+		assert.equal(buildBashPermissionPattern("sudo git push"), "Bash(git push:*)");
+	});
+
+	test("skips env wrapper and VAR=val assignments", () => {
+		assert.equal(buildBashPermissionPattern("env NODE_ENV=prod node server.js"), "Bash(node:*)");
+		assert.equal(buildBashPermissionPattern("NODE_ENV=prod node server.js"), "Bash(node:*)");
+		assert.equal(buildBashPermissionPattern("FOO=bar BAZ=qux git push"), "Bash(git push:*)");
+	});
+
+	test("strips path from executable", () => {
+		assert.equal(buildBashPermissionPattern("/usr/bin/git push"), "Bash(git push:*)");
+		assert.equal(buildBashPermissionPattern("C:\\Windows\\ping.exe localhost"), "Bash(ping:*)");
+	});
+
+	test("empty or whitespace-only command", () => {
+		assert.equal(buildBashPermissionPattern(""), "Bash(*)");
+		assert.equal(buildBashPermissionPattern("   "), "Bash(*)");
+	});
+
+	test("chained commands — extracts pattern from the meaningful segment", () => {
+		assert.equal(buildBashPermissionPattern("cd /foo && gh pr list --limit 5"), "Bash(gh pr list:*)");
+		assert.equal(buildBashPermissionPattern("cd C:/Users/djeff/repos/gsd-2 && gh pr list --limit 5"), "Bash(gh pr list:*)");
+		assert.equal(buildBashPermissionPattern("cd /tmp && git push origin main"), "Bash(git push:*)");
+		assert.equal(buildBashPermissionPattern("export FOO=1 && npm install lodash"), "Bash(npm install:*)");
+		assert.equal(buildBashPermissionPattern("mkdir -p out; docker ps -a"), "Bash(docker ps:*)");
+		assert.equal(buildBashPermissionPattern("echo start || ping localhost"), "Bash(ping:*)");
+	});
+
+	test("skips trailing || true / || : error suppressors", () => {
+		assert.equal(
+			buildBashPermissionPattern("cd C:/Users/djeff/repos/gsd-2 && gh pr create --dry-run --title \"test\" --body \"test\" 2>&1 || true"),
+			"Bash(gh pr create:*)",
+		);
+		assert.equal(buildBashPermissionPattern("gh pr list || true"), "Bash(gh pr list:*)");
+		assert.equal(buildBashPermissionPattern("git push || :"), "Bash(git push:*)");
+		assert.equal(buildBashPermissionPattern("cd /tmp && npm install || echo failed"), "Bash(npm install:*)");
+	});
+
+	test("single command is unaffected by chain extraction", () => {
+		assert.equal(buildBashPermissionPattern("gh pr list"), "Bash(gh pr list:*)");
+		assert.equal(buildBashPermissionPattern("git push origin main"), "Bash(git push:*)");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// buildBashPermissionPatternOptions — granularity level menu
+// ---------------------------------------------------------------------------
+
+describe("buildBashPermissionPatternOptions", () => {
+	test("offers every prefix from base to full subcommand chain", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions("gh pr list"), [
+			"Bash(gh:*)",
+			"Bash(gh pr:*)",
+			"Bash(gh pr list:*)",
+		]);
+		assert.deepEqual(buildBashPermissionPatternOptions("git push origin main"), [
+			"Bash(git:*)",
+			"Bash(git push:*)",
+			"Bash(git push origin:*)",
+			"Bash(git push origin main:*)",
+		]);
+	});
+
+	test("stops at first flag — flags are args, not verbs", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions("gh pr create --title foo"), [
+			"Bash(gh:*)",
+			"Bash(gh pr:*)",
+			"Bash(gh pr create:*)",
+		]);
+		assert.deepEqual(buildBashPermissionPatternOptions("git log --oneline"), [
+			"Bash(git:*)",
+			"Bash(git log:*)",
+		]);
+	});
+
+	test("single-option when there is no subcommand to choose from", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions("ls -la /tmp"), ["Bash(ls:*)"]);
+		assert.deepEqual(buildBashPermissionPatternOptions("ping -n 4 localhost"), ["Bash(ping:*)"]);
+		assert.deepEqual(buildBashPermissionPatternOptions("node"), ["Bash(node:*)"]);
+	});
+
+	test("extracts meaningful segment from compound commands", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions("cd /foo && gh pr list"), [
+			"Bash(gh:*)",
+			"Bash(gh pr:*)",
+			"Bash(gh pr list:*)",
+		]);
+		assert.deepEqual(buildBashPermissionPatternOptions("gh pr create --dry-run || true"), [
+			"Bash(gh:*)",
+			"Bash(gh pr:*)",
+			"Bash(gh pr create:*)",
+		]);
+	});
+
+	test("caps at three subcommand tokens to keep the menu short", () => {
+		const result = buildBashPermissionPatternOptions("foo bar baz qux quux corge");
+		// base + 3 sub tokens = 4 patterns max
+		assert.equal(result.length, 4);
+		assert.deepEqual(result, [
+			"Bash(foo:*)",
+			"Bash(foo bar:*)",
+			"Bash(foo bar baz:*)",
+			"Bash(foo bar baz qux:*)",
+		]);
+	});
+
+	test("skips sudo/env wrappers like the single-pattern variant", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions("sudo git push origin"), [
+			"Bash(git:*)",
+			"Bash(git push:*)",
+			"Bash(git push origin:*)",
+		]);
+		assert.deepEqual(buildBashPermissionPatternOptions("NODE_ENV=prod node server.js"), [
+			"Bash(node:*)",
+			"Bash(node server.js:*)",
+		]);
+	});
+
+	test("empty command returns the catch-all pattern", () => {
+		assert.deepEqual(buildBashPermissionPatternOptions(""), ["Bash(*)"]);
+		assert.deepEqual(buildBashPermissionPatternOptions("   "), ["Bash(*)"]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// bashCommandMatchesSavedRules — compound command bypass for saved rules
+// ---------------------------------------------------------------------------
+
+describe("bashCommandMatchesSavedRules — compound command bypass", () => {
+	let tempDir: string;
+	let originalCwd: string;
+
+	// Create a temp project directory with .claude/settings.local.json
+	function setupSettings(allow: string[]): void {
+		const claudeDir = join(tempDir, ".claude");
+		mkdirSync(claudeDir, { recursive: true });
+		writeFileSync(
+			join(claudeDir, "settings.local.json"),
+			JSON.stringify({ permissions: { allow } }),
+		);
+	}
+
+	// biome-ignore lint/suspicious/noExplicitAny: test-only monkey-patch
+	let origCwd: any;
+
+	// Monkey-patch process.cwd() to point at our temp dir
+	function setCwd(dir: string): void {
+		origCwd = process.cwd;
+		process.cwd = () => dir;
+	}
+	function restoreCwd(): void {
+		if (origCwd) process.cwd = origCwd;
+	}
+
+	test("matches cd-prefixed compound command against saved prefix rule", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /some/path && gh pr list --limit 5"),
+				true,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("matches cd-prefixed compound command with exact subcommand", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd C:/Users/foo/repos/bar && gh pr list"),
+				true,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("rejects when leading segment is not cd", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			// "rm -rf /tmp" is not a cd command — should not auto-approve
+			assert.equal(
+				bashCommandMatchesSavedRules("rm -rf /tmp && gh pr list"),
+				false,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("rejects when meaningful segment does not match any rule", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /path && gh issue create --title foo"),
+				false,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("matches simple (non-compound) commands against on-disk rules", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			// Simple commands must also be checked — the SDK's in-memory cache
+			// may be stale if the rule was added mid-session via "Always Allow"
+			assert.equal(bashCommandMatchesSavedRules("gh pr list --limit 5"), true);
+			assert.equal(bashCommandMatchesSavedRules("gh pr list"), true);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("returns false for simple commands with no matching rule", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr list:*)"]);
+			setCwd(tempDir);
+			assert.equal(bashCommandMatchesSavedRules("gh issue list --limit 5"), false);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("returns false when no settings file exists", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			// No .claude/settings.local.json created
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /path && gh pr list"),
+				false,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("matches exact rule (non-prefix)", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(ping -n 4 localhost)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /path && ping -n 4 localhost"),
+				true,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("handles multiple cd segments before the meaningful command", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(npm install:*)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /home && cd project && npm install lodash"),
+				true,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("matches compound command with trailing || true suppressor", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			setupSettings(["Bash(gh pr create:*)"]);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules('cd C:/Users/djeff/repos/gsd-2 && gh pr create --dry-run --title "test" --body "test" 2>&1 || true'),
+				true,
+			);
+			assert.equal(
+				bashCommandMatchesSavedRules("gh pr create --dry-run || true"),
+				true,
+			);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /tmp && git push || :"),
+				false, // rule is for gh pr create, not git push
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("reads rules from settings.json as well as settings.local.json", () => {
+		tempDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-rules-")));
+		try {
+			const claudeDir = join(tempDir, ".claude");
+			mkdirSync(claudeDir, { recursive: true });
+			writeFileSync(
+				join(claudeDir, "settings.json"),
+				JSON.stringify({ permissions: { allow: ["Bash(git push:*)"] } }),
+			);
+			setCwd(tempDir);
+			assert.equal(
+				bashCommandMatchesSavedRules("cd /repo && git push origin main"),
+				true,
+			);
+		} finally {
+			restoreCwd();
+			rmSync(tempDir, { recursive: true, force: true });
+		}
 	});
 });