one-code-extension 0.4.1 → 0.5.0

package/extensions/auto-mode/resolved-paths-meta.ts

@@ -0,0 +1,133 @@
+/**
+ * The auto-mode transcript's `{"meta":{"resolvedPaths":…}}` line (pure apart
+ * from filesystem reads): where a path the action names really lands, when a
+ * symlink takes it out of the working directories.
+ *
+ * The classifier judges the call's text. `Set-Content ' leading.txt' x` reads
+ * as an in-project write even when ` leading.txt` is a symlink to
+ * `~/.ssh/authorized_keys`, and Claude Code's ruleset allows "local file
+ * operations within project scope". So the harness resolves every constant
+ * word of the action that names a path inside the working directories, and
+ * when one resolves outside them it puts the fact directly above the action,
+ * as it does the `gitStatus` line (git-status-meta.ts). An action whose paths
+ * all stay inside gets no line, so the payload of ordinary calls is Claude
+ * Code's own. The fact is measured by the harness, never read from tool input.
+ *
+ * Only words the call spells are judged: a link inside a listed directory, or
+ * a path computed at run time, is not seen (the pre-gates refuse those shapes
+ * on their own; decisions/auto-mode.md "The resolvedPaths line").
+ */
+
+import { comparablePath } from "../lib/paths.ts";
+import type { PowerShellParse } from "../lib/powershell-parser.ts";
+import { isPathSubjectTool } from "../permissions/matcher.ts";
+import { powershellSeparators, powershellUnescaped } from "../permissions/powershell-paths.ts";
+import { isWithin, resolveForContainment, resolveThroughLinks, toAbsolute, toAbsoluteBash } from "./paths.ts";
+import { parseCommand } from "./shell-parse.ts";
+
+/** One path the action names that resolves outside every working directory. */
+export interface ResolvedPathFact {
+	/** The word as the call spells it (quotes and escapes resolved). */
+	path: string;
+	/** Where it resolves through symlinks, in the filesystem's own spelling. */
+	resolvesTo: string;
+}
+
+/** The line's own explanation, since the ruleset has no sentence for it. */
+export const RESOLVED_PATHS_NOTE =
+	"Measured by the harness, not written by the agent: each path below is named by the action under review as if inside the working directory, but resolves through a symbolic link to resolvesTo, outside every working directory. Judge the action as reading or writing resolvesTo.";
+
+/** The most words one action has resolved: a huge command must not stall the gate. */
+const MAX_CANDIDATES = 256;
+/** A word longer than this is not a path worth resolving; it also bounds the line, whose words the agent wrote. */
+const MAX_WORD = 1_024;
+/** The most paths the line reports: enough to show the action escapes, bounded so it cannot swell the classifier's prompt. */
+const MAX_FACTS = 16;
+
+/** The constant words of a bash command line: every known token value and redirect target, and the value of `--opt=value`. */
+export function bashPathCandidates(command: string): string[] {
+	const words: string[] = [];
+	for (const segment of parseCommand(command).segments) {
+		for (const token of segment.tokens) {
+			if (token.dynamic) continue;
+			words.push(token.value);
+			const eq = token.value.indexOf("=");
+			if (token.value.startsWith("-") && eq > 0) words.push(token.value.slice(eq + 1));
+		}
+		words.push(...segment.redirects);
+	}
+	return words;
+}
+
+/**
+ * The constant strings of a PowerShell parse (every node PowerShell gave a
+ * value), with the backtick escapes `-Path` drops removed as a second
+ * spelling: the gate does not know which parameter took the value.
+ */
+export function powershellPathCandidates(parse: PowerShellParse): string[] {
+	const words: string[] = [];
+	for (const node of parse.nodes) {
+		if (typeof node.value !== "string") continue;
+		words.push(node.value);
+		const unescaped = powershellUnescaped(node.value);
+		if (unescaped !== node.value) words.push(unescaped);
+	}
+	return words;
+}
+
+export interface ResolvedPathsOptions {
+	/** The call's working directory. */
+	cwd: string;
+	home: string;
+	/** Every working directory (the cwd and any added workspace directories). */
+	roots: readonly string[];
+	/** How the words spell a path: `bash` (Git Bash's `/c/…` on Windows), `powershell` (`\` separates on macOS and Linux too), else the platform's own. */
+	spelling?: "bash" | "powershell";
+}
+
+/**
+ * The words that name a path inside a working directory but resolve outside
+ * all of them, or undefined when none does. A word that is outside as spelled
+ * (`/etc/hosts`, `../x`) is left to the classifier's own reading of the text.
+ */
+export function resolvedPathFacts(words: readonly string[], opts: ResolvedPathsOptions): ResolvedPathFact[] | undefined {
+	const roots = opts.roots.map((root) => resolveForContainment(root) ?? root);
+	// A word may spell a root through the alias it was given as (`/var/…` for
+	// `/private/var/…`): it names a path inside when it sits under either spelling.
+	const spelledRoots = [...opts.roots, ...roots];
+	const { cwd } = opts;
+	const facts: ResolvedPathFact[] = [];
+	const seen = new Set<string>();
+	for (const word of words) {
+		if (seen.size >= MAX_CANDIDATES || facts.length >= MAX_FACTS) break;
+		if (!word || word.length > MAX_WORD || word.includes("\0") || seen.has(word)) continue;
+		seen.add(word);
+		const lexical =
+			opts.spelling === "bash"
+				? toAbsoluteBash(cwd, word, opts.home)
+				: toAbsolute(cwd, opts.spelling === "powershell" ? powershellSeparators(word) : word, opts.home);
+		if (!spelledRoots.some((root) => isWithin(root, lexical))) continue;
+		const resolvesTo = resolveThroughLinks(lexical);
+		if (resolvesTo === undefined || roots.some((root) => isWithin(root, comparablePath(resolvesTo)))) continue;
+		facts.push({ path: word, resolvesTo });
+	}
+	return facts.length > 0 ? facts : undefined;
+}
+
+/**
+ * The facts for one action under review, or undefined: a shell command's
+ * constant words (`bash` and `monitor` from the bash parse, `powershell` from
+ * PowerShell's own parse, none without one), or a path tool's path argument.
+ * `subject` is the command line or the path, as the permission gate extracts it.
+ */
+export function actionResolvedPaths(
+	tool: string,
+	subject: string,
+	powershellParse: PowerShellParse | undefined,
+	opts: Omit<ResolvedPathsOptions, "spelling">,
+): ResolvedPathFact[] | undefined {
+	if (!subject) return undefined;
+	if (tool === "bash" || tool === "monitor") return resolvedPathFacts(bashPathCandidates(subject), { ...opts, spelling: "bash" });
+	if (tool === "powershell") return powershellParse ? resolvedPathFacts(powershellPathCandidates(powershellParse), { ...opts, spelling: "powershell" }) : undefined;
+	return isPathSubjectTool(tool) ? resolvedPathFacts([subject], opts) : undefined;
+}

