@gajae-code/coding-agent 0.11.11 → 0.12.0

package/src/session/streaming-output.ts

@@ -114,8 +114,12 @@ export interface TruncationResult {
 	elidedLines?: number;
 	lastLinePartial?: boolean;
 	firstLineExceedsLimit?: boolean;
+	lastLineExceedsLimit?: boolean;
 }
 
+/** Direction vocabulary used by callers that select which end of content to retain. */
+export type TruncationDirection = "head" | "last" | "both";
+
 export interface TruncationOptions {
 	/** Maximum number of lines (default: 3000) */
 	maxLines?: number;
@@ -131,6 +135,8 @@ export interface TruncationOptions {
 	 * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
 	 */
 	maxHeadLines?: number;
+	/** Direction to dispatch through truncateContent (head, last, or both). */
+	direction?: TruncationDirection;
 }
 
 /** Result from byte-level truncation helpers. */
@@ -452,6 +458,7 @@ export function truncateTail(content: string, options: TruncationOptions = {}):
 					outputBytes: tail.bytes,
 					lastLinePartial: true,
 					firstLineExceedsLimit: false,
+					lastLineExceedsLimit: true,
 				};
 			}
 			break;
@@ -474,6 +481,7 @@ export function truncateTail(content: string, options: TruncationOptions = {}):
 					outputBytes: tail.bytes,
 					lastLinePartial: true,
 					firstLineExceedsLimit: false,
+					lastLineExceedsLimit: true,
 				};
 			}
 			break;
@@ -516,14 +524,129 @@ export function formatMiddleElisionMarker(elidedLines: number, elidedBytes: numb
 }
 
 /**
- * Truncate content keeping a head window and a tail window, eliding the middle.
+ * A retained source segment returned by {@link truncateMiddleWindows}.
+ * Line coordinates are 1-indexed and inclusive.
+ */
+export type ReadSegment =
+	| {
+			kind: "lines";
+			content: string;
+			lines: number;
+			bytes: number;
+			origin: { startLine: number; endLine: number };
+			lastLinePartial: false;
+	  }
+	| {
+			kind: "partial-line";
+			content: string;
+			lines: 1;
+			bytes: number;
+			origin: { startLine: number; endLine: number };
+			sourceLineBytes: number;
+			lastLinePartial: true;
+	  };
+
+/** The actual windows retained by middle truncation. */
+export interface ReadWindow {
+	kind: "full" | "head-only" | "tail-only" | "middle";
+	head?: ReadSegment;
+	tail?: ReadSegment;
+	// With normalized head/tail line budgets, an overlap cannot occur: a
+	// source that can fit both windows returns `full`, otherwise their kept
+	// line counts sum to less than the source. Retain this defensive value for
+	// custom/future budgets and wire compatibility.
+	overlap: "disjoint" | "adjacent" | "overlapping";
+	elidedLines: number;
+	elidedBytes: number;
+	totalLines: number;
+	totalBytes: number;
+	/** @deprecated Non-enumerable compatibility reason for older consumers. */
+	truncatedBy?: "lines" | "bytes" | "middle";
+}
+
+function outputLineCount(result: TruncationResult): number {
+	return result.outputLines ?? (result.content.length === 0 ? 0 : countNewlines(result.content) + 1);
+}
+
+function outputByteCount(result: TruncationResult): number {
+	return result.outputBytes ?? Buffer.byteLength(result.content, "utf-8");
+}
+
+function lastSourceLineBytes(content: string): number {
+	const lineStart = content.lastIndexOf(NL) + 1;
+	return Buffer.byteLength(content.slice(lineStart), "utf-8");
+}
+
+function makeReadSegment(
+	result: TruncationResult,
+	startLine: number,
+	totalLines: number,
+	sourceContent: string = result.content,
+): ReadSegment | undefined {
+	const lines = outputLineCount(result);
+	if (lines <= 0) return undefined;
+	const bytes = outputByteCount(result);
+	const endLine = Math.min(totalLines, startLine + lines - 1);
+	if (result.lastLinePartial) {
+		const partialLine = endLine;
+		return {
+			kind: "partial-line",
+			content: result.content,
+			lines: 1,
+			bytes,
+			origin: { startLine: partialLine, endLine: partialLine },
+			sourceLineBytes: lastSourceLineBytes(sourceContent),
+			lastLinePartial: true,
+		};
+	}
+	return {
+		kind: "lines",
+		content: result.content,
+		lines,
+		bytes,
+		origin: { startLine, endLine },
+		lastLinePartial: false,
+	};
+}
+
+function withMiddleWindowReason(windows: ReadWindow, truncatedBy: "lines" | "bytes" | "middle"): ReadWindow {
+	Object.defineProperty(windows, "truncatedBy", { value: truncatedBy, enumerable: false });
+	return windows;
+}
+
+function fullReadWindow(
+	content: string,
+	totalLines: number,
+	totalBytes: number,
+	overlap: ReadWindow["overlap"] = "disjoint",
+): ReadWindow {
+	return {
+		kind: "full",
+		head: {
+			kind: "lines",
+			content,
+			lines: totalLines,
+			bytes: totalBytes,
+			origin: { startLine: 1, endLine: totalLines },
+			lastLinePartial: false,
+		},
+		overlap,
+		elidedLines: 0,
+		elidedBytes: 0,
+		totalLines,
+		totalBytes,
+	};
+}
+
+/**
+ * Truncate content while exposing the exact retained head/tail windows.
  *
- * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
- * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
- * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
- * budget is empty or the content already fits.
+ * The budget split and fallback ordering intentionally mirror truncateMiddle.
+ * The overlap classification is performed before resolving an overlap to a
+ * full window, so callers can distinguish disjoint, adjacent and overlapping
+ * candidate windows even when no marker is needed.
  */
