one-code-extension 0.4.0 → 0.5.0

package/extensions/auto-mode/config.ts

@@ -22,7 +22,7 @@
  * `~/.claude`: One Code used to write them there, and a stale value (a model the
  * session cannot reach) must not keep biting. Every write goes to
  * `~/.onecode/settings.json`; One Code never mutates Claude Code's files. See
- * "Own state, borrowed config" in docs/decisions/memory-state.md.
+ * "Own state, borrowed config" in working-docs/decisions/memory-state.md.
  *
  * ## The customization surface (CC 2.1.233's own)
  *
@@ -42,11 +42,12 @@
  *
  * (The rule lists were briefly retired between the ruleset adoption and CC
  * 2.1.233 shipping `/auto-mode-setup`, which writes this exact schema — see
- * docs/decisions/auto-mode.md.)
+ * working-docs/decisions/auto-mode.md.)
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { claudeUserSettingsPath } from "../lib/claude-settings.ts";
+import { claudeUserSettingsPath, managedSettingsPaths } from "../lib/claude-settings.ts";
+import { claudeSourcesOn } from "../lib/config-mode.ts";
 import { oneCodeSettingsPath, readSettingsForWrite, writeSettings } from "../lib/one-code-settings.ts";
 import { DEFAULT_ENVIRONMENT, slotName } from "./defaults.ts";
 
