gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -3,8 +3,9 @@
  *
  * The SDK runs the full agentic loop (multi-turn, tool execution, compaction)
  * in one call. This adapter translates the SDK's streaming output into
- * AssistantMessageEvents for TUI rendering, then strips tool-call blocks from
- * the final AssistantMessage so GSD's agent loop doesn't try to dispatch them.
+ * AssistantMessageEvents for TUI rendering, then preserves externally executed
+ * tool-call blocks on the final AssistantMessage so Agent Core can render them
+ * while `externalToolExecution` prevents local redispatch.
  */
 
 import type {
@@ -20,6 +21,10 @@ import type {
 import type { ExtensionUIContext } from "@gsd/pi-coding-agent";
 import { EventStream } from "@gsd/pi-ai";
 import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
@@ -177,34 +182,88 @@ export function getResultErrorMessage(result: SDKResultMessage): string {
 // Claude binary resolution
 // ---------------------------------------------------------------------------
 
-/** Cached result of the `which`/`where claude` lookup so the shell is only spawned once per process. */
+/** Cached result of the Claude executable/script resolution so lookup runs once per process. */
 let cachedClaudePath: string | null = null;
+const requireFromHere = createRequire(import.meta.url);
 
 /** Return the shell command used to locate the `claude` binary on the given platform. */
 export function getClaudeLookupCommand(platform: NodeJS.Platform = process.platform): string {
 	return platform === "win32" ? "where claude" : "which claude";
 }
 
-/** Extract the first line of `which`/`where` output as the resolved binary path. */
-export function parseClaudeLookupOutput(output: Buffer | string): string {
-	return output
+/**
+ * Pick the most suitable path from `which`/`where` output.
+ *
+ * On Windows, `where claude` can return shim entries first (for example
+ * `...\\npm\\claude` / `...\\npm\\claude.cmd`) that the Claude Agent SDK treats
+ * as a native executable path and then fails to spawn. Prefer a native
+ * `.exe` candidate when present.
+ */
+export function parseClaudeLookupOutput(output: Buffer | string, platform: NodeJS.Platform = process.platform): string {
+	const lines = output
 		.toString()
-		.trim()
-		.split(/\r?\n/)[0] ?? "";
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter(Boolean);
+
+	if (lines.length === 0) return "";
+	if (platform !== "win32") return lines[0] ?? "";
+
+	const exeCandidate = lines.find((line) => /\.exe$/i.test(line));
+	if (exeCandidate) return exeCandidate;
+
+	const cmdCandidate = lines.find((line) => /\.cmd$/i.test(line));
+	if (cmdCandidate) return cmdCandidate;
+
+	return lines[0] ?? "";
+}
+
+/** Resolve the SDK-bundled cli.js path if available. */
+export function resolveBundledClaudeCliPath(): string | null {
+	try {
+		const sdkEntry = requireFromHere.resolve("@anthropic-ai/claude-agent-sdk");
+		const cliPath = join(dirname(sdkEntry), "cli.js");
+		return existsSync(cliPath) ? cliPath : null;
+	} catch {
+		return null;
+	}
 }
 
 /**
- * Resolve the path to the system-installed `claude` binary.
- * The SDK defaults to a bundled cli.js which doesn't exist when
- * installed as a library — we need to point it at the real CLI.
+ * Normalize a discovered path for Claude Agent SDK consumption.
+ *
+ * On Windows, the SDK treats non-`.js` paths as native binaries. NPM shims
+ * like `claude`/`claude.cmd` are not native binaries and can fail with
+ * `ENOENT`/`EINVAL` in that mode. When no `.exe` is available, prefer the
+ * SDK-bundled `cli.js` so the SDK runs via Node.
  */
+export function normalizeClaudePathForSdk(
+	resolvedPath: string,
+	platform: NodeJS.Platform = process.platform,
+	bundledCliPath: string | null = resolveBundledClaudeCliPath(),
+): string {
+	if (platform !== "win32") return resolvedPath;
+	if (/\.exe$/i.test(resolvedPath)) return resolvedPath;
+	if (bundledCliPath) return bundledCliPath;
+	return resolvedPath;
+}
+
+/** Resolve the path passed to `pathToClaudeCodeExecutable`. */
 function getClaudePath(): string {
 	if (cachedClaudePath) return cachedClaudePath;
+
+	const fallback = process.platform === "win32"
+		? (resolveBundledClaudeCliPath() ?? "claude.cmd")
+		: "claude";
+
 	try {
-		cachedClaudePath = parseClaudeLookupOutput(execSync(getClaudeLookupCommand(), { timeout: 5_000, stdio: "pipe" }));
+		const lookupOutput = execSync(getClaudeLookupCommand(), { timeout: 5_000, stdio: "pipe" });
+		const parsed = parseClaudeLookupOutput(lookupOutput, process.platform);
+		cachedClaudePath = normalizeClaudePathForSdk(parsed || fallback, process.platform);
 	} catch {
-		cachedClaudePath = "claude"; // fall back to PATH resolution
+		cachedClaudePath = fallback;
 	}
+
 	return cachedClaudePath;
 }
 
@@ -631,6 +690,439 @@ async function promptTextInputElicitation(
 	return { action: "accept", content };
 }
 
+// ---------------------------------------------------------------------------
+// canUseTool handler
+// ---------------------------------------------------------------------------
+
+/** Options passed by the SDK to the canUseTool callback. */
+interface CanUseToolOptions {
+	signal: AbortSignal;
+	suggestions?: Array<Record<string, unknown>>;
+	blockedPath?: string;
+	decisionReason?: string;
+	title?: string;
+	displayName?: string;
+	description?: string;
+	toolUseID: string;
+	agentID?: string;
+}
+
+/** Result returned by the canUseTool callback to the SDK. */
+type CanUseToolPermissionResult =
+	| { behavior: "allow"; updatedInput?: Record<string, unknown>; updatedPermissions?: Array<Record<string, unknown>>; toolUseID?: string }
+	| { behavior: "deny"; message: string; interrupt?: boolean; toolUseID?: string };
+
+/**
+ * Known CLI tools where the subcommand verb changes the risk profile.
+ * Value = number of subcommand tokens (beyond the executable) to capture
+ * in the "Always Allow" permission pattern.
+ *
+ * `git push` and `git log` are very different → depth 1 → `Bash(git push:*)`
+ * `gh pr create` and `gh pr list` differ at depth 2 → `Bash(gh pr create:*)`
+ * `ping` is always safe → not listed → `Bash(ping:*)`
+ */
+const SUBCOMMAND_DEPTH: Record<string, number> = {
+	git: 1,
+	gh: 2,
+	npm: 1,
+	npx: 1,
+	yarn: 1,
+	pnpm: 1,
+	docker: 1,
+	kubectl: 1,
+	aws: 2,
+	az: 2,
+	gcloud: 2,
+	cargo: 1,
+	pip: 1,
+	pip3: 1,
+	brew: 1,
+	terraform: 1,
+	helm: 1,
+	dotnet: 1,
+};
+
+/** Command wrappers to skip when extracting the base executable. */
+const CMD_PASSTHROUGH = new Set(["sudo", "env", "command"]);
+
+/**
+ * Build a smart permission pattern for Bash "Always Allow".
+ *
+ * Simple commands → `Bash(ping:*)` (any args are fine)
+ * Subcommand-sensitive CLIs → `Bash(git push:*)` (verb is captured, args wildcarded)
+ */
+export function buildBashPermissionPattern(command: string): string {
+	// When the command is a chain like "cd /foo && gh pr list", extract the
+	// last segment — `cd` is just setup, the meaningful operation is what follows.
+	const segments = command.split(/\s*(?:&&|\|\||;)\s*/);
+	// Skip leading `cd` (directory setup) and trailing error suppressors
+	// like `|| true`, `|| :`, `|| echo ...`.  The meaningful command is
+	// the first segment that is *neither* of those.
+	const SETUP_RE = /^\s*cd\s/;
+	const SUPPRESSOR_RE = /^\s*(?:true|:|echo\b)/;
+	let meaningful: string | undefined;
+	if (segments.length > 1) {
+		// Strip suppressors, then strip cd prefixes; take the *last* remaining
+		// segment — that's the meaningful command.
+		const trimmed = segments.filter(s => !SUPPRESSOR_RE.test(s));
+		const core = trimmed.filter(s => !SETUP_RE.test(s));
+		meaningful = core.length > 0 ? core[core.length - 1] : trimmed[trimmed.length - 1];
+	}
+	meaningful = meaningful || segments[0] || command;
+	const rawTokens = meaningful.trim().split(/\s+/);
+
+	// Skip sudo/env wrappers and leading VAR=val assignments
+	let idx = 0;
+	while (idx < rawTokens.length) {
+		if (CMD_PASSTHROUGH.has(rawTokens[idx])) { idx++; continue; }
+		if (/^[A-Za-z_]\w*=/.test(rawTokens[idx])) { idx++; continue; }
+		break;
+	}
+	const tokens = rawTokens.slice(idx).filter(Boolean);
+	if (tokens.length === 0) return "Bash(*)";
+
+	// Strip path and .exe from executable name
+	const base = tokens[0].replace(/^.*[\\/]/, "").replace(/\.exe$/i, "");
+	const depth = SUBCOMMAND_DEPTH[base];
+
+	if (depth !== undefined) {
+		// Capture base + N subcommand tokens: "gh pr list" → Bash(gh pr list:*)
+		const significant = [base, ...tokens.slice(1, 1 + depth)].join(" ");
+		return `Bash(${significant}:*)`;
+	}
+
+	// Simple command — any args are fine: "ping" → Bash(ping:*)
+	return `Bash(${base}:*)`;
+}
+
+/**
+ * Build the list of granularity options presented after a user chooses
+ * "Always Allow" for a Bash command.
+ *
+ * Rather than assuming the user wants the default smart pattern, the UI
+ * shows every meaningful prefix so the user explicitly picks the scope:
+ *
+ *   "gh pr list --limit 5" → [
+ *     "Bash(gh:*)",         // allow any gh command
+ *     "Bash(gh pr:*)",      // allow any gh pr subcommand
+ *     "Bash(gh pr list:*)", // allow just this verb
+ *   ]
+ *
+ * Flags (tokens starting with `-`) terminate the subcommand chain — they
+ * are call-site arguments, not stable verbs. Subcommand depth is capped
+ * at 3 to keep the menu short (max 4 options).
+ *
+ * Returns a single-entry list when there is no meaningful subcommand to
+ * choose from (e.g. `ls -la`). Callers can skip the second dialog in
+ * that case.
+ */
+export function buildBashPermissionPatternOptions(command: string): string[] {
+	const segments = command.split(/\s*(?:&&|\|\||;)\s*/);
+	const SETUP_RE = /^\s*cd\s/;
+	const SUPPRESSOR_RE = /^\s*(?:true|:|echo\b)/;
+	let meaningful: string | undefined;
+	if (segments.length > 1) {
+		const trimmed = segments.filter(s => !SUPPRESSOR_RE.test(s));
+		const core = trimmed.filter(s => !SETUP_RE.test(s));
+		meaningful = core.length > 0 ? core[core.length - 1] : trimmed[trimmed.length - 1];
+	}
+	meaningful = meaningful || segments[0] || command;
+	const rawTokens = meaningful.trim().split(/\s+/);
+
+	let idx = 0;
+	while (idx < rawTokens.length) {
+		if (CMD_PASSTHROUGH.has(rawTokens[idx])) { idx++; continue; }
+		if (/^[A-Za-z_]\w*=/.test(rawTokens[idx])) { idx++; continue; }
+		break;
+	}
+	const tokens = rawTokens.slice(idx).filter(Boolean);
+	if (tokens.length === 0) return ["Bash(*)"];
+
+	const base = tokens[0].replace(/^.*[\\/]/, "").replace(/\.exe$/i, "");
+
+	// Collect up to 3 subcommand tokens, stopping at the first flag.
+	const subTokens: string[] = [];
+	for (let i = 1; i < tokens.length; i++) {
+		const t = tokens[i];
+		if (t.startsWith("-")) break;
+		subTokens.push(t);
+		if (subTokens.length >= 3) break;
+	}
+
+	const patterns: string[] = [`Bash(${base}:*)`];
+	for (let i = 1; i <= subTokens.length; i++) {
+		patterns.push(`Bash(${[base, ...subTokens.slice(0, i)].join(" ")}:*)`);
+	}
+	return patterns;
+}
+
+/**
+ * Read Bash allow-rule patterns from project and user settings files.
+ *
+ * Returns the ruleContent portion (e.g. `"gh pr list:*"`) for each
+ * `Bash(...)` entry found in `permissions.allow`.
+ */
+function readBashAllowRulesFromSettings(): string[] {
+	const rules: string[] = [];
+	const paths = [
+		join(process.cwd(), ".claude", "settings.local.json"),
+		join(process.cwd(), ".claude", "settings.json"),
+	];
+	try {
+		paths.push(join(homedir(), ".claude", "settings.json"));
+	} catch {
+		// homedir() can throw on some platforms
+	}
+	for (const settingsPath of paths) {
+		try {
+			if (!existsSync(settingsPath)) continue;
+			const raw = JSON.parse(readFileSync(settingsPath, "utf8"));
+			const allow = raw?.permissions?.allow;
+			if (!Array.isArray(allow)) continue;
+			for (const entry of allow) {
+				if (typeof entry !== "string") continue;
+				const m = /^Bash\((.+)\)$/.exec(entry);
+				if (m) rules.push(m[1]);
+			}
+		} catch {
+			// Ignore malformed settings files
+		}
+	}
+	return rules;
+}
+
+/**
+ * Check if a Bash compound command matches saved allow rules after
+ * extracting the meaningful segment.
+ *
+ * The SDK's built-in matcher refuses to match prefix rules against
+ * compound commands (e.g. `cd /path && gh pr list`). Claude Code
+ * routinely prepends `cd <cwd> &&` to commands, causing saved rules
+ * to never match on re-invocation. This function strips safe leading
+ * segments (only `cd` commands) and checks the remaining operation
+ * against saved rules.
+ *
+ * For compound commands, returns true only when all leading segments
+ * are `cd` commands and the final segment matches a saved rule.
+ * For simple (single-segment) commands, checks directly against saved
+ * rules — this covers the case where a rule was added mid-session and
+ * the SDK's in-memory cache is stale.
+ */
+export function bashCommandMatchesSavedRules(command: string): boolean {
+	const segments = command.split(/\s*(?:&&|\|\||;)\s*/).filter(Boolean);
+	if (segments.length === 0) return false;
+
+	let meaningful: string;
+	if (segments.length === 1) {
+		meaningful = segments[0].trim();
+	} else {
+		// Strip trailing error suppressors (|| true, || :, || echo ...)
+		// and leading cd segments.  The first remaining segment is the
+		// meaningful command.  All other non-cd, non-suppressor segments
+		// must be absent — otherwise we can't safely auto-approve.
+		const SETUP_RE = /^cd\s/;
+		const SUPPRESSOR_RE = /^\s*(?:true|:|echo\b)/;
+		const trimmed = segments.filter(s => !SUPPRESSOR_RE.test(s.trim()));
+		const core = trimmed.filter(s => !SETUP_RE.test(s.trim()));
+		if (core.length !== 1) return false; // ambiguous — multiple real commands
+		meaningful = core[0].trim();
+	}
+	if (!meaningful) return false;
+
+	const rules = readBashAllowRulesFromSettings();
+	if (rules.length === 0) return false;
+
+	for (const rule of rules) {
+		const prefixMatch = /^(.+):\*$/.exec(rule);
+		if (prefixMatch) {
+			const prefix = prefixMatch[1];
+			if (meaningful === prefix || meaningful.startsWith(prefix + " ")) {
+				return true;
+			}
+			continue;
+		}
+		// Exact match
+		if (meaningful === rule) return true;
+	}
+
+	return false;
+}
+
+/** Format the tool input into a human-readable summary for the permission prompt. */
+function formatToolInput(toolName: string, input: Record<string, unknown>): string {
+	// Bash — show the command
+	if (input.command && typeof input.command === "string") {
+		const cmd = input.command.length > 300 ? input.command.slice(0, 300) + "…" : input.command;
+		return cmd;
+	}
+	// File-oriented tools — show path
+	if (input.file_path && typeof input.file_path === "string") {
+		return `${toolName}: ${input.file_path}`;
+	}
+	// Generic fallback — compact JSON, truncated
+	const json = JSON.stringify(input);
+	if (json.length <= 200) return json;
+	return json.slice(0, 200) + "…";
+}
+
+/**
+ * Create a canUseTool handler that routes SDK permission requests through the
+ * extension UI's select dialog, or auto-approves when no UI is available.
+ *
+ * Presents three options:
+ * - **Allow** — approve this one invocation
+ * - **Always Allow** — approve and pass `suggestions` back as `updatedPermissions`
+ *   so the SDK remembers the choice for the rest of the session
+ * - **Deny** — reject the invocation
+ *
+ * Follows the same pattern as {@link createClaudeCodeElicitationHandler}:
+ * takes an optional UI context and returns the callback or undefined.
+ *
+ * When UI is unavailable (headless / auto-mode sub-agents), returns a handler
+ * that always approves — replacing the old GSD_AUTO_MODE → bypassPermissions
+ * workaround.
+ */
+export function createClaudeCodeCanUseToolHandler(
+	ui: ExtensionUIContext | undefined,
+): ((toolName: string, input: Record<string, unknown>, options: CanUseToolOptions) => Promise<CanUseToolPermissionResult>) | undefined {
+	if (!ui) return undefined;
+
+	return async (toolName, _input, options) => {
+		// Abort early if the signal is already fired
+		if (options.signal.aborted) {
+			return { behavior: "deny", message: "Aborted", toolUseID: options.toolUseID };
+		}
+
+		// For Bash compound commands (e.g. "cd /path && gh pr list"),
+		// check if the meaningful operation matches a saved allow rule.
+		// The SDK's built-in matcher rejects prefix rules for compound
+		// commands, but cd-prefixed commands are routine and the actual
+		// operation is already approved.
+		if (toolName === "Bash" && typeof _input.command === "string") {
+			if (bashCommandMatchesSavedRules(_input.command)) {
+				return { behavior: "allow", updatedInput: _input, toolUseID: options.toolUseID };
+			}
+		}
+
+		const inputSummary = formatToolInput(toolName, _input);
+		const title = options.title || `Allow Claude Code to use: ${toolName}?`;
+		const body = [
+			options.description,
+			inputSummary,
+		].filter(Boolean).join("\n");
+
+		// The 2nd menu (level picker) lets the user choose the exact pattern,
+		// so the 1st menu just shows "Always Allow" without a command suffix.
+		const alwaysAllowLabel = "Always Allow";
+
+		try {
+			const choice = await ui.select(
+				`${title}\n${body}`,
+				["Allow", alwaysAllowLabel, "Deny"],
+				{ signal: options.signal },
+			);
+
+			if (options.signal.aborted) {
+				return { behavior: "deny", message: "Aborted", toolUseID: options.toolUseID };
+			}
+
+			if (choice === alwaysAllowLabel) {
+				// Pass the SDK's own suggestions back as updatedPermissions so
+				// it knows how to persist them (PermissionUpdate[] shape).
+				// For Bash, patch the ruleContent with the user-chosen
+				// granularity pattern (e.g. "gh", "gh pr", "gh pr list") so
+				// the saved rule matches the scope the user actually wants.
+				let perms = options.suggestions;
+				let notifyLabel: string | undefined;
+				if (toolName === "Bash" && typeof _input.command === "string") {
+					// Present every meaningful prefix so the user picks the
+					// scope explicitly rather than getting a blanket match.
+					const patternOptions = buildBashPermissionPatternOptions(_input.command);
+					let chosenPattern: string;
+					if (patternOptions.length <= 1) {
+						// No subcommand choice to make (e.g. "ls -la") — use
+						// the single available pattern directly.
+						chosenPattern = patternOptions[0] ?? buildBashPermissionPattern(_input.command);
+					} else {
+						const levelChoiceRaw = await ui.select(
+							"Save permission at which level?",
+							patternOptions,
+							{ signal: options.signal },
+						);
+						if (options.signal.aborted) {
+							return { behavior: "deny", message: "Aborted", toolUseID: options.toolUseID };
+						}
+						const levelChoice = Array.isArray(levelChoiceRaw) ? levelChoiceRaw[0] : levelChoiceRaw;
+						if (!levelChoice || !patternOptions.includes(levelChoice)) {
+							// User dismissed the level picker — cancel the
+							// tool use. Falling back to a one-time allow
+							// here would leave the spawned agent running
+							// with no clear signal that the user bailed.
+							return {
+								behavior: "deny",
+								message: "User cancelled permission selection",
+								toolUseID: options.toolUseID,
+							};
+						}
+						chosenPattern = levelChoice;
+					}
+					notifyLabel = chosenPattern;
+					// Extract the ruleContent portion from "Bash(gh pr list:*)" → "gh pr list:*"
+					const ruleContent = chosenPattern.replace(/^Bash\(/, "").replace(/\)$/, "");
+					if (perms && Array.isArray(perms) && perms.length > 0) {
+						// Clone suggestions and patch ruleContent on any Bash addRules entry
+						perms = perms.map((s: any) => {
+							if (s.type === "addRules" && Array.isArray(s.rules)) {
+								return {
+									...s,
+									rules: s.rules.map((r: any) =>
+										r.toolName === "Bash" ? { ...r, ruleContent } : r,
+									),
+								};
+							}
+							return s;
+						});
+					} else {
+						// No suggestions from SDK — build a proper PermissionUpdate
+						perms = [{
+							type: "addRules",
+							rules: [{ toolName: "Bash", ruleContent }],
+							behavior: "allow",
+							destination: "localSettings",
+						}];
+					}
+				}
+				// Notify with the resolved pattern (label already previewed it)
+				if (notifyLabel) {
+					ui.notify(`Saved: ${notifyLabel}`, "info");
+				}
+				return {
+					behavior: "allow",
+					updatedInput: _input,
+					toolUseID: options.toolUseID,
+					...(perms ? { updatedPermissions: perms } : {}),
+				};
+			}
+
+			if (choice === "Allow") {
+				return {
+					behavior: "allow",
+					updatedInput: _input,
+					toolUseID: options.toolUseID,
+				};
+			}
+
+			return { behavior: "deny", message: "User denied", toolUseID: options.toolUseID };
+		} catch {
+			return { behavior: "deny", message: "Aborted", toolUseID: options.toolUseID };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Elicitation handler
+// ---------------------------------------------------------------------------
+
 /** Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available. */
 export function createClaudeCodeElicitationHandler(
 	ui: ExtensionUIContext | undefined,
@@ -692,18 +1184,22 @@ export function makeAbortedMessage(model: string, lastTextContent: string): Assi
 /**
  * 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`).
+ * Defaults to `acceptEdits`, which auto-approves file reads/edits but
+ * surfaces a permission dialog for dangerous operations (e.g. general Bash,
+ * Agent, WebFetch). This prevents tools outside the allowlist from being
+ * silently denied — the SDK emits an `extension_ui_request` event so the
+ * user sees a prompt instead of a silent refusal that Claude Code mistakes
+ * for user rejection (#4383).
+ *
+ * Set `GSD_CLAUDE_CODE_PERMISSION_MODE` to `bypassPermissions` to restore
+ * the old always-approve behaviour, or to `default` / `plan` for stricter
+ * modes.
  *
- * 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.
+ * When `GSD_HEADLESS=1` is set (auto-mode / non-interactive runs), the
+ * default flips to `bypassPermissions` because there is no UI to approve
+ * permission dialogs — `acceptEdits` would hang verification commands like
+ * `npx tsc --noEmit` or `npx vitest run` indefinitely (#4657). Explicit
+ * overrides still win, so users can opt back into `acceptEdits` in headless.
  */
 export async function resolveClaudePermissionMode(
 	env: NodeJS.ProcessEnv = process.env,
@@ -712,6 +1208,12 @@ export async function resolveClaudePermissionMode(
 	if (override === "bypassPermissions" || override === "acceptEdits" || override === "default" || override === "plan") {
 		return override;
 	}
+	if (env.GSD_HEADLESS === "1") {
+		console.warn(
+			"[claude-code-cli] Headless mode detected (GSD_HEADLESS=1): defaulting permissionMode to 'bypassPermissions' so verification Bash commands can run. Set GSD_CLAUDE_CODE_PERMISSION_MODE=acceptEdits to opt out.",
+		);
+		return "bypassPermissions";
+	}
 	return "bypassPermissions";
 }
 
@@ -773,20 +1275,24 @@ export function buildSdkOptions(
 	const { reasoning, ...sdkExtraOptions } = extraOptions;
 	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).
+	// Globally unblock all tools. Users reported that the `acceptEdits` default
+	// plus a narrow allowlist silently declined most Bash/Agent/WebFetch calls
+	// when `extensionUIContext` wasn't threaded through. Default to
+	// bypassPermissions and an empty disallow list so every tool — including
+	// `AskUserQuestion` and every `mcp__*` workflow tool — is auto-approved.
+	// Opt back into gated mode with GSD_CLAUDE_CODE_PERMISSION_MODE=acceptEdits.
+	const disallowedTools: string[] = [];
 	const allowedTools = [
 		"Read",
 		"Write",
 		"Edit",
 		"Glob",
 		"Grep",
-		"Bash(ls:*)",
-		"Bash(pwd)",
+		"Bash",
+		"Agent",
+		"WebFetch",
+		"WebSearch",
+		"AskUserQuestion",
 		...(mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : []),
 	];
 	const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
@@ -867,6 +1373,69 @@ function normalizeToolResultContent(content: unknown): ExternalToolResultContent
 	return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
 }
 
+/**
+ * Extract a `details` payload from an MCP tool-result block.
+ *
+ * MCP's `CallToolResult` carries structured data in `structuredContent` — the
+ * protocol's supported channel for non-text payloads. Claude Code's synthetic
+ * user message may surface that field in one of two shapes depending on SDK
+ * version: as a sibling on the `mcp_tool_result` block itself, or as a
+ * dedicated content sub-block with `type: "structuredContent"`. Snake-case
+ * (`structured_content`) is accepted defensively in case a transport hop
+ * rewrites casing. All other shapes fall back to an empty object so callers
+ * can rely on `details` being present.
+ */
+function extractStructuredDetailsFromBlock(block: Record<string, unknown>): Record<string, unknown> | undefined {
+	const sibling = block.structuredContent ?? (block as Record<string, unknown>).structured_content;
+	if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
+		return sibling as Record<string, unknown>;
+	}
+
+	if (Array.isArray(block.content)) {
+		for (const item of block.content) {
+			if (!item || typeof item !== "object") continue;
+			const sub = item as Record<string, unknown>;
+			if (sub.type !== "structuredContent" && sub.type !== "structured_content") continue;
+			const payload = sub.structuredContent ?? sub.structured_content ?? sub.data ?? sub.value;
+			if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+				return payload as Record<string, unknown>;
+			}
+		}
+	}
+
+	// Return undefined (not {}) when no structured payload is present, matching
+	// the pre-#4477 contract where `details` was nullable. An empty-object
+	// sentinel is truthy and breaks downstream consumers that gate on
+	// `if (details)`. `undefined` matches the type of the field these results
+	// flow into (`Record<string, unknown> | undefined`).
+	return undefined;
+}
+
+/**
+ * True for items that are MCP `structuredContent` pseudo-blocks living inside
+ * a tool-result `content[]` array. These blocks carry the structured payload
+ * (extracted separately by `extractStructuredDetailsFromBlock`) and must NOT
+ * leak into the visible content rendered to the user — 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).
+ */
+function isStructuredContentPseudoBlock(item: unknown): boolean {
+	if (!item || typeof item !== "object") return false;
+	const type = (item as Record<string, unknown>).type;
+	return type === "structuredContent" || type === "structured_content";
+}
+
+/**
+ * Strip `structuredContent` pseudo-blocks from a tool-result content array
+ * before normalization. The structured payload is extracted via the sibling
+ * `structuredContent` field (or a dedicated extractor pass on the raw block);
+ * the visible content path must not include the pseudo-block itself.
+ */
+function stripStructuredContentPseudoBlocks(content: unknown): unknown {
+	if (!Array.isArray(content)) return content;
+	return content.filter((item) => !isStructuredContentPseudoBlock(item));
+}
+
 /** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
 export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): Array<{
 	toolUseId: string;
@@ -890,8 +1459,8 @@ export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): A
 		extracted.push({
 			toolUseId,
 			result: {
-				content: normalizeToolResultContent(block.content),
-				details: {},
+				content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(block.content)),
+				details: extractStructuredDetailsFromBlock(block),
 				isError: block.is_error === true,
 			},
 		});
@@ -906,8 +1475,8 @@ export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): A
 				extracted.push({
 					toolUseId,
 					result: {
-						content: normalizeToolResultContent(toolResult.content),
-						details: {},
+						content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(toolResult.content)),
+						details: extractStructuredDetailsFromBlock(toolResult),
 						isError: toolResult.is_error === true,
 					},
 				});
@@ -931,6 +1500,49 @@ function attachExternalResultsToToolBlocks(
 	}
 }
 
+/**
+ * Build the final assistant content that Agent Core consumes in
+ * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
+ * SDK-produced external results by tool-call id, and then appends the final
+ * text/thinking blocks for the completed turn.
+ */
+export function buildFinalAssistantContent(params: {
+	intermediateToolBlocks: AssistantMessage["content"];
+	pendingContent?: AssistantMessage["content"];
+	toolResultsById: ReadonlyMap<string, ExternalToolResultPayload>;
+	lastThinkingContent?: string;
+	lastTextContent?: string;
+	fallbackResultText?: string;
+}): AssistantMessage["content"] {
+	const mergedToolBlocks = [...params.intermediateToolBlocks];
+	if (params.pendingContent) {
+		mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
+	}
+	attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
+
+	const finalContent: AssistantMessage["content"] = [...mergedToolBlocks];
+	if (params.pendingContent && params.pendingContent.length > 0) {
+		for (const block of params.pendingContent) {
+			if (block.type === "text" || block.type === "thinking") {
+				finalContent.push(block);
+			}
+		}
+	} else {
+		if (params.lastThinkingContent) {
+			finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
+		}
+		if (params.lastTextContent) {
+			finalContent.push({ type: "text", text: params.lastTextContent });
+		}
+	}
+
+	if (finalContent.length === 0 && params.fallbackResultText) {
+		finalContent.push({ type: "text", text: params.fallbackResultText });
+	}
+
+	return finalContent;
+}
+
 /**
  * Merge tool-call blocks from the active partial-message builder into the
  * running list of intermediate tool calls, preserving order and de-duping
@@ -962,8 +1574,9 @@ export function mergePendingToolCalls(
  * GSD streamSimple function that delegates to the Claude Agent SDK.
  *
  * Emits AssistantMessageEvent deltas for real-time TUI rendering
- * (thinking, text, tool calls). The final AssistantMessage has tool-call
- * blocks stripped so the agent loop ends the turn without local dispatch.
+ * (thinking, text, tool calls). The final AssistantMessage preserves
+ * SDK-executed tool-call blocks for Agent Core's `externalToolExecution`
+ * path, which renders the results without dispatching the tools locally.
  */
 export function streamViaClaudeCode(
 	model: Model<any>,
@@ -1013,18 +1626,26 @@ async function pumpSdkMessages(
 		const prompt = buildPromptFromContext(context);
 		const queryPrompt = buildSdkQueryPrompt(context, prompt);
 		const permissionMode = await resolveClaudePermissionMode();
+		const uiContext = (options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext;
+		const canUseToolHandler = createClaudeCodeCanUseToolHandler(uiContext);
+		// When no UI is available (headless / auto-mode), auto-approve all
+		// tool requests. This replaces the old bypassPermissions workaround.
+		const canUseToolFallback = canUseToolHandler
+			?? (async (_toolName: string, _input: Record<string, unknown>, opts: CanUseToolOptions): Promise<CanUseToolPermissionResult> =>
+				({ behavior: "allow", toolUseID: opts.toolUseID }));
 		const sdkOpts = buildSdkOptions(
 			modelId,
 			prompt,
 			{ permissionMode },
-			typeof (options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext === "object"
-				? {
-						reasoning: options?.reasoning,
-						onElicitation: createClaudeCodeElicitationHandler(
-							(options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext,
-						),
-					}
-				: { reasoning: options?.reasoning },
+			{
+				reasoning: options?.reasoning,
+				canUseTool: canUseToolFallback,
+				...(uiContext
+					? {
+							onElicitation: createClaudeCodeElicitationHandler(uiContext),
+						}
+					: {}),
+			},
 		);
 
 		const queryResult = sdk.query({
@@ -1164,46 +1785,15 @@ async function pumpSdkMessages(
 				// -- Result (terminal) --
 				case "result": {
 					const result = msg as SDKResultMessage;
-
-					// Build final message. Include intermediate tool calls so the
-					// agent loop's externalToolExecution path emits tool_execution
-					// 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);
-
-					// Add text/thinking from the last turn
-					if (builder && builder.message.content.length > 0) {
-						for (const block of builder.message.content) {
-							if (block.type === "text" || block.type === "thinking") {
-								finalContent.push(block);
-							}
-						}
-					} else {
-						if (lastThinkingContent) {
-							finalContent.push({ type: "thinking", thinking: lastThinkingContent });
-						}
-						if (lastTextContent) {
-							finalContent.push({ type: "text", text: lastTextContent });
-						}
-					}
-
-					// Fallback: use the SDK's result text if we have no content
-					if (finalContent.length === 0 && result.subtype === "success" && result.result) {
-						finalContent.push({ type: "text", text: result.result });
-					}
+					const finalContent = buildFinalAssistantContent({
+						intermediateToolBlocks,
+						pendingContent: builder?.message.content,
+						toolResultsById,
+						lastThinkingContent,
+						lastTextContent,
+						fallbackResultText:
+							result.subtype === "success" && result.result ? result.result : undefined,
+					});
 
 					const finalMessage: AssistantMessage = {
 						role: "assistant",