-export function truncateMiddle(content: string, options: TruncationOptions = {}): TruncationResult {
+export function truncateMiddleWindows(content: string, options: TruncationOptions = {}): ReadWindow {
 	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
 	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
 	const headBytes = options.maxHeadBytes ?? Math.floor(maxBytes / 2);
@@ -533,57 +656,153 @@ export function truncateMiddle(content: string, options: TruncationOptions = {})
 
 	const totalBytes = Buffer.byteLength(content, "utf-8");
 	const totalLines = countNewlines(content) + 1;
+	if (totalBytes <= maxBytes && totalLines <= maxLines) return fullReadWindow(content, totalLines, totalBytes);
+
+	const oneSided = (kind: "head-only" | "tail-only", result: TruncationResult, startLine: number): ReadWindow => {
+		const lines = outputLineCount(result);
+		const bytes = outputByteCount(result);
+		const segment = makeReadSegment(result, startLine, totalLines, content);
+
+		const windows: ReadWindow = {
+			kind,
+			...(kind === "head-only" ? (segment ? { head: segment } : {}) : segment ? { tail: segment } : {}),
+			overlap: "disjoint",
+			elidedLines: Math.max(0, totalLines - lines),
+			elidedBytes: Math.max(0, totalBytes - bytes),
+			totalLines,
+			totalBytes,
+		};
+		return withMiddleWindowReason(windows, result.truncatedBy === "lines" ? "lines" : "bytes");
+	};
 
-	if (totalBytes <= maxBytes && totalLines <= maxLines) {
-		return noTruncResult(content, totalLines, totalBytes);
-	}
-
-	// Degenerate budgets → fall back to one-sided truncation.
+	// Keep this order identical to truncateMiddle: degenerate budgets are
+	// resolved before either one-sided truncator is called.
 	if (headBytes <= 0 || headLines <= 0) {
-		return truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		const tail = truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		return oneSided("tail-only", tail, totalLines - outputLineCount(tail) + 1);
 	}
 	if (tailBytes <= 0 || tailLines <= 0) {
-		return truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		const head = truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		return oneSided("head-only", head, 1);
 	}
 
 	const head = truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
 	const tail = truncateTail(content, { maxBytes: tailBytes, maxLines: tailLines });
-
-	const headLinesKept = head.outputLines ?? 0;
-	const tailLinesKept = tail.outputLines ?? 0;
-	const headBytesKept = head.outputBytes ?? Buffer.byteLength(head.content, "utf-8");
-	const tailBytesKept = tail.outputBytes ?? Buffer.byteLength(tail.content, "utf-8");
+	const headLinesKept = outputLineCount(head);
+	const tailLinesKept = outputLineCount(tail);
+	const headBytesKept = outputByteCount(head);
+	const tailBytesKept = outputByteCount(tail);
 
 	// Head unusable (first line exceeds budget) → tail-only.
-	if (headLinesKept === 0 || head.firstLineExceedsLimit) return tail;
+	if (headLinesKept === 0 || head.firstLineExceedsLimit) {
+		return oneSided("tail-only", tail, totalLines - tailLinesKept + 1);
+	}
 	// Tail unusable → head-only.
-	if (tailLinesKept === 0) return head;
-	// Windows overlap → no meaningful elision; return content untruncated.
-	if (headLinesKept + tailLinesKept >= totalLines) {
-		return noTruncResult(content, totalLines, totalBytes);
+	if (tailLinesKept === 0) return oneSided("head-only", head, 1);
+
+	const headEnd = headLinesKept;
+	const tailStart = totalLines - tailLinesKept + 1;
+	const overlap: ReadWindow["overlap"] =
+		headEnd + 1 < tailStart ? "disjoint" : headEnd + 1 === tailStart ? "adjacent" : "overlapping";
+	const tailPartial = tail.lastLinePartial === true;
+
+	// Adjacent/overlapping complete windows cover the whole source. Return one
+	// full segment so renderers never insert a marker for an overlap.
+	if (headLinesKept + tailLinesKept >= totalLines && !tailPartial) {
+		return fullReadWindow(content, totalLines, totalBytes, overlap);
 	}
 
-	const elidedLines = totalLines - headLinesKept - tailLinesKept;
-	// `totalBytes - headBytesKept - tailBytesKept` includes newline separators
-	// between the kept windows and the elided region; close enough for a notice.
-	const elidedBytes = Math.max(0, totalBytes - headBytesKept - tailBytesKept);
-	const marker = formatMiddleElisionMarker(elidedLines, elidedBytes);
-	const composed = `${head.content}\n${marker}\n${tail.content}`;
-	const markerBytes = Buffer.byteLength(marker, "utf-8");
+	const headWindow = makeReadSegment(head, 1, totalLines, content);
+	const tailWindow = makeReadSegment(tail, tailStart, totalLines, content);
+	if (!headWindow || !tailWindow) return fullReadWindow(content, totalLines, totalBytes, overlap);
+
+	const partialSourceBytes = tailWindow.kind === "partial-line" ? tailWindow.sourceLineBytes : tailWindow.bytes;
+	const elidedLines = tailPartial
+		? Math.max(0, tailStart - headEnd - 1)
+		: Math.max(0, totalLines - headLinesKept - tailLinesKept);
+	const elidedBytes = tailPartial
+		? Math.max(0, totalBytes - headBytesKept - partialSourceBytes)
+		: Math.max(0, totalBytes - headBytesKept - tailBytesKept);
+	return withMiddleWindowReason(
+		{
+			kind: "middle",
+			head: headWindow,
+			tail: tailWindow,
+			overlap,
+			elidedLines,
+			elidedBytes,
+			totalLines,
+			totalBytes,
+		},
+		"middle",
+	);
+}
 
-	return {
-		content: composed,
-		truncated: true,
-		truncatedBy: "middle",
-		totalLines,
-		totalBytes,
-		outputLines: headLinesKept + tailLinesKept + 1,
-		outputBytes: headBytesKept + tailBytesKept + markerBytes + 2,
-		elidedLines,
-		elidedBytes,
-		lastLinePartial: tail.lastLinePartial,
-		firstLineExceedsLimit: false,
-	};
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ * The composed return shape remains field-for-field compatible with the
+ * historical implementation; callers that need coordinates use
+ * truncateMiddleWindows directly.
+ */
+export function truncateMiddle(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const headBytes = options.maxHeadBytes ?? Math.floor(maxBytes / 2);
+	const tailBytes = Math.max(0, maxBytes - headBytes);
+	const headLines = options.maxHeadLines ?? Math.max(1, Math.floor(maxLines / 2));
+	const tailLines = Math.max(0, maxLines - headLines);
+	const windows = truncateMiddleWindows(content, options);
+
+	switch (windows.kind) {
+		case "full":
+			return noTruncResult(content, windows.totalLines, windows.totalBytes);
+		case "tail-only":
+			return truncateTail(content, { maxBytes: tailBytes || maxBytes, maxLines: tailLines || maxLines });
+		case "head-only":
+			return truncateHead(content, { maxBytes: headBytes, maxLines: headLines });
+		case "middle": {
+			const head = windows.head;
+			const tail = windows.tail;
+			if (!head || !tail) return noTruncResult(content, windows.totalLines, windows.totalBytes);
+			if (head.lines + tail.lines >= windows.totalLines)
+				return noTruncResult(content, windows.totalLines, windows.totalBytes);
+			const legacyElidedLines = Math.max(0, windows.totalLines - head.lines - tail.lines);
+			const legacyElidedBytes =
+				tail.kind === "partial-line"
+					? Math.max(0, windows.totalBytes - head.bytes - tail.bytes)
+					: windows.elidedBytes;
+			const marker = formatMiddleElisionMarker(legacyElidedLines, legacyElidedBytes);
+			const markerBytes = Buffer.byteLength(marker, "utf-8");
+			return {
+				content: `${head.content}\n${marker}\n${tail.content}`,
+				truncated: true,
+				truncatedBy: "middle",
+				totalLines: windows.totalLines,
+				totalBytes: windows.totalBytes,
+				outputLines: head.lines + tail.lines + 1,
+				outputBytes: head.bytes + tail.bytes + markerBytes + 2,
+				elidedLines: legacyElidedLines,
+				elidedBytes: legacyElidedBytes,
+				lastLinePartial: tail.lastLinePartial,
+				firstLineExceedsLimit: false,
+				...(tail.lastLinePartial ? { lastLineExceedsLimit: true } : {}),
+			};
+		}
+	}
+}
+
+/**
+ * Dispatch truncation using the caller-facing direction vocabulary.
+ */
+export function truncateContent(content: string, options: TruncationOptions = {}): TruncationResult {
+	switch (options.direction) {
+		case "last":
+			return truncateTail(content, options);
+		case "both":
+			return truncateMiddle(content, options);
+		default:
+			return truncateHead(content, options);
+	}
 }
 
 // =============================================================================

package/src/setup/provider-onboarding.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { getAgentDbPath, getAgentDir } from "@gajae-code/utils";
 import { YAML } from "bun";
 import { type ModelsConfig, ModelsConfigSchema } from "../config/models-config-schema";
+import { compareRankedProviders, famousProviderIndex } from "../config/provider-ranking";
 import { AuthStorage } from "../session/auth-storage";
 import providerPresets from "./provider-presets.json";
 
@@ -81,11 +82,25 @@ export function findProviderPreset(value: string | undefined): ProviderPreset |
 	return PROVIDER_PRESETS.find(preset => preset.id === normalized || preset.aliases.includes(normalized));
 }
 
+function providerPresetRankingId(preset: ProviderPreset): string {
+	return (
+		[preset.providerId, preset.id, ...preset.aliases].find(id => famousProviderIndex(id) !== undefined) ?? preset.id
+	);
+}
+
 export function formatProviderPresetList(): string {
-	return PROVIDER_PRESETS.map(preset => {
-		const aliases = preset.aliases.length > 0 ? ` (aliases: ${preset.aliases.join(", ")})` : "";
-		return `${preset.id}${aliases}: ${preset.description}`;
-	}).join("\n");
+	return [...PROVIDER_PRESETS]
+		.sort((left, right) =>
+			compareRankedProviders(
+				{ id: providerPresetRankingId(left), label: left.name, authState: "none" },
+				{ id: providerPresetRankingId(right), label: right.name, authState: "none" },
+			),
+		)
+		.map(preset => {
+			const aliases = preset.aliases.length > 0 ? ` (aliases: ${preset.aliases.join(", ")})` : "";
+			return `${preset.id}${aliases}: ${preset.description}`;
+		})
+		.join("\n");
 }
 
 export function parseModelList(values: readonly string[]): string[] {

package/src/skill-state/active-state.ts

@@ -71,8 +71,6 @@ export interface SkillActiveEntry {
 	handoff_at?: string;
 	active_subskills?: ActiveSubskillEntry[];
 	source_state_revision?: number;
-	/** Durable ordering token from the source workflow mode-state, not this cache file's revision. */
-	committed_mode_state_revision?: number;
 }
 
 export interface SkillActiveState {
@@ -116,8 +114,6 @@ export interface SyncSkillActiveStateOptions {
 	handoff_at?: string;
 	active_subskills?: ActiveSubskillEntry[];
 	sourceRevision?: number;
-	/** Durable ordering token from the source workflow mode-state, not this cache file's revision. */
-	committedModeRevision?: number;
 }
 
 const HUD_TEXT_LIMIT = 80;
@@ -789,9 +785,6 @@ async function persistActiveEntry(
 		await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
 			cwd,
 			audit: activeStateWriterAudit("write-active-entry", sessionScope),
-			...(typeof entry.committed_mode_state_revision === "number"
-				? { orderingRevision: entry.committed_mode_state_revision }
-				: {}),
 		});
 	}
 }