@@ -61,12 +62,12 @@ export interface AutoModeConfig {
 	allow: string[];
 	/** Suspend narrow Bash allow rules so every shell command reaches the classifier. */
 	classifyAllShell: boolean;
-	/** `provider/model-id` override for the classifier model. */
+	/** `provider/model-id` the user chose for the classifier (`/auto-mode model`). */
 	classifierModel?: string;
 	/**
 	 * Containment identity (`modelIdentity().containment`) the `classifierModel`
 	 * was stamped for when set via `/auto-mode model`. A cross-provider setting
-	 * whose stamp no longer matches the session is treated as stale and overridden
+	 * whose stamp no longer matches the session is treated as stale and replaced
 	 * — see `classifierCandidates`. Undefined for a hand-edited setting.
 	 */
 	classifierModelSetFor?: string;
@@ -91,21 +92,16 @@ interface AutoModeSettingsFile {
 
 const DEFAULTS_TOKEN = "$defaults";
 
-/** Managed-settings locations, highest authority, matching Claude Code's paths. */
-export function managedSettingsPaths(): string[] {
-	if (process.platform === "darwin") return ["/Library/Application Support/ClaudeCode/managed-settings.json"];
-	if (process.platform === "win32") return ["C:\\ProgramData\\ClaudeCode\\managed-settings.json"];
-	return ["/etc/claude-code/managed-settings.json"];
-}
-
 /**
  * The files `autoMode` is read from, lowest precedence first. One Code's own
  * auto-mode keys (`classifierModel`, `classifierModelSetFor`) are deliberately
- * NOT collected from the borrowed `claudeUserSettingsPath` — Claude Code does not
- * define them, and One Code once wrote them there, so a stale value must not
- * survive the move to `~/.onecode` (see the read guard in the loader).
+ * NOT collected from the borrowed `claudeUserSettingsPath` (see the read guard
+ * in the loader).
  */
 export function autoModeSettingsPaths(home: string): string[] {
+	// Independent mode (lib/config-mode.ts) reads One Code's file alone; the
+	// built-in rules apply regardless, since settings only append to them.
+	if (!claudeSourcesOn()) return [oneCodeSettingsPath(home)];
 	return [claudeUserSettingsPath(home), oneCodeSettingsPath(home), ...managedSettingsPaths()];
 }
 
@@ -285,7 +281,7 @@ export function loadAutoModeConfigWithDiagnostics(home: string): AutoModeConfigL
 		// `classifierModel` is One Code's own key, not Claude Code's. It is read from
 		// `~/.onecode` and managed settings only — never from `~/.claude`, where an
 		// old One Code build may have left a stale value. A leftover in `~/.claude` is
-		// surfaced as a diagnostic so the user knows why it stopped applying.
+		// surfaced as a diagnostic so the user knows why it does not apply.
 		if (typeof block.classifierModel === "string" && block.classifierModel.trim()) {
 			if (path === claudeUser) {
 				diagnostics.push(
@@ -331,9 +327,8 @@ export function loadAutoModeConfig(home: string): AutoModeConfig {
 /**
  * Persist `autoMode.classifierModel` in One Code's own settings file
  * (`~/.onecode/settings.json`), preserving every other key. `undefined` removes
- * the setting. Never touches Claude Code's files — this is One Code's key, and
- * the knob that may move the classifier to another provider, so it lives in One
- * Code's own state (see the module comment).
+ * the setting. Never touches Claude Code's files: this is One Code's key, and
+ * the knob that may move the classifier to another provider.
  *
  * Unlike loading, this throws on a malformed file: a lenient read merely skips
  * rules, but a lenient write would replace the whole settings file with only ours.
@@ -369,7 +364,7 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
  * Persist a `/auto-mode setup` result to One Code's own settings file: replace
  * the wizard-owned keys (environment + the three rule lists — an undefined list
  * removes stale values, last-writer like CC's own wizard) while preserving every
- * other settings key and the non-wizard autoMode keys (classifierModel, …).
+ * other settings key and non-wizard autoMode keys.
  * Never touches Claude Code's files; throws on a malformed file rather than
  * replacing the settings with only ours.
  */
@@ -387,6 +382,63 @@ export function persistAutoModeSetup(patch: Record<string, string[] | undefined>
 	writeSettings(path, file);
 }
 
+/** The auto-mode keys the /permissions Auto mode tab lists and edits. */
+export type AutoModeListKey = "allow" | "soft_deny" | "hard_deny" | "environment";
+
+export interface SourcedAutoModeEntry {
+	key: AutoModeListKey;
+	text: string;
+	source: "claude-user" | "onecode-user" | "managed";
+	path: string;
+}
+
+/**
+ * Every auto-mode rule and environment entry with the file it came from, in
+ * load order. `"$defaults"` is left out: in the rule lists it means nothing
+ * here (the built-ins always apply), and in the environment it is the
+ * splice point, shown as the built-in default rather than as an entry.
+ */
+export function listAutoModeEntries(home: string): SourcedAutoModeEntry[] {
+	const claudeUser = claudeUserSettingsPath(home);
+	const oneCodeUser = oneCodeSettingsPath(home);
+	const entries: SourcedAutoModeEntry[] = [];
+	for (const path of autoModeSettingsPaths(home)) {
+		const block = asRecord(readFile(path, [])?.autoMode);
+		if (!block) continue;
+		const source = path === claudeUser ? "claude-user" : path === oneCodeUser ? "onecode-user" : "managed";
+		for (const key of ["allow", "soft_deny", "hard_deny", "environment"] as const) {
+			for (const text of stringArray(block[key]) ?? []) {
+				if (text.trim() !== DEFAULTS_TOKEN) entries.push({ key, text, source, path });
+			}
+		}
+	}
+	return entries;
+}
+
+/** Whether One Code's own `autoMode.environment` keeps the built-in default through `"$defaults"`. */
+export function oneCodeEnvironmentExtendsDefault(home: string): boolean {
+	const block = asRecord(readFile(oneCodeSettingsPath(home), [])?.autoMode);
+	return (stringArray(block?.environment) ?? []).some((text) => text.trim() === DEFAULTS_TOKEN);
+}
+
+/**
+ * Rewrite one auto-mode list in One Code's own settings file. An emptied list
+ * is removed (for the environment, that restores the built-in default), and so
+ * is an emptied `autoMode` block. Throws on a malformed file, like the other
+ * writers.
+ */
+export function updateOneCodeAutoModeList(key: AutoModeListKey, update: (entries: string[]) => string[], home: string): void {
+	const path = oneCodeSettingsPath(home);
+	const file = readSettingsForWrite(path);
+	const block = asRecord(file.autoMode) ?? {};
+	const next = update(stringArray(block[key]) ?? []);
+	if (next.length === 0) delete block[key];
+	else block[key] = next;
+	if (Object.keys(block).length === 0) delete file.autoMode;
+	else file.autoMode = block;
+	writeSettings(path, file);
+}
+
 /**
  * The `permissions.allow` entries in One Code's own settings file — what the
  * setup audit can actually remove. Broad rules that live in Claude Code's files

package/extensions/auto-mode/decision-log.ts

@@ -38,6 +38,8 @@ export interface DecisionEntry {
 	raw?: string;
 	/** `provider/id` of the model that produced a classifier verdict. */
 	model?: string;
+	/** The provider rejected the full classifier transcript as too long, not unsafe. */
+	transcriptTooLong?: true;
 }
 
 const SUBJECT_LIMIT = 300;

package/extensions/auto-mode/defaults.ts

@@ -3,7 +3,7 @@
  *
  * The ruleset itself is no longer configurable prose lists — the classifier
  * ruleset is a fixed monolith matching Claude Code's classifier (see
- * classifier-prompt.ts and docs/decisions/auto-mode.md). The one customization
+ * classifier-prompt.ts and working-docs/decisions/auto-mode.md). The one customization
  * surface Claude Code exposes, and the only one we expose, is the `## Environment` section:
  * `DEFAULT_ENVIRONMENT` is CC's default slot text, and a user's `autoMode.environment`
  * entries replace it. Re-exported here so config.ts has a single stable import

package/extensions/auto-mode/denials.ts

@@ -0,0 +1,123 @@
+/**
+ * Calls the auto-mode classifier denied this session, and the one-shot grants
+ * the user mints by approving them in `/permissions` (pure).
+ *
+ * Claude Code records every classifier denial (newest first, at most 20) for
+ * its "Recently denied" tab, keyed by tool and exact input. Approving one there
+ * writes no rule and bypasses nothing: the model is told it may retry, and the
+ * retry goes through the classifier again (findings §33). One Code's classifier
+ * takes user intent only from the user's own typed input, so a retry would
+ * most likely be blocked again. Here an approval instead mints a grant for that
+ * exact tool and input: the next call that matches it skips the classifier
+ * once, then the grant is spent. It carries the authority of answering "Yes"
+ * once on a permission prompt, and no more: a changed command, another
+ * directory or a second run is judged as usual, and deny rules and the safety
+ * floor are checked before any grant (working-docs/decisions/auto-mode.md,
+ * "Approving a denied call").
+ *
+ * The store lives in the permissions extension's memory for one session. It is
+ * never persisted, and a new session starts empty.
+ */
+
+/** Claude Code's `MAX_DENIALS`. */
+export const MAX_DENIALS = 20;
+
+export interface AutoModeDenial {
+	/** Unique within the store, so a panel row outlives list changes. */
+	id: number;
+	/** The normalized tool name (`bash`, `write`, `mcp__server__tool`). */
+	toolName: string;
+	/** What the user sees for the call: `bash(rm -rf dist)`, its subject clipped at 200 characters for the panel. */
+	display: string;
+	/** The same call unclipped, for the text the model reads (the grant message, the breadcrumb). */
+	fullDisplay: string;
+	/** The exact call (`denialInputKey`). */
+	inputKey: string;
+	/** The classifier's reason (a grounded rule name, or the failure it explained). */
+	reason: string;
+	/** The grounded rule name, when the verdict cited one. */
+	rule?: string;
+	timestamp: number;
+}
+
+/** JSON with object keys sorted at every level, so two spellings of one input agree. */
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			.filter(([, v]) => v !== undefined)
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+		return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableJson(v)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * The key a denial and its grant are matched by: the tool, the directory the
+ * call runs in, and its whole input. For a shell tool only the command counts,
+ * as in Claude Code (its `description` and `timeout` do not change what runs);
+ * for every other tool the whole input does. The directory is part of the key
+ * because the same command in another directory is another action.
+ */
+export function denialInputKey(toolName: string, input: Record<string, unknown>, cwd: string, shell: boolean): string {
+	const counted = shell ? { command: input.command } : input;
+	return `${toolName}\0${cwd}\0${stableJson(counted)}`;
+}
+
+export class DenialStore {
+	private denials: AutoModeDenial[] = [];
+	/** Unspent grants per exact call: two approved denials of one call allow two retries. */
+	private readonly grants = new Map<string, number>();
+	private nextId = 1;
+
+	/** Record a classifier denial, newest first, keeping the last `MAX_DENIALS`. */
+	record(denial: Omit<AutoModeDenial, "id">): AutoModeDenial {
+		const entry = { ...denial, id: this.nextId++ };
+		this.denials = [entry, ...this.denials].slice(0, MAX_DENIALS);
+		return entry;
+	}
+
+	/** Newest first. */
+	list(): readonly AutoModeDenial[] {
+		return this.denials;
+	}
+
+	/**
+	 * Approve denials by id: each leaves the list and mints a grant for its exact
+	 * call. Returns the approved entries, in list order; unknown ids are skipped.
+	 */
+	approve(ids: ReadonlySet<number>): AutoModeDenial[] {
+		const approved = this.denials.filter((denial) => ids.has(denial.id));
+		for (const denial of approved) this.grants.set(denial.inputKey, (this.grants.get(denial.inputKey) ?? 0) + 1);
+		this.denials = this.denials.filter((denial) => !ids.has(denial.id));
+		return approved;
+	}
+
+	/** Spend one grant for this exact call. True once per approval. */
+	takeGrant(inputKey: string): boolean {
+		const left = this.grants.get(inputKey);
+		if (!left) return false;
+		if (left === 1) this.grants.delete(inputKey);
+		else this.grants.set(inputKey, left - 1);
+		return true;
+	}
+
+	/** A call that went through another way drops its earlier denials (Claude Code does the same). */
+	settle(inputKey: string): void {
+		this.denials = this.denials.filter((denial) => denial.inputKey !== inputKey);
+	}
+
+	/** A new session starts with no denials and no grants. */
+	reset(): void {
+		this.denials = [];
+		this.grants.clear();
+	}
+}
+
+/**
+ * The message the model gets when the user approves denials in `/permissions`:
+ * Claude Code's wording, verbatim (findings §33).
+ */
+export function permissionGrantedMessage(displays: readonly string[]): string {
+	return `Permission granted for: ${displays.join(", ")}. You may now retry ${displays.length === 1 ? "this command" : "these commands"} if you would like.`;
+}

package/extensions/auto-mode/git-checkout-programs.ts

@@ -0,0 +1,187 @@
+/**
+ * Whether a checkout's own git configuration makes a read-only git command run
+ * a program (pure apart from fs reads).
+ *
+ * The pre-gate fast-paths `git status`, `diff`, `log` and the other read-only
+ * subcommands by their options (read-only-options.ts). git honours the
+ * repository's `.git/config`, and some keys there name a program that those
+ * reads run: `core.fsmonitor` on every index read, a `filter.<driver>.clean`
+ * when `status` re-hashes a file, `diff.external` and the diff and textconv
+ * drivers on `diff`/`log -p`/`show`, `gpg.program` on `log --show-signature`
+ * or a `%G?` format, a pager. `status` also rewrites the index opportunistically,
+ * which runs a `post-index-change` hook. A directory whose `.git` came from an
+ * archive, a synced folder or a copied tree can carry any of these, so a git
+ * read there is not provably read-only and goes to the classifier (PR #8
+ * review; SECURITY-REVIEW-2026-09-23's folder-trust residual).
+ *
+ * Only repository-scoped files are read: the checkout's `config`, its
+ * `config.worktree`, every submodule's config, and the hooks
+ * directories (`core.hooksPath` included). The user's own global and system
+ * configuration is theirs, and git-lfs's standard filter commands pass. The
+ * scan is textual and wide on purpose: an unneeded escalation costs one
+ * classifier call, a missed key would be code execution behind a "safe", so
+ * anything it cannot read counts as a program too.
+ */
+
+import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { findGitRoot, gitdirFileTarget } from "../lib/git.ts";
+import { expandTilde } from "../lib/paths.ts";
+
+const BOOLEAN = /^(true|false|yes|no|on|off|1|0)?$/i;
+
+/** git-lfs's own filter commands (`git lfs install`), resolved on the user's PATH. */
+const LFS_FILTERS = new Set(["git-lfs clean -- %f", "git-lfs smudge -- %f", "git-lfs filter-process"]);
+
+/** Keys whose value git runs during a read, by section (subsections included). */
+const PROGRAM_KEYS: Record<string, (key: string, value: string | undefined) => boolean> = {
+	// `core.fsmonitor=true` is git's own daemon; any other value is a hook command.
+	core: (key, value) => (key === "fsmonitor" && !BOOLEAN.test(value ?? "")) || key === "pager",
+	diff: (key) => key === "external" || key === "command" || key === "textconv",
+	filter: (key, value) => (key === "clean" || key === "smudge" || key === "process") && !LFS_FILTERS.has(value ?? ""),
+	pager: (_key, value) => !BOOLEAN.test(value ?? ""),
+	gpg: (key) => key === "program",
+	// An included file is not followed; it could hold any of the above.
+	include: (key) => key === "path",
+	includeif: (key) => key === "path",
+};
+
+/** One git config file's entries, section names lowercased without their subsection. */
+function configEntries(text: string): { section: string; key: string; value: string | undefined }[] {
+	const entries: { section: string; key: string; value: string | undefined }[] = [];
+	let section = "";
+	for (const raw of text.split(/\r?\n/)) {
+		let line = raw.trim();
+		const header = /^\[\s*([A-Za-z0-9.-]+)(?:\s+"(?:[^"\\]|\\.)*")?\s*\]/.exec(line);
+		if (header) {
+			// `[diff "x"]` and the old `[diff.x]` spelling both name section `diff`.
+			section = header[1].split(".")[0].toLowerCase();
+			line = line.slice(header[0].length).trim();
+		}
+		if (!line || line.startsWith("#") || line.startsWith(";")) continue;
+		const entry = /^([A-Za-z][A-Za-z0-9-]*)\s*(?:=\s*(.*))?$/.exec(line);
+		if (entry) entries.push({ section, key: entry[1].toLowerCase(), value: entry[2]?.trim().replace(/^"(.*)"$/, "$1") });
+	}
+	return entries;
+}
+
+/**
+ * What one git config file's text names: the first program-valued key, as
+ * `section.key`, and every `core.hooksPath`. A hooks path is not a program by
+ * itself (husky sets one); the caller looks there for the hook a read runs.
+ */
+export function configRunsProgram(text: string): { program?: string; hooksPaths: string[] } {
+	const hooksPaths: string[] = [];
+	for (const { section, key, value } of configEntries(text)) {
+		if (section === "core" && key === "hookspath" && value) hooksPaths.push(value);
+		else if (PROGRAM_KEYS[section]?.(key, value)) return { program: `${section}.${key}`, hooksPaths };
+	}
+	return { hooksPaths };
+}
+
+/** The checkout holding `dir`: its worktree root, git dir and common dir, or undefined outside one. */
+function checkoutOf(dir: string): { root: string; gitDir: string; commonDir: string } | undefined {
+	const root = findGitRoot(dir);
+	if (!root) return undefined;
+	const gitDir = gitdirFileTarget(root) ?? join(root, ".git");
+	let commonDir = gitDir;
+	try {
+		const common = readFileSync(join(gitDir, "commondir"), "utf-8").trim();
+		if (common) commonDir = isAbsolute(common) ? common : resolve(gitDir, common);
+	} catch {
+		// Not a linked worktree: the git dir is the common dir.
+	}
+	return { root, gitDir, commonDir };
+}
+
+/** A missing file or directory, as opposed to one this process cannot read. */
+function isMissing(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException).code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+/**
+ * Every submodule git dir `status` can recurse into, or undefined when the
+ * search cannot finish (an unreadable directory, more than 200 repositories,
+ * nesting past 32 levels), which the caller treats as a program. Found two
+ * ways: the standard layout under `<commonDir>/modules` (a nested submodule's
+ * under its parent's own `modules/`; a slashed submodule name is a directory
+ * chain), and each `.gitmodules` path whose `.git` points somewhere else.
+ */
+function submoduleGitDirs(root: string, commonDir: string): string[] | undefined {
+	const found = new Set<string>();
+	const walk = (dir: string, depth: number): boolean => {
+		if (depth > 32) return false;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch (error) {
+			return isMissing(error);
+		}
+		if (entries.some((entry) => entry.name === "HEAD" || entry.name === "config")) {
+			found.add(dir);
+			return found.size <= 200 && walk(join(dir, "modules"), depth + 1);
+		}
+		return entries.every((entry) => !entry.isDirectory() || walk(join(dir, entry.name), depth + 1));
+	};
+	if (!walk(join(commonDir, "modules"), 0)) return undefined;
+	let gitmodules = "";
+	try {
+		gitmodules = readFileSync(join(root, ".gitmodules"), "utf-8");
+	} catch (error) {
+		if (!isMissing(error)) return undefined;
+	}
+	for (const { section, key, value } of configEntries(gitmodules)) {
+		if (section !== "submodule" || key !== "path" || !value) continue;
+		const worktree = resolve(root, value);
+		const dotGit = join(worktree, ".git");
+		const gitDir = gitdirFileTarget(worktree) ?? (existsSync(dotGit) ? dotGit : undefined);
+		if (gitDir) found.add(gitDir);
+		if (found.size > 200) return undefined;
+	}
+	return [...found];
+}
+
+/** The hooks a git read can run: `status` rewrites the index. */
+export const READ_HOOKS = ["post-index-change"] as const;
+
+/**
+ * Why a git command in `dir` could run a program the checkout names, or
+ * undefined when its repository-scoped configuration names none (or `dir` is
+ * in no checkout). `hooks` are the hook names the command can run; `home`
+ * expands a `~` hooks path.
+ */
+export function checkoutGitRunsProgram(dir: string, home: string, hooks: readonly string[] = READ_HOOKS): string | undefined {
+	const checkout = checkoutOf(dir);
+	if (!checkout) return undefined;
+	const { root, gitDir, commonDir } = checkout;
+	const modules = submoduleGitDirs(root, commonDir);
+	if (!modules) return "the checkout's submodules cannot all be read";
+	// `status` rewrites the index, which runs `post-index-change`; it recurses
+	// into submodules, each with its own hooks directory.
+	const hooksDirs = [join(commonDir, "hooks"), ...modules.map((module) => join(module, "hooks"))];
+	for (const file of new Set([join(commonDir, "config"), join(commonDir, "config.worktree"), join(gitDir, "config.worktree")])) {
+		const found = readConfig(file);
+		if (!found) return "the checkout's git config cannot be read";
+		if (found.program) return `the checkout's git config sets ${found.program}, which names a program git runs`;
+		for (const path of found.hooksPaths) hooksDirs.push(resolve(root, expandTilde(path, home)));
+	}
+	for (const module of modules) {
+		const found = readConfig(join(module, "config"));
+		// A submodule's relative hooks path is resolved against a worktree this check does not map.
+		if (!found || found.program || found.hooksPaths.length > 0) {
+			return `a submodule's git config ${found ? `sets ${found.program ?? "core.hookspath"}, which names a program git runs` : "cannot be read"}`;
+		}
+	}
+	const hook = hooks.find((name) => hooksDirs.some((dir) => existsSync(join(dir, name))));
+	return hook && `the checkout has a ${hook} hook, which git runs`;
+}
+
+/** What a config file names; empty when it does not exist, undefined when it cannot be read. */
+function readConfig(file: string): { program?: string; hooksPaths: string[] } | undefined {
+	try {
+		return configRunsProgram(readFileSync(file, "utf-8"));
+	} catch (error) {
+		return isMissing(error) ? { hooksPaths: [] } : undefined;
+	}
+}

package/extensions/auto-mode/git-status-meta.ts

@@ -0,0 +1,159 @@
+/**
+ * The auto-mode transcript's `{"meta":{"gitStatus":…}}` line (pure), in the
+ * Claude Code-compatible shape the ruleset describes.
+ *
+ * Before a shell command that can destroy uncommitted work, the harness runs
+ * `git status` itself and puts the result directly above that command in the
+ * classifier's `<transcript>`, so the classifier judges the tree's real state
+ * instead of presuming it dirty. The ruleset says how to read it ("A
+ * `gitStatus` of `{"clean":true}` clears the Irreversible Local Destruction
+ * presume-dirty for that command; staged/modified/untracked counts … confirm
+ * it"). A command qualifies when any pattern of a qualifying category
+ * (`GIT_STATUS_CATEGORIES`) matches it, `monitor` commands included.
+ */
+
+type Pattern = { pattern: RegExp; category: string };
+
+/** Bash command categories; `destructiveCategory` names a command by the first match. */
+const BASH_PATTERNS: Pattern[] = [
+	{ pattern: /\bgit\s+reset\s+--hard\b/, category: "git_reset_hard" },
+	{ pattern: /\bgit\s+push\b[^;&|\n]*[ \t](--force|--force-with-lease|-f)\b/, category: "git_force_push" },
+	{ pattern: /\bgit\s+clean\b(?![^;&|\n]*(?:-[a-zA-Z]*n|--dry-run))[^;&|\n]*-[a-zA-Z]*f/, category: "git_clean_force" },
+	{ pattern: /\bgit\s+checkout\s+(--\s+)?\.[ \t]*($|[;&|\n])/, category: "git_checkout_dot" },
+	{ pattern: /\bgit\s+restore\s+(--\s+)?\.[ \t]*($|[;&|\n])/, category: "git_restore_dot" },
+	{ pattern: /\bgit\s+stash[ \t]+(drop|clear)\b/, category: "git_stash_drop" },
+	{ pattern: /\bgit\s+branch\s+(-D[ \t]|--delete\s+--force|--force\s+--delete)\b/, category: "git_branch_force_delete" },
+	{ pattern: /\bgit\s+(commit|push|merge)\b[^;&|\n]*--no-verify\b/, category: "git_no_verify" },
+	{ pattern: /\bgit\s+commit\b[^;&|\n]*--amend\b/, category: "git_commit_amend" },
+	{
+		pattern: /(^|[;&|\n][ \t]*)rm\s+-[a-zA-Z]*[rR][a-zA-Z]*f|(^|[;&|\n][ \t]*)rm\s+-[a-zA-Z]*f[a-zA-Z]*[rR]/,
+		category: "rm_recursive_force",
+	},
+	{ pattern: /(^|[;&|\n][ \t]*)rm\s+-[a-zA-Z]*[rR]/, category: "rm_recursive" },
+	{ pattern: /(^|[;&|\n][ \t]*)rm\s+-[a-zA-Z]*f/, category: "rm_force" },
+	{ pattern: /\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, category: "sql_drop_truncate" },
+	{ pattern: /\bDELETE\s+FROM\s+\w+[ \t]*(;|"|'|\n|$)/i, category: "sql_delete_from" },
+	{ pattern: /\bkubectl\s+delete\b/, category: "kubectl_delete" },
+	{ pattern: /\bterraform\s+destroy\b/, category: "terraform_destroy" },
+];
+
+const REMOVE = "(?:^|[|;&\\n({])[ \\t]*(Remove-Item|rm|del|rd|rmdir|ri)\\b[^|;&\\n}]*";
+
+/** PowerShell command categories, in the same first-match order. */
+const POWERSHELL_PATTERNS: Pattern[] = [
+	{ pattern: new RegExp(`${REMOVE}-Recurse\\b[^|;&\\n}]*-Force\\b`, "i"), category: "remove_item_recursive_force" },
+	{ pattern: new RegExp(`${REMOVE}-Force\\b[^|;&\\n}]*-Recurse\\b`, "i"), category: "remove_item_recursive_force" },
+	{ pattern: new RegExp(`${REMOVE}-Recurse\\b`, "i"), category: "remove_item_recursive" },
+	{ pattern: new RegExp(`${REMOVE}-Force\\b`, "i"), category: "remove_item_force" },
+	{ pattern: /\bClear-Content\b[^|;&\n]*\*/i, category: "clear_content_glob" },
+	{ pattern: /\bFormat-Volume\b/i, category: "format_volume" },
+	{ pattern: /\bClear-Disk\b/i, category: "clear_disk" },
+	{ pattern: /\bgit\s+reset\s+--hard\b/i, category: "git_reset_hard" },
+	{ pattern: /\bgit\s+push\b[^|;&\n]*\s+(--force|--force-with-lease|-f)\b/i, category: "git_force_push" },
+	{ pattern: /\bgit\s+clean\b(?![^|;&\n]*(?:-[a-zA-Z]*n|--dry-run))[^|;&\n]*-[a-zA-Z]*f/i, category: "git_clean_force" },
+	{ pattern: /\bgit\s+stash\s+(drop|clear)\b/i, category: "git_stash_drop" },
+	{ pattern: /\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, category: "sql_drop_truncate" },
+	{ pattern: /\bStop-Computer\b/i, category: "stop_computer" },
+	{ pattern: /\bRestart-Computer\b/i, category: "restart_computer" },
+	{ pattern: /\bClear-RecycleBin\b/i, category: "clear_recycle_bin" },
+];
+
+/** The categories that get a gitStatus line: the ones that can destroy uncommitted work. */
+export const GIT_STATUS_CATEGORIES: ReadonlySet<string> = new Set([
+	"git_reset_hard",
+	"git_checkout_dot",
+	"git_restore_dot",
+	"git_clean_force",
+	"rm_recursive_force",
+	"rm_recursive",
+	"rm_force",
+	"remove_item_recursive_force",
+	"remove_item_recursive",
+	"remove_item_force",
+	"clear_content_glob",
+]);
+
+/** The destructive category of a shell command (first match, first 10,000 characters), or undefined. */
+export function destructiveCategory(tool: "bash" | "powershell", command: string): string | undefined {
+	const text = command.length > 10_000 ? command.slice(0, 10_000) : command;
+	const patterns = tool === "powershell" ? POWERSHELL_PATTERNS : BASH_PATTERNS;
+	return patterns.find(({ pattern }) => pattern.test(text))?.category;
+}
+
+/** The categories of every pattern this command matches (first 10,000 characters). */
+function matchedCategories(tool: "bash" | "powershell", command: string): { text: string; categories: string[] } {
+	const text = command.length > 10_000 ? command.slice(0, 10_000) : command;
+	const patterns = tool === "powershell" ? POWERSHELL_PATTERNS : BASH_PATTERNS;
+	return { text, categories: patterns.filter(({ pattern }) => pattern.test(text)).map(({ category }) => category) };
+}
+
+/**
+ * Whether this shell command gets a gitStatus line above it in the transcript.
+ * Any qualifying pattern counts, not only the first match, so `git push
+ * --force x && rm -rf y` gets the line for its `rm -rf`: the line only ever
+ * adds ground truth.
+ */
+export function wantsGitStatusMeta(tool: "bash" | "powershell", command: string): boolean {
+	return matchedCategories(tool, command).categories.some((category) => GIT_STATUS_CATEGORIES.has(category));
+}
+
+/** `git clean` deletes ignored files only with `-x`/`-X`. */
+const GIT_CLEAN_IGNORED = /\bgit\s+clean\b[^;&|\n]*[ \t]-[a-zA-Z]*[xX]/i;
+
+/**
+ * Whether this shell command can delete ignored files (`.env`, local builds),
+ * which `git status` hides and git cannot restore. Every non-git removal
+ * category can; of the git ones, only a `git clean -x`/`-X`.
+ */
+export function reachesIgnoredFiles(tool: "bash" | "powershell", command: string): boolean {
+	const { text, categories } = matchedCategories(tool, command);
+	return categories.some((category) =>
+		category === "git_clean_force" ? GIT_CLEAN_IGNORED.test(text) : GIT_STATUS_CATEGORIES.has(category) && !category.startsWith("git_"),
+	);
+}
+
+/**
+ * The `git status` arguments for the line (the harness adds its own `-c`
+ * hardening), wider than Claude Code's `--ignore-submodules=dirty` (PR #8
+ * review). A dirty submodule always counts as modified: `rm -rf` deletes its
+ * work, and `git reset --hard --recurse-submodules` (or `submodule.recurse`,
+ * which the command line does not show) discards it. Ignored entries (`!!`,
+ * one per ignored directory) are listed only for a command that deletes them
+ * (`reachesIgnoredFiles`), so the line can withhold `{"clean":true}` there
+ * and keep it for a `git reset --hard` in a repo with an ignored `.env`.
+ */
+export function gitStatusMetaArgs(reachesIgnored: boolean): readonly string[] {
+	const args = ["status", "--porcelain", "--ignore-submodules=none", "--untracked-files=normal"];
+	return reachesIgnored ? [...args, "--ignored=matching"] : args;
+}
+
+/** The line's gitStatus value: `{clean: true}`, or the tree's counts. */
+export type GitStatusMeta = { clean: true } | { staged: number; modified: number; untracked: number };
+
+/**
+ * Summarize `git status --porcelain` output as clean, or staged/modified/untracked
+ * counts. Undefined (no line: the classifier keeps presuming dirty) when only
+ * ignored entries remain, which the wider `gitStatusMetaArgs` list.
+ */
+export function gitStatusMeta(porcelain: string): GitStatusMeta | undefined {
+	let staged = 0;
+	let modified = 0;
+	let untracked = 0;
+	let ignored = 0;
+	for (const line of porcelain.split("\n")) {
+		if (line.length < 2) continue;
+		const [index, worktree] = [line[0], line[1]];
+		if (index === "?" && worktree === "?") {
+			untracked++;
+			continue;
+		}
+		if (index === "!" && worktree === "!") {
+			ignored++;
+			continue;
+		}
+		if (index !== " " && index !== "?") staged++;
+		if (worktree !== " ") modified++;
+	}
+	if (staged !== 0 || modified !== 0 || untracked !== 0) return { staged, modified, untracked };
+	return ignored > 0 ? undefined : { clean: true };
+}