package/extensions/auto-mode/rules.ts

@@ -12,7 +12,7 @@
  * `unmatched`, so a hallucinated name cannot borrow a real HARD rule's authority.
  * The rule's own name is what the user sees; the model's wording is kept as
  * commentary that is never mistaken for fact. This is decision 1 in
- * docs/decisions/auto-mode.md, re-expressed against CC's category scheme in
+ * working-docs/decisions/auto-mode.md, re-expressed against CC's category scheme in
  * place of our old H1/S4/A2 ids.
  */
 
@@ -106,6 +106,23 @@ export function buildCategoryIndex(ruleset: string): RuleIndex {
 	return { rules, byName };
 }
 
+const countRules = (section: string): number => section.split("\n").filter((line) => ruleNameFromLine(line) !== undefined).length;
+
+/**
+ * How many rules each section of a ruleset holds, counted like the index (one
+ * per top-level bullet). On the embedded ruleset with no user extras, this is
+ * what the /permissions Auto mode tab shows as the built-in rules of each
+ * section (findings §33: Claude Code shows 70 soft-deny rules because it counts
+ * the Artifact consent rule this ruleset does not carry).
+ */
+export function builtinRuleCounts(ruleset: string): { hard_deny: number; soft_deny: number; allow: number } {
+	return {
+		hard_deny: countRules(sliceSection(ruleset, HARD_HEADING, SOFT_HEADING)),
+		soft_deny: countRules(sliceSection(ruleset, SOFT_HEADING, ALLOW_HEADING)),
+		allow: countRules(sliceSection(ruleset, ALLOW_HEADING, "\n## ")),
+	};
+}
+
 /** Look up a category the classifier emitted. undefined ⇒ not a known BLOCK rule. */
 export function groundCategory(index: RuleIndex, category: string | undefined): IndexedRule | undefined {
 	if (!category) return undefined;

package/extensions/auto-mode/safety-floor.ts

@@ -17,16 +17,26 @@
  * complete to be sound — a `sed -i` on settings.json that the shell evidence
  * does not model as a write is the classifier's to catch, as today.
  *
+ * The consent stores (`lib/consent-stores.ts`) are gate controls too: an
+ * entry in one approves a repository's hooks, MCP servers, allow rules or
+ * language servers for every later session. So are the cached model catalogs
+ * (`lib/model-catalog-data.ts catalogCacheFiles`): they decide the model's
+ * tier, and the tier decides which fast paths skip the classifier.
+ *
  * The target list is deliberately exact files, not directories: ~/.claude also
  * holds memory and skills that the agent writes routinely, and a floor that
  * fires on routine work teaches the user to approve without reading.
  */
 
-import { analyzeShellCommand } from "./shell-analysis.ts";
-import { autoModeSettingsPaths } from "./config.ts";
-import { oneCodeProjectSettingsPath } from "../lib/one-code-settings.ts";
-import { claudeJsonPath, comparablePath } from "../lib/paths.ts";
-import { isWritingTool, resolveForContainment, toAbsolute } from "./paths.ts";
+import { FIND_PATTERN_TESTS, findNegatedPatterns } from "./read-only-options.ts";
+import { analyzeShellCommand, globComponentRegex, hasReadOnlyShellWords, isUnknownTilde, LOOPS, movesDirectory, parseCommand, resolvePayload, scopedTracker } from "./shell-analysis.ts";
+import type { Token } from "./shell-parse.ts";
+import { claudeUserSettingsPath, managedSettingsPaths } from "../lib/claude-settings.ts";
+import { CONSENT_STORE_TAIL, consentStorePaths } from "../lib/consent-stores.ts";
+import { oneCodeProjectSettingsPath, oneCodeSettingsPath } from "../lib/one-code-settings.ts";
+import { CATALOG_CACHE_TAIL, catalogCacheFiles } from "../lib/model-catalog-data.ts";
+import { claudeJsonPath, comparablePath, oneCodeStateDir } from "../lib/paths.ts";
+import { isWritingTool, resolveForContainment, toAbsolute, toAbsoluteBash } from "./paths.ts";
 
 /** The same comparison form resolveForContainment's output is in (lib/paths.ts). */
 const fold = comparablePath;
@@ -53,8 +63,13 @@ const ONECODE_SETTINGS_TAIL = /\/\.onecode\/(projects\/[^/]+\/)?settings\.json$/
 function safetyControlFiles(home: string, oneCodeProjectSettings?: string): string[] {
 	return [
 		// autoMode + user permission rules, and the managed-settings paths (the
-		// global ~/.onecode/settings.json here honours ONECODE_STATE_DIR).
-		...autoModeSettingsPaths(home),
+		// global ~/.onecode/settings.json here honours ONECODE_STATE_DIR). Spelled
+		// out, not the mode-aware autoModeSettingsPaths: independent mode reads no
+		// Claude Code file, but one written there would take effect the moment
+		// the user switches back, so the floor guards it in both modes.
+		claudeUserSettingsPath(home),
+		oneCodeSettingsPath(home),
+		...managedSettingsPaths(),
 		// Claude Code's global state file also carries permission configuration;
 		// claudeJsonPath honours CLAUDE_CONFIG_DIR so a relocated file is still caught.
 		claudeJsonPath(home),
@@ -62,6 +77,12 @@ function safetyControlFiles(home: string, oneCodeProjectSettings?: string): stri
 		// tail regex catches it under a literal `.onecode`; this catches it when
 		// ONECODE_STATE_DIR relocated the state root (review L2).
 		...(oneCodeProjectSettings ? [oneCodeProjectSettings] : []),
+		// The consent stores: an entry approves a repository's hooks, MCP
+		// servers, allow rules or language servers for every later session.
+		...consentStorePaths(home),
+		// The cached model catalogs decide the model's tier, and the tier decides
+		// which fast paths skip the classifier.
+		...catalogCacheFiles(oneCodeStateDir(process.env, home)),
 	];
 }
 
@@ -71,14 +92,75 @@ function safetyControlFiles(home: string, oneCodeProjectSettings?: string): stri
  * by the caller (once per session) so this need not re-walk for the project root.
  */
 export function isSafetyControlTarget(resolved: string, home: string, oneCodeProjectSettings?: string): boolean {
+	return matchesControlFile(resolved, controlFileForms(home, oneCodeProjectSettings));
+}
+
+/**
+ * Every comparison form of the control files: each resolved like a write
+ * target, or the two sides can disagree about the same file (macOS /var →
+ * /private/var), plus its literal spelling.
+ */
+function controlFileForms(home: string, oneCodeProjectSettings?: string): Set<string> {
+	const forms = new Set<string>();
+	for (const file of safetyControlFiles(home, oneCodeProjectSettings)) {
+		forms.add(resolveForContainment(file) ?? fold(file));
+		forms.add(fold(file));
+	}
+	return forms;
+}
+
+function matchesControlFile(resolved: string, forms: ReadonlySet<string>): boolean {
 	const target = fold(resolved);
-	if (SETTINGS_TAIL.test(target) || ONECODE_SETTINGS_TAIL.test(target)) return true;
-	// The control files go through the same resolution as the write target, or
-	// the two sides can disagree about the same file (macOS /var → /private/var).
-	return safetyControlFiles(home, oneCodeProjectSettings).some((file) => {
-		const control = resolveForContainment(file) ?? fold(file);
-		return control === target || fold(file) === target;
-	});
+	return SETTINGS_TAIL.test(target) || ONECODE_SETTINGS_TAIL.test(target) || CONSENT_STORE_TAIL.test(target) || CATALOG_CACHE_TAIL.test(target) || forms.has(target);
+}
+
+const GLOB_CHARS = /[*?[]/;
+
+/**
+ * Whether a resolved shell path names a control file, literally or as a glob
+ * the shell expands onto one (`> .claude/settings.*`, `.claude/s*.json`). A
+ * glob leaf is tried against every control file name in its directory; a glob
+ * in a directory component stops whenever the leaf could spell a control
+ * file's name, since the floor may only ever say "stop". `dotRule` is bash's:
+ * a leaf not starting with `.` never matches a name that does.
+ */
+function namesControlFile(resolved: string, forms: ReadonlySet<string>, dotRule: boolean): boolean {
+	if (matchesControlFile(resolved, forms)) return true;
+	const target = fold(resolved);
+	if (!GLOB_CHARS.test(target)) return false;
+	const slash = target.lastIndexOf("/");
+	const dir = target.slice(0, slash);
+	const leaf = target.slice(slash + 1);
+	// An uncompilable bracket expression matches nothing: the shell writes the literal name.
+	const regex = globComponentRegex(leaf);
+	if (!regex) return false;
+	const names = new Set(["settings.json", "settings.local.json"]);
+	for (const form of forms) names.add(form.slice(form.lastIndexOf("/") + 1));
+	const spelled = [...names].filter((name) => regex.test(name) && !(dotRule && name.startsWith(".") && !leaf.startsWith(".")));
+	if (spelled.length === 0) return false;
+	return GLOB_CHARS.test(dir) || spelled.some((name) => matchesControlFile(`${dir}/${name}`, forms));
+}
+
+/**
+ * A find's negated pattern operands, by token index: those that only exclude
+ * files (`findNegatedPatterns`), which name nothing, and the rest, which may
+ * select every file but the ones they name. A find that is not read-only acts
+ * on every file a negated pattern leaves in (`! -name keep -delete`), and its
+ * expression is not read, so there every pattern after any `!`/`-not` selects.
+ */
+function negatedFindPatterns(tokens: readonly Token[], args: readonly Token[]): { excluding: Set<number>; selecting: Set<number> } {
+	const offset = tokens.length - args.length;
+	const shift = (indexes: Set<number>) => new Set([...indexes].map((index) => index + offset));
+	const readOnly = findNegatedPatterns(args);
+	if (readOnly) return { excluding: shift(readOnly.excluding), selecting: shift(readOnly.selecting) };
+	const selecting = new Set<number>();
+	let negated = false;
+	for (let index = 0; index + 1 < tokens.length; index++) {
+		const word = tokens[index].value;
+		if (word === "!" || word === "-not") negated = true;
+		else if (negated && FIND_PATTERN_TESTS.has(word)) selecting.add(index + 1);
+	}
+	return { excluding: new Set(), selecting };
 }
 
 export interface FloorInput {
@@ -96,8 +178,32 @@ export interface FloorInput {
 	oneCodeProjectSettings?: string;
 }
 
+/**
+ * A wildcard or negated pattern (`./node_modules/*`, `!**\/node_modules/**`):
+ * the command may select a control file without naming one, so "it writes"
+ * would be false and a read-only search can pass rewritten without it.
+ */
+const PATTERN_TOKEN = /^!|[*?[]/;
+const PATTERN_REASON = "its pattern ";
+
 const REASON = (token: string) =>
-	`it writes ${token}, which holds the permission rules and auto-mode configuration that contain this agent`;
+	CATALOG_FILE_NAME.test(token)
+		? `it writes ${token}, a model catalog that decides the model tier the auto-mode checks that contain this agent depend on`
+		: PATTERN_TOKEN.test(token)
+			? `${PATTERN_REASON}${token} can select a file that holds the permission rules and auto-mode configuration that contain this agent`
+			: `it writes ${token}, which holds the permission rules and auto-mode configuration that contain this agent`;
+
+/** The model-facing block text for a floor reason. The floor re-checks a rewrite, and the classifier still judges it. */
+export function safetyFloorBlockText(reason: string): string {
+	const opening = `Auto mode blocked this call without consulting the classifier: ${reason}.`;
+	if (reason.startsWith(PATTERN_REASON)) {
+		return `${opening} A command that may touch the gate's own configuration is never auto-approved. If this is a read-only search, rewrite it without the wildcard or negated pattern (for example \`grep -r --exclude-dir=node_modules\`); otherwise ask the user to run it themselves.`;
+	}
+	return `${opening} Writes to the gate's own configuration are never auto-approved. Do not retry or route around this; ask the user to make the change themselves.`;
+}
+
+/** A cached catalog's file name, to word the reason (a false match only rewords it). */
+const CATALOG_FILE_NAME = /(^|[/\\])(models-dev|openrouter|huggingface|refresh-failed)\.json$/i;
 
 /**
  * Reason text when this call writes a safety-control file, undefined otherwise.
@@ -115,12 +221,28 @@ export function safetyControlWrite({ toolName, input, cwd, home, oneCodeProjectS
 		return resolved && isSafetyControlTarget(resolved, home, perRepoSettings) ? REASON(raw) : undefined;
 	}
 
-	if (toolName === "bash") {
+	// `monitor` runs a shell command exactly as `bash` does (review L1).
+	if (toolName === "bash" || toolName === "monitor") {
 		const command = typeof input.command === "string" ? input.command : "";
 		if (!command) return undefined;
 		const evidence = analyzeShellCommand({ command, cwd, home });
+		const forms = controlFileForms(home, perRepoSettings);
 		for (const write of evidence.writes) {
-			if (write.resolved && isSafetyControlTarget(write.resolved, home, perRepoSettings)) return REASON(write.token);
+			if (write.resolved && namesControlFile(write.resolved, forms, true)) return REASON(write.token);
+		}
+		// A command the pre-gate cannot prove read-only may write in ways its
+		// evidence does not model (an output operand, an option's value, a
+		// nested script), and until 2026-09-23 such a write reached neither this
+		// floor nor, when the pre-gate wrongly said "safe", the classifier
+		// (SECURITY-REVIEW-2026-09-23 H3). So for those the floor is textual, as
+		// the PowerShell one below: any unproven word naming a gate-control file
+		// stops the call. Proven read-only simple commands are excluded even in
+		// an escalated compound line; their redirects and nested code are not.
+		// `readOnlyOutside` means every command was proven read-only by its
+		// options and only the location escalated: a read, not a hidden write.
+		if (evidence.verdict === "escalate" && !evidence.readOnlyOutside) {
+			const named = shellNamesControlFile(command, cwd, home, perRepoSettings, 0, forms);
+			if (named) return REASON(named);
 		}
 	}
 
@@ -132,9 +254,11 @@ export function safetyControlWrite({ toolName, input, cwd, home, oneCodeProjectS
 		// gate (the floor may only ever say "stop" — header).
 		const command = typeof input.command === "string" ? input.command : "";
 		if (!command) return undefined;
+		// PowerShell wildcards (`*`, `?`, `[…]`) have no leading-dot rule.
+		const forms = controlFileForms(home, perRepoSettings);
 		for (const token of powershellPathTokens(command, home)) {
 			const absolute = toAbsolute(cwd, token, home);
-			if (isSafetyControlTarget(resolveForContainment(absolute) ?? absolute, home, perRepoSettings)) return REASON(token);
+			if (namesControlFile(resolveForContainment(absolute) ?? absolute, forms, false)) return REASON(token);
 		}
 	}
 
@@ -167,3 +291,222 @@ export function powershellPathTokens(command: string, home: string): string[] {
 	}
 	return out;
 }
+
+/**
+ * A `{var}>f` redirect, which assigns the descriptor's number to var. The
+ * grammar reads `{var}` as a word, or not at all after a compound command, so
+ * it is matched in the line's text.
+ */
+const VAR_REDIRECT = /\{[A-Za-z_][A-Za-z0-9_]*\}[<>]/;
+
+/**
+ * The gate-control file spellings the textual floor matches in a command line,
+ * lowercased, with `\\` turned to `/` and `/./`, `//` collapsed.
+ */
+const CONTROL_FILE_TEXT =
+	/(^|[\s'"=/<>|;&(:])(\.claude\/settings(\.local)?\.json|\.onecode\/(projects\/[^\s'"/]+\/)?settings\.json|\.onecode\/cache\/model-catalog\/(models-dev|openrouter|huggingface|refresh-failed)\.json|managed-settings\.json|\.claude\.json)(?=$|[\s'";|&)<>])/;
+
+/**
+ * `$_` (or `${_}`, `${#_}`, …) anywhere in the line: bash's last argument of
+ * the previous command, which carries a proven read-only command's words into
+ * a later one (`echo .claude/settings.json; rm "$_"`). Raw text, so heredoc
+ * bodies and quoted spellings count too; a false positive costs one stop.
+ */
+const LAST_ARGUMENT = /\$(?:_|\{[#!]?_)(?![A-Za-z0-9_])/;
+
+/**
+ * The literal text every match of a find `-regex` pattern ends with (find
+ * anchors the pattern to the whole path), or undefined when that is not
+ * certain: no literal tail, or alternation anywhere (`|` or emacs `\|`).
+ * Wildcards, groups, intervals and classes end the tail in either the emacs
+ * or the POSIX spelling. Only `\` before one of `.*+?[]^$\/-` is a literal;
+ * any other escape (emacs `\'` is an anchor, `\w` a class) ends the tail.
+ */
+export function regexLiteralTail(pattern: string): string | undefined {
+	if (pattern.includes("|")) return undefined;
+	const units: Array<{ literal: boolean; text: string }> = [];
+	for (let i = 0; i < pattern.length; i++) {
+		const char = pattern[i];
+		if (char === "\\" && i + 1 < pattern.length) {
+			const next = pattern[++i];
+			units.push({ literal: /[.*+?[\]^$\\/-]/.test(next), text: next });
+		} else units.push({ literal: !/[.[\]*+?^$(){}\\]/.test(char), text: char });
+	}
+	// A trailing unescaped `$` only re-anchors the end find anchors anyway.
+	if (units.at(-1)?.text === "$" && !units.at(-1)!.literal) units.pop();
+	let tail = "";
+	for (let i = units.length - 1; i >= 0 && units[i].literal; i--) tail = units[i].text + tail;
+	return tail || undefined;
+}
+
+/**
+ * The first word of a shell line that names a gate-control file, or
+ * undefined. Every word not proven read-only counts, plus the value after an `=`
+ * (`--output=…`, `of=…`) and the words of a nested `sh -c '…'` script, read
+ * from proven words too (`echo '…'` may print a script to a file); `cd`
+ * is followed, per subshell scope, so a relative name is resolved where the
+ * shell would. Where the directory cannot be known (the line does not parse,
+ * a `cd` sits in a loop body that runs more than once, or its target is an
+ * expansion), a word whose file name is a control file's stops by name alone.
+ * False positives cost one stop; the floor may only ever say "stop".
+ */
+export function shellNamesControlFile(
+	command: string,
+	cwd: string,
+	home: string,
+	oneCodeProjectSettings?: string,
+	depth = 0,
+	/** Resolved once per top-level call, not once per word. */
+	forms: ReadonlySet<string> = controlFileForms(home, oneCodeProjectSettings),
+): string | undefined {
+	const { segments, parseFailed, unknownQuoting, unattributedExpansion, definesFunction, pipelines } = parseCommand(command);
+	const dirs = scopedTracker(cwd);
+	const ignoredRanges: { start: number; end: number }[] = [];
+	// Functions/eval can replace a read-only command; loop headers, case
+	// subjects and `{var}>` redirects can change shell state outside the
+	// attributed words. A compound command's redirect (`{ …; } > f`,
+	// `fi > f`) or an `exec` one sends a proven command's output, unquoted
+	// words and all, to a file a later command can run; /dev/null and
+	// descriptor dups capture nothing. Never use a partial parse, such a
+	// construct, or a nested script to subtract evidence.
+	const capturesOutput = segments.some((segment) =>
+		segment.redirects.some((target) => target !== "/dev/null") && (segment.tokens.length === 0 || resolvePayload(segment.tokens).command === "exec"),
+	);
+	const canProveWords = depth === 0 && !parseFailed && !unknownQuoting && !unattributedExpansion && !definesFunction && !capturesOutput && !VAR_REDIRECT.test(command) && !segments.some((segment) =>
+		segment.enclosing.some((construct) => LOOPS.has(construct) || construct === "case_statement") ||
+		["eval", "source", ".", "alias", "enable", "trap"].includes(resolvePayload(segment.tokens).command),
+	) && !LAST_ARGUMENT.test(command);
+
+	// Decided before the walk: in a loop, a word read before the `cd` runs after it on the next pass.
+	const unknownDir =
+		parseFailed ||
+		segments.some((segment) => {
+			const payload = resolvePayload(segment.tokens);
+			// A script run in this shell (`eval "cd .claude"`, `source f`) may `cd` too.
+			if (["eval", "source", "."].includes(payload.command)) return true;
+			if (!movesDirectory(segment)) return false;
+			const target = payload.args.find((token) => !token.value.startsWith("-"));
+			// `cd -` goes to $OLDPWD.
+			const previous = payload.args.some((token) => token.value === "-");
+			return (
+				payload.command !== "cd" ||
+				previous ||
+				// A pipeline's last `cd` moves the later commands of its own shell
+				// under lastpipe, inside a substitution too.
+				!!segment.pipelineShell ||
+				// `false && cd x` may or may not move the commands after it.
+				!!segment.conditional ||
+				segment.enclosing.some((construct) => LOOPS.has(construct)) ||
+				!!target?.dynamic ||
+				!!target?.glob ||
+				(!!target && isUnknownTilde(target.value))
+			);
+		});
+	// Lowercased on every platform: a false positive costs one stop.
+	const baseName = (path: string) => path.slice(path.replace(/\\/g, "/").lastIndexOf("/") + 1).toLowerCase();
+	const controlNames = new Set([...forms].map(baseName));
+	// First pass, in order: each segment's directory and whether its words
+	// alone are proven read-only. The cd tracking runs here so the second pass
+	// can look ahead at a whole pipeline.
+	let shellChanged = false;
+	const facts = segments.map((segment) => {
+		const dir = dirs.get(segment);
+		const payload = resolvePayload(segment.tokens);
+		// A previous assignment or stateful builtin can change command lookup
+		// (PATH, a hash entry, shell options, …). Arithmetic commands and
+		// expansions can assign too. A standalone command proof cannot account
+		// for that state. Even inert assignments/expansions forfeit it.
+		shellChanged ||= !!segment.unknownTarget || !!segment.expandsIntoInput ||
+			segment.tokens.some((word) => word.dynamic || /^[A-Za-z_][A-Za-z0-9_]*(\[[^\]]*\])?\+?=/.test(word.value)) ||
+			["read", "readarray", "mapfile", "getopts", "printf", "export", "declare", "typeset", "local", "readonly", "unset", "set", "shopt", "hash", "let", "wait", "coproc"].includes(payload.command);
+		const proven = canProveWords && !shellChanged && !unknownDir &&
+			segment.wordRanges?.length === segment.tokens.length && hasReadOnlyShellWords(segment, dir, home);
+		if (payload.command === "cd" && !unknownDir) {
+			const target = payload.args.find((token) => !token.value.startsWith("-"));
+			if (target) dirs.set(segment, toAbsoluteBash(dir, target.value, home));
+		}
+		return { dir, payload, proven };
+	});
+	// Pipeline output may itself be a script (`echo '…' | sh`), so a pipeline
+	// member keeps its words out of the scan only when the pipeline sits in the
+	// top-level shell and every member is one proven read-only command: then
+	// no member runs another's output (`find … | sort`). Substitutions and
+	// `( … )` stay textual.
+	const provenPipelineScopes = new Set<number>();
+	for (const members of pipelines) {
+		const inMember = members.map((scope) => segments.flatMap((segment, index) => (segment.scopes.length === 1 && segment.scopes[0] === scope ? [index] : [])));
+		const nested = segments.some((segment) => segment.scopes.length > 1 && members.includes(segment.scopes[0]));
+		if (!nested && inMember.every((indexes) => indexes.length === 1 && facts[indexes[0]].proven)) {
+			for (const scope of members) provenPipelineScopes.add(scope);
+		}
+	}
+	for (const [index, segment] of segments.entries()) {
+		const { dir, payload, proven } = facts[index];
+		const readOnly = proven && (segment.scopes.length === 0 || (segment.scopes.length === 1 && provenPipelineScopes.has(segment.scopes[0])));
+		if (readOnly) ignoredRanges.push(...segment.wordRanges!);
+		// -regex/-iregex match the whole path, which the file-name glob check
+		// cannot model. An unproven find selecting by one stops unless the
+		// pattern's fixed tail rules out every control file's name, and only a
+		// plain conjunction can rely on that: `! -regex '.*\.orig'` or a `-o`
+		// branch selects everything the pattern does not.
+		if (!readOnly && payload.command === "find") {
+			const uncertain = payload.args.some((token) => ["-regextype", "!", "-not", "-o", "-or", ","].includes(token.value));
+			for (const [i, token] of payload.args.entries()) {
+				if (token.value !== "-regex" && token.value !== "-iregex") continue;
+				const pattern = payload.args[i + 1];
+				if (!pattern || pattern.dynamic || uncertain) return pattern?.value ?? token.value;
+				const tail = regexLiteralTail(pattern.value)?.toLowerCase();
+				const name = tail?.slice(tail.lastIndexOf("/") + 1);
+				if (tail === undefined || name === undefined || [...controlNames].some((control) => tail.includes("/") ? control === name : control.endsWith(name))) return pattern.value;
+			}
+		}
+		const negated = payload.command === "find" && !readOnly ? negatedFindPatterns(segment.tokens, payload.args) : undefined;
+		const words = [
+			...segment.tokens.map((token, index) => ({ value: token.value, index, exempt: readOnly })),
+			...[...segment.redirects, ...segment.inputs.map((token) => token.value)].map((value) => ({ value, index: -1, exempt: false })),
+		];
+		for (const { value: word, index: at, exempt } of words) {
+			// A proven command's words are still read as a script: its output can
+			// reach a file it never names, through an enclosing redirect, an
+			// `exec` or a descriptor (`{ echo '…'; } > s.sh; sh s.sh`). Only
+			// their path match is exempt.
+			if (depth < 3 && /\s/.test(word)) {
+				const nested = shellNamesControlFile(word, dir, home, oneCodeProjectSettings, depth + 1, forms);
+				if (nested) return nested;
+			}
+			if (exempt) continue;
+			// find never opens or writes a pattern operand, and one that only
+			// excludes files names nothing (a loop elsewhere in the line leaves
+			// every word unproven). A negated pattern that may select everything
+			// else may select a control file.
+			if (negated?.excluding.has(at)) continue;
+			if (negated?.selecting.has(at)) return word;
+			const eq = word.indexOf("=");
+			for (const candidate of eq >= 0 ? [word, word.slice(eq + 1)] : [word]) {
+				if (!candidate || isUnknownTilde(candidate)) continue;
+				const resolved = resolveForContainment(toAbsoluteBash(dir, candidate, home));
+				if (resolved && namesControlFile(resolved, forms, true)) return candidate;
+				if (unknownDir && controlNames.has(baseName(candidate))) return candidate;
+				// find matches names beneath its search roots, not the shell's cwd.
+				// An unproven expression may delete/execute on any such match.
+				if (payload.command === "find") {
+					const pattern = globComponentRegex(baseName(candidate));
+					if (pattern && [...controlNames].some((name) => pattern.test(name))) return candidate;
+				}
+			}
+		}
+	}
+	// Keep the raw-text fallback for syntax/words the walker cannot attribute,
+	// heredoc bodies included. Only exact source ranges of proven command
+	// words disappear; never use string replacement (the same text may also
+	// occur in a redirect or in an unproven command).
+	let unproven = "";
+	let at = 0;
+	for (const range of ignoredRanges.sort((a, b) => a.start - b.start)) {
+		unproven += command.slice(at, range.start) + " ";
+		at = range.end;
+	}
+	unproven += command.slice(at);
+	const text = unproven.toLowerCase().replace(/\\/g, "/").replace(/\/\.\//g, "/").replace(/\/{2,}/g, "/");
+	return CONTROL_FILE_TEXT.exec(text)?.[2];
+}