@@ -870,9 +863,6 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 				? { active_subskills: preservedActiveSubskills }
 				: {}),
 		...(typeof options.sourceRevision === "number" ? { source_state_revision: options.sourceRevision } : {}),
-		...(typeof options.committedModeRevision === "number"
-			? { committed_mode_state_revision: options.committedModeRevision }
-			: {}),
 	};
 	const sessionScope = { sessionId: options.sessionId };
 	await removeSupersededPlanningPipelineEntries(options.cwd, sessionScope, entry);

package/src/skill-state/workflow-hud.ts

@@ -23,6 +23,9 @@ interface RalplanHudState extends WorkflowGateHudState {
 	iteration?: number;
 	iterationFromIndex?: number;
 	stages?: string;
+	architectPasses?: number;
+	criticPasses?: number;
+	reviewPassBudget?: number;
 	verdict?: string;
 	latestSummary?: string;
 	pendingApproval?: boolean;
@@ -194,13 +197,31 @@ export function deriveDeepInterviewHud(
 export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSummary {
 	const verdict = state.verdict?.toUpperCase();
 	const verdictSeverity =
-		verdict === "BLOCK"
+		verdict === "BLOCK" || verdict === "REJECT"
 			? "blocked"
 			: verdict === "ITERATE" || verdict === "WATCH"
 				? "warning"
-				: verdict === "APPROVE" || verdict === "CLEAR"
+				: verdict === "APPROVE" || verdict === "CLEAR" || verdict === "OKAY"
 					? "success"
 					: undefined;
+	const reviewPassChip = (
+		label: "arch" | "crit",
+		passes: number | undefined,
+		priority: number,
+	): WorkflowHudChip | null => {
+		if (
+			state.pendingApproval ||
+			typeof passes !== "number" ||
+			!Number.isFinite(passes) ||
+			passes <= 0 ||
+			typeof state.reviewPassBudget !== "number" ||
+			!Number.isFinite(state.reviewPassBudget) ||
+			state.reviewPassBudget <= 0
+		) {
+			return null;
+		}
+		return chip(label, `${passes}/${state.reviewPassBudget}`, priority);
+	};
 	return {
 		version: 1,
 		summary: state.latestSummary,
@@ -217,6 +238,8 @@ export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSumma
 				30,
 			),
 			chip("stages", state.stages, 35),
+			reviewPassChip("arch", state.architectPasses, 36),
+			reviewPassChip("crit", state.criticPasses, 38),
 			chip("verdict", verdict, 40, verdictSeverity),
 		]),
 		...(state.updatedAt ? { updated_at: state.updatedAt } : {}),

package/src/skill-state/workflow-mutation-guard.ts

@@ -57,6 +57,9 @@ const BASH_OPAQUE_INTERPRETER_WRITE_RE =
 const BASH_HEREDOC_OPAQUE_INTERPRETER_WRITE_RE =
 	/(?:^|[;&|\n])\s*(?:\w+=[^\s]+\s+)*(?:sudo\s+)?(?:python3?|node|ruby)\b[^;&|\n]*(?:<<[-]?\s*['"]?\w+['"]?)[\s\S]*(?:open\s*\(|writeFile(?:Sync)?\s*\(|\.write\s*\()/i;
 const BASH_DD_OUTPUT_RE = /(?:^|[;&|\n])\s*(?:\w+=[^\s]+\s+)*(?:sudo\s+)?(?:[^\s;&|]*\/)?dd\b([^;&|\n]*)/gi;
+/** Literal `sh|bash|zsh -c '<script>'` payloads whose nested script must also be scanned. */
+const BASH_NESTED_SHELL_RE =
+	/(?:^|[;&|\n])\s*(?:\w+=[^\s]+\s+)*(?:sudo\s+)?(?:[^\s;&|]*\/)?(?:ba|z|da)?sh\s+(?:-[A-Za-z]+\s+)*-[A-Za-z]*c\s+(?:(')([^']*)'|(")([^"]*)")/g;
 
 type ToolWithEditMode = AgentTool & {
 	mode?: unknown;
@@ -77,6 +80,12 @@ export interface WorkflowMutationGuardInput {
 interface ExtractedTargets {
 	paths: string[];
 	unknown: boolean;
+	/**
+	 * Set when a bash command was recognized as performing a filesystem write.
+	 * During a planning phase an unrecognized bash command is allowed (reading
+	 * and inspection must not be blocked); only a recognized mutation blocks.
+	 */
+	explicitMutation?: boolean;
 }
 
 export interface WorkflowMutationDecision {
@@ -382,11 +391,34 @@ function cleanShellWord(value: string): string {
 	return value.replace(/^['"]|['"]$/g, "");
 }
 
+/**
+ * Blank out single-quoted spans so shell metacharacters inside a literal
+ * argument value (e.g. `--value 'uses `x`; a > b'`) are not misread as
+ * redirections or separators. Single quotes suppress every expansion in POSIX
+ * shells, so their contents are always inert data. Double-quoted spans are left
+ * intact because they still expand `$(...)` and backticks.
+ */
+function maskSingleQuotedSpans(command: string): string {
+	let masked = "";
+	let inSingle = false;
+	for (const character of command) {
+		if (character === "'") {
+			inSingle = !inSingle;
+			masked += character;
+			continue;
+		}
+		masked += inSingle && character !== "\n" ? " " : character;
+	}
+	// An unbalanced quote means the parse is unreliable; keep the original text
+	// so the scanner stays fail-closed rather than blind.
+	return inSingle ? command : masked;
+}
+
 function isDeviceSinkPath(value: string): boolean {
 	return DEVICE_SINK_PATHS.has(cleanShellWord(value));
 }
 
-function extractBashTargets(args: unknown): ExtractedTargets {
+function extractBashTargets(args: unknown, depth = 0): ExtractedTargets {
 	const record = getRecord(args);
 	const command = safeString(record?.command);
 	const targets: ExtractedTargets = { paths: [], unknown: false };
@@ -394,19 +426,40 @@ function extractBashTargets(args: unknown): ExtractedTargets {
 		targets.unknown = true;
 		return targets;
 	}
+	// A literal `sh|bash|zsh -c '<script>'` payload is a real command list. Its
+	// mutations never match the top-level patterns, so recurse into it; anything
+	// deeper than a bounded depth is not statically analyzable and fails closed.
+	for (const match of command.matchAll(BASH_NESTED_SHELL_RE)) {
+		if (depth >= 2) {
+			targets.explicitMutation = true;
+			targets.unknown = true;
+			break;
+		}
+		const nested = extractBashTargets({ command: match[2] ?? match[4] ?? "" }, depth + 1);
+		for (const nestedPath of nested.paths) addPath(targets, nestedPath);
+		if (nested.unknown) targets.unknown = true;
+		if (nested.explicitMutation) targets.explicitMutation = true;
+	}
+	// Nested scripts were read from the raw text above; every scanner below works
+	// on the masked view so quoted argument data cannot look like a redirection.
+	const scanned = maskSingleQuotedSpans(command);
 	if (BASH_OPAQUE_INTERPRETER_WRITE_RE.test(command) || BASH_HEREDOC_OPAQUE_INTERPRETER_WRITE_RE.test(command)) {
+		targets.explicitMutation = true;
 		targets.unknown = true;
 	}
 	// `exec 1<>file` rebinds a descriptor, so a later `>/dev/null` may not reach the device at all.
-	if (BASH_EXEC_REDIRECT_RE.test(command)) {
+	if (BASH_EXEC_REDIRECT_RE.test(scanned)) {
+		targets.explicitMutation = true;
 		targets.unknown = true;
 	}
-	for (const match of command.matchAll(BASH_EXTENDED_WRITE_RE)) {
+	for (const match of scanned.matchAll(BASH_EXTENDED_WRITE_RE)) {
+		targets.explicitMutation = true;
 		const cleaned = cleanShellWord(match[1] ?? "");
 		if (!cleaned) targets.unknown = true;
 		else if (!isDeviceSinkPath(cleaned)) addPath(targets, cleaned);
 	}
-	for (const match of command.matchAll(BASH_DD_OUTPUT_RE)) {
+	for (const match of scanned.matchAll(BASH_DD_OUTPUT_RE)) {
+		targets.explicitMutation = true;
 		const parts = shellWords(match[1] ?? "").map(cleanShellWord);
 		// Every `of=` counts: GNU dd honors the last one, so `of=/dev/null of=real.ts` writes real.ts.
 		const outputs = parts.filter(part => part.startsWith("of="));
@@ -417,15 +470,17 @@ function extractBashTargets(args: unknown): ExtractedTargets {
 			else if (!isDeviceSinkPath(outputPath)) addPath(targets, outputPath);
 		}
 	}
-	for (const match of command.matchAll(BASH_IN_PLACE_MUTATION_COMMAND_RE)) {
+	for (const match of scanned.matchAll(BASH_IN_PLACE_MUTATION_COMMAND_RE)) {
 		const parts = shellWords(match[1] ?? "").map(cleanShellWord);
 		const hasInPlaceFlag = parts.some(part => /^-.*i/.test(part));
 		if (!hasInPlaceFlag) continue;
+		targets.explicitMutation = true;
 		const target = [...parts].reverse().find(part => part && !part.startsWith("-"));
 		if (target) addPath(targets, target);
 		else targets.unknown = true;
 	}
-	for (const match of command.matchAll(BASH_MUTATION_COMMAND_RE)) {
+	for (const match of scanned.matchAll(BASH_MUTATION_COMMAND_RE)) {
+		targets.explicitMutation = true;
 		const redirected = match[2]?.trim();
 		if (redirected) {
 			const cleaned = cleanShellWord(redirected);
@@ -666,7 +721,10 @@ export async function getWorkflowMutationDecision(
 	}
 	if (input.forceOverride) return { blocked: false, targets: [] };
 	const message = planningPhaseBlockMessage(planning.skill);
-	if (targets.unknown) {
+	// Bash during a planning phase blocks only when a filesystem mutation was
+	// actually recognized. Inspection, reads, and CLI invocations the scanner does
+	// not model stay usable; other tools keep failing closed on unknown targets.
+	if (targets.unknown && (input.tool.name !== "bash" || targets.explicitMutation)) {
 		return {
 			blocked: true,
 			message,