@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/resources/skills/marketplace.ts

@@ -0,0 +1,255 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { clioConfigDir } from "../../../core/xdg.js";
+import {
+	type InstallSkillInput,
+	type InstallSkillResult,
+	installSkillFromSource,
+	isSkillName,
+	parseSkillSourceSpec,
+} from "./install.js";
+import { loadSkills, type Skill } from "./loader.js";
+
+/**
+ * Local skill marketplace. Entries come from two real sources only:
+ *
+ *  1. A catalog directory of actual SKILL.md packages (for example the
+ *     repo-level skills/ folder, or CLIO_CODER_SKILL_CATALOG_DIR). Metadata is read
+ *     from the packages themselves via the normal skill loader.
+ *  2. A JSON index file (CLIO_CODER_SKILL_MARKETPLACE_INDEX or
+ *     <config>/skill-marketplace.json) whose entries point at installable
+ *     sources.
+ *
+ * There is no synthetic or hardcoded marketplace data; an empty result means
+ * no marketplace is configured.
+ */
+
+export type MarketplaceSkillOrigin = "catalog" | "index";
+
+/**
+ * The diagnostic that means "nothing is wrong, nothing is configured". Callers
+ * that render an empty state of their own separate it from real failures (an
+ * unreadable index, a broken package) by identity rather than by string match.
+ */
+export const MARKETPLACE_UNCONFIGURED = "no local skill marketplace catalog or index configured";
+
+export interface MarketplaceSkill {
+	name: string;
+	description: string;
+	/** Local path or URL accepted by `clio-coder skills install`. */
+	sourceUrl: string;
+	version?: string;
+	audit?: "pass" | "warn" | "fail" | "unknown";
+	/** Catalog grouping ("git", "research", ...); absent in a flat catalog. */
+	category?: string;
+	origin: MarketplaceSkillOrigin;
+}
+
+export type MarketplaceStatus = "installed" | "installable" | "unavailable";
+
+export interface MarketplaceDiscoveryResult {
+	status: MarketplaceStatus;
+	skills: MarketplaceSkill[];
+	diagnostics: string[];
+}
+
+export interface DiscoverMarketplaceOptions {
+	/** Working directory used to find a repo-level skills/ catalog. */
+	cwd?: string;
+	/** Override the JSON index path; null disables the JSON index source. */
+	indexPath?: string | null;
+	/** Override the catalog directory; null disables catalog discovery. */
+	catalogDir?: string | null;
+}
+
+function defaultIndexPath(): string | null {
+	try {
+		return path.join(clioConfigDir(), "skill-marketplace.json");
+	} catch {
+		return null;
+	}
+}
+
+function isIndexSkill(value: unknown): value is { name: string; description: string; sourceUrl: string } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.name === "string" &&
+		record.name.trim().length > 0 &&
+		typeof record.description === "string" &&
+		typeof record.sourceUrl === "string" &&
+		record.sourceUrl.trim().length > 0
+	);
+}
+
+function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function indexAudit(value: unknown): MarketplaceSkill["audit"] {
+	return value === "pass" || value === "warn" || value === "fail" || value === "unknown" ? value : undefined;
+}
+
+function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill[] {
+	try {
+		const parsed = JSON.parse(readFileSync(indexPath, "utf8")) as unknown;
+		const rawSkills = Array.isArray(parsed)
+			? parsed
+			: parsed && typeof parsed === "object" && Array.isArray((parsed as { skills?: unknown }).skills)
+				? (parsed as { skills: unknown[] }).skills
+				: [];
+		return rawSkills.filter(isIndexSkill).map((skill) => {
+			const record = skill as unknown as Record<string, unknown>;
+			// Version, audit and category are published by `npm run skills:pin`.
+			// They are advisory display metadata; an index entry stays installable
+			// without them, which is why only name/description/sourceUrl gate.
+			const version = optionalString(record.version);
+			const audit = indexAudit(record.audit);
+			const category = optionalString(record.category);
+			return {
+				name: skill.name.trim(),
+				description: skill.description.trim(),
+				sourceUrl: skill.sourceUrl.trim(),
+				...(version ? { version } : {}),
+				...(audit ? { audit } : {}),
+				...(category ? { category } : {}),
+				origin: "index" as const,
+			};
+		});
+	} catch (err) {
+		diagnostics.push(`skill marketplace index unreadable: ${err instanceof Error ? err.message : String(err)}`);
+		return [];
+	}
+}
+
+/**
+ * True when the directory contains a <pkg>/SKILL.md either immediately (flat
+ * catalog) or one category folder down (grouped catalog, e.g.
+ * skills/git/ship/SKILL.md). The loader itself recurses arbitrarily;
+ * this probe only decides whether a repo-level skills/ folder is a catalog.
+ */
+function looksLikeSkillCatalog(dir: string): boolean {
+	if (!existsSync(dir)) return false;
+	try {
+		return readdirSync(dir, { withFileTypes: true }).some((entry) => {
+			if (!entry.isDirectory()) return false;
+			const child = path.join(dir, entry.name);
+			if (existsSync(path.join(child, "SKILL.md"))) return true;
+			try {
+				return readdirSync(child, { withFileTypes: true }).some(
+					(inner) => inner.isDirectory() && existsSync(path.join(child, inner.name, "SKILL.md")),
+				);
+			} catch {
+				return false;
+			}
+		});
+	} catch {
+		return false;
+	}
+}
+
+function resolveCatalogDir(options: DiscoverMarketplaceOptions): string | null {
+	if (options.catalogDir === null) return null;
+	if (options.catalogDir) return path.resolve(options.catalogDir);
+	const fromEnv = process.env.CLIO_CODER_SKILL_CATALOG_DIR;
+	if (fromEnv && fromEnv.trim().length > 0) return path.resolve(fromEnv.trim());
+	const repoCatalog = path.join(options.cwd ?? process.cwd(), "skills");
+	return looksLikeSkillCatalog(repoCatalog) ? repoCatalog : null;
+}
+
+/**
+ * The catalog folder a package sits in, which is the grouping `--category`
+ * installs by. A flat catalog has none, and a package outside the catalog dir
+ * (which `path.relative` reports with a leading "..") is not grouped by it.
+ */
+function catalogCategory(catalogDir: string, baseDir: string): string | undefined {
+	const rel = path.relative(catalogDir, baseDir);
+	const category = path.dirname(rel);
+	if (rel.length === 0 || rel.startsWith("..") || category === "." || category.startsWith("..")) return undefined;
+	return category;
+}
+
+function catalogEntry(skill: Skill, catalogDir: string): MarketplaceSkill {
+	const version = typeof skill.metadata.version === "string" ? skill.metadata.version : undefined;
+	const category = catalogCategory(catalogDir, skill.baseDir);
+	return {
+		name: skill.name,
+		description: skill.description,
+		sourceUrl: skill.baseDir,
+		...(version ? { version } : {}),
+		...(skill.provenance?.audit ? { audit: skill.provenance.audit } : {}),
+		...(category ? { category } : {}),
+		origin: "catalog",
+	};
+}
+
+function catalogSkills(dir: string, diagnostics: string[]): MarketplaceSkill[] {
+	const list = loadSkills({ disableDiscovery: true, explicitSkillPaths: [dir] });
+	for (const diag of list.diagnostics) {
+		if (diag.type === "warning" || diag.type === "error") diagnostics.push(diag.message);
+	}
+	return list.items.map((skill) => catalogEntry(skill, dir));
+}
+
+export function discoverMarketplaceSkills(options: DiscoverMarketplaceOptions = {}): MarketplaceDiscoveryResult {
+	const diagnostics: string[] = [];
+	const skills: MarketplaceSkill[] = [];
+	const seen = new Set<string>();
+
+	// Catalog packages first: real local files beat index pointers on name collisions.
+	const catalogDir = resolveCatalogDir(options);
+	if (catalogDir) {
+		for (const skill of catalogSkills(catalogDir, diagnostics)) {
+			if (seen.has(skill.name)) continue;
+			seen.add(skill.name);
+			skills.push(skill);
+		}
+	}
+
+	const indexPath =
+		options.indexPath === null ? null : (options.indexPath ?? process.env.CLIO_CODER_SKILL_MARKETPLACE_INDEX ?? null);
+	const resolvedIndexPath = indexPath ?? defaultIndexPath();
+	if (options.indexPath !== null && resolvedIndexPath && existsSync(resolvedIndexPath)) {
+		for (const skill of indexSkills(resolvedIndexPath, diagnostics)) {
+			if (seen.has(skill.name)) continue;
+			seen.add(skill.name);
+			skills.push(skill);
+		}
+	}
+
+	if (skills.length === 0 && diagnostics.length === 0) {
+		diagnostics.push(MARKETPLACE_UNCONFIGURED);
+	}
+	return { status: skills.length > 0 ? "installable" : "unavailable", skills, diagnostics };
+}
+
+export function getMarketplaceSkills(options: DiscoverMarketplaceOptions = {}): MarketplaceSkill[] {
+	return discoverMarketplaceSkills(options).skills;
+}
+
+/**
+ * The single install entry point for every frontend (headless CLI, TUI
+ * pending-skill prompt, skills hub). Source resolution, in precedence order:
+ *
+ *  1. A GitHub URL installs directly.
+ *  2. An existing local path installs directly; paths always beat same-named
+ *     marketplace entries.
+ *  3. A bare skill name resolves through the local marketplace.
+ *
+ * Anything else is an error naming both failed interpretations. Overwriting
+ * an existing install always requires an explicit `force: true`.
+ */
+export function installSkill(input: InstallSkillInput): InstallSkillResult {
+	const source = input.source.trim();
+	const spec = parseSkillSourceSpec(source);
+	if (spec?.kind === "local" && isSkillName(source) && !existsSync(spec.path)) {
+		const skill = getMarketplaceSkills({ ...(input.cwd ? { cwd: input.cwd } : {}) }).find(
+			(entry) => entry.name === source,
+		);
+		if (!skill) {
+			throw new Error(`"${source}" is neither an existing local path nor available in the local marketplace`);
+		}
+		return installSkillFromSource({ ...input, source: skill.sourceUrl });
+	}
+	return installSkillFromSource(input);
+}

package/src/domains/resources/skills/provenance-pin.ts

@@ -0,0 +1,115 @@
+/**
+ * Local-first skill provenance pinning.
+ *
+ * `skills/registry.yaml` (regenerated with `npm run skills:pin`) pins the
+ * provenance-stripped sha256 of every marketplace skill's SKILL.md. At
+ * activation time, a skill carrying marketplace provenance (`registry-id`
+ * frontmatter) is compared against the pinned entry on the same normalized
+ * hash, so install-lifecycle stamps (`installed-at`, `installed-hash`, ...)
+ * never read as drift while any content or registry-identity edit does. A
+ * mismatch means the installed content drifted from its audited form. Drift
+ * never blocks; skills still pass through the normal tool safety gates. No
+ * network, no remote registry, no signing; this is hash comparison against a
+ * local manifest.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+
+export const SKILL_PIN_MANIFEST_FILENAME = "registry.yaml";
+
+export interface SkillPinEntry {
+	name: string;
+	version: string | null;
+	sha256: string;
+}
+
+export type SkillDriftVerdict = "match" | "mismatch";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Resolve the manifest path using the same catalog resolution as the marketplace. */
+function resolveSkillPinManifestPath(cwd: string): string | null {
+	const fromEnv = process.env.CLIO_CODER_SKILL_CATALOG_DIR;
+	const catalogDir = fromEnv && fromEnv.trim().length > 0 ? path.resolve(fromEnv.trim()) : path.join(cwd, "skills");
+	const manifestPath = path.join(catalogDir, SKILL_PIN_MANIFEST_FILENAME);
+	return existsSync(manifestPath) ? manifestPath : null;
+}
+
+function loadSkillPinManifest(manifestPath: string): Map<string, SkillPinEntry> | null {
+	let parsed: unknown;
+	try {
+		parsed = yaml.parse(readFileSync(manifestPath, "utf8"));
+	} catch {
+		return null;
+	}
+	if (!isPlainObject(parsed) || !Array.isArray(parsed.skills)) return null;
+	const entries = new Map<string, SkillPinEntry>();
+	for (const raw of parsed.skills) {
+		if (!isPlainObject(raw)) continue;
+		const name = typeof raw.name === "string" ? raw.name.trim() : "";
+		const sha256 = typeof raw.sha256 === "string" ? raw.sha256.trim().toLowerCase() : "";
+		if (name.length === 0 || !/^[0-9a-f]{64}$/.test(sha256)) continue;
+		entries.set(name, {
+			name,
+			version: typeof raw.version === "string" && raw.version.trim().length > 0 ? raw.version.trim() : null,
+			sha256,
+		});
+	}
+	return entries;
+}
+
+/** Which recorded hash the activated content was measured against. */
+export type SkillDriftAuthority = "pinned-manifest" | "install-record";
+
+export interface SkillDriftReport {
+	verdict: SkillDriftVerdict;
+	authority: SkillDriftAuthority;
+	/** The hash the content was compared against, for the operator's record. */
+	expected: string;
+}
+
+/**
+ * Compare an activated skill against whatever recorded hash can speak for it.
+ *
+ * Two independent authorities, tried in that order because they answer
+ * different questions. The pinned manifest says what the audited catalog
+ * entry's content is, so it wins wherever it has an entry. The skill's own
+ * `installed-hash` frontmatter says what this machine wrote at install time,
+ * which is the only evidence available for a skill installed straight from a
+ * URL, and it catches the case the manifest cannot see at all: content edited
+ * on disk after installation.
+ *
+ * Both compare on the provenance-stripped hash, so install-lifecycle stamps
+ * never read as drift while any content or registry-identity edit does. Null
+ * means nothing recorded a hash for this skill; drift evidence is opt-in and
+ * never a gate, and skills still pass the normal tool safety gates either way.
+ */
+export function checkSkillDrift(
+	skill: { name: string; normalizedHash: string; provenance?: { installedHash?: string } },
+	cwd: string,
+): SkillDriftReport | null {
+	const actual = skill.normalizedHash.toLowerCase();
+	const manifestPath = resolveSkillPinManifestPath(cwd);
+	const manifest = manifestPath === null ? null : loadSkillPinManifest(manifestPath);
+	const pinned = manifest?.get(skill.name);
+	if (pinned !== undefined) {
+		return {
+			verdict: pinned.sha256 === actual ? "match" : "mismatch",
+			authority: "pinned-manifest",
+			expected: pinned.sha256,
+		};
+	}
+	const recorded = skill.provenance?.installedHash?.trim().toLowerCase();
+	if (recorded !== undefined && /^[0-9a-f]{64}$/.test(recorded)) {
+		return {
+			verdict: recorded === actual ? "match" : "mismatch",
+			authority: "install-record",
+			expected: recorded,
+		};
+	}
+	return null;
+}

package/src/domains/safety/action-classifier.ts

@@ -0,0 +1,268 @@
+import path from "node:path";
+import { artifactDefaultPath } from "../../core/artifact-paths.js";
+import { canonicalizeExistingPath } from "../../core/path-canonical.js";
+import { ToolNames } from "../../core/tool-names.js";
+import { extractCommandCdTargets, extractCommandWriteTargets } from "./protected-artifacts.js";
+
+/**
+ * Deterministic action classifier for tool calls. Pure function, no I/O, no
+ * state. Slice 3 wires it into dispatch admission and audit. This module only
+ * owns the mapping from (tool, args) to an ActionClass.
+ */
+
+export type ActionClass = "read" | "write" | "execute" | "dispatch" | "system_modify" | "git_destructive" | "unknown";
+
+export interface ClassifierCall {
+	tool: string;
+	args?: Record<string, unknown>;
+}
+
+export interface Classification {
+	actionClass: ActionClass;
+	reasons: ReadonlyArray<string>;
+}
+
+interface NamedPattern {
+	name: string;
+	re: RegExp;
+}
+
+const GIT_DESTRUCTIVE_PATTERNS: ReadonlyArray<NamedPattern> = [
+	{ name: "git-push-force-long", re: /\bgit\s+push\s+--force\b/i },
+	{ name: "git-push-force-short", re: /\bgit\s+push\s+-f\b/i },
+	{ name: "git-reset-hard", re: /\bgit\s+reset\s+--hard\b/i },
+	{ name: "git-clean-fd", re: /\bgit\s+clean\s+-fd?\b/i },
+	{ name: "git-checkout-dot", re: /\bgit\s+checkout\s+--\s+\./i },
+	{ name: "git-branch-D", re: /\bgit\s+branch\s+-D\b/i },
+	{ name: "git-restore-source", re: /\bgit\s+restore\s+--source\b/i },
+];
+
+const SYSTEM_MODIFY_PATTERNS: ReadonlyArray<NamedPattern> = [
+	{ name: "sudo-or-doas", re: /\b(sudo|doas)\b/i },
+	// allow rm -rf /tmp/... and /var/tmp/... but flag everything else rooted at /
+	{ name: "rm-rf-root", re: /\brm\s+-rf?\s+\/(?!(tmp|var\/tmp)(?:\/|\s|$))/i },
+	{ name: "apt-install", re: /\bapt(-get)?\s+(install|remove|purge)/i },
+	{ name: "brew-install", re: /\bbrew\s+(install|uninstall|reinstall)/i },
+	{ name: "npm-install-global", re: /\bnpm\s+install\s+-g\b/i },
+	{ name: "pip-install", re: /\bpip\s+install\b/i },
+	{ name: "systemctl", re: /\bsystemctl\s+/i },
+	{ name: "chmod-root", re: /\bchmod\s+[0-7]{3,4}\s+\//i },
+	{ name: "chown", re: /\bchown\s+/i },
+];
+
+/**
+ * `/run` is here because path resolution canonicalizes symlinks: on every
+ * systemd distribution `/var/run` is a symlink to `/run` and `/var/lock` to
+ * `/run/lock`, so a write aimed at either landed on a path no prefix covered
+ * and escaped the system-root rule whenever the workspace happened to sit
+ * under it. Found while auditing the `/var` subdirectories for the carve-out
+ * below.
+ */
+const SYSTEM_WRITE_ROOT_PREFIXES: ReadonlyArray<string> = ["/etc", "/usr", "/var", "/bin", "/sbin", "/run"];
+
+/**
+ * Temp trees that sit under a protected root but are ordinary scratch space,
+ * not system state. `/var/tmp` is the FHS's persistent temp directory and
+ * `/var/folders` is macOS's per-user temp tree, and both are where an operator
+ * or a harness puts a throwaway workspace. Classifying them as system_modify
+ * made every mutating call from a workspace there require a confirmation, which
+ * headless runs answer with a denial: a `clio-coder run` in a `/var/tmp` sandbox
+ * could not write one byte, and the model's recovery was to report work it had
+ * not done. The exemption is a carve-out rather than an enumeration of the
+ * system directories under `/var` on purpose: `/var/log`, `/var/lib`,
+ * `/var/spool`, `/var/db` and every other subdirectory, including ones this
+ * list has never heard of, stay exactly as protected as before.
+ *
+ * `rm -rf` already reads the same line (SYSTEM_MODIFY_PATTERNS rm-rf-root
+ * exempts `/tmp` and `/var/tmp`), so the two checks now agree.
+ */
+const SYSTEM_WRITE_EXEMPT_PREFIXES: ReadonlyArray<string> = ["/var/tmp", "/var/folders"];
+
+function isUnderPrefix(abs: string, prefix: string): boolean {
+	return abs === prefix || abs.startsWith(`${prefix}/`);
+}
+
+function baseClassify(tool: string): ActionClass | null {
+	switch (tool) {
+		case ToolNames.Read:
+		case ToolNames.Grep:
+		case ToolNames.Find:
+		case ToolNames.Ls:
+		case ToolNames.WebFetch:
+		case ToolNames.Git:
+		case ToolNames.CodeNav:
+		case ToolNames.Context:
+		case ToolNames.Monitor:
+		case ToolNames.AskUser:
+		case ToolNames.CredentialPresent:
+		// tasks mutates only the session's task ledger, never the workspace,
+		// so it stays read class and is never gated behind a confirmation.
+		case ToolNames.Tasks:
+		// ledger posts a typed contribution to a coordination board and reads a
+		// local mirror. Neither touches the workspace, so it is never gated
+		// behind a confirmation.
+		case ToolNames.Ledger:
+			return "read";
+		case ToolNames.Write:
+		case ToolNames.Edit:
+		case ToolNames.Artifact:
+			return "write";
+		case ToolNames.Bash:
+		case ToolNames.Verify:
+			return "execute";
+		case ToolNames.Dispatch:
+		case ToolNames.Steer:
+			return "dispatch";
+		default:
+			return null;
+	}
+}
+
+function scanStringOf(args: Record<string, unknown> | undefined): string {
+	if (!args) return "";
+	const parts: string[] = [];
+	for (const value of Object.values(args)) {
+		if (value == null) continue;
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+			parts.push(String(value));
+		} else {
+			try {
+				parts.push(JSON.stringify(value));
+			} catch {
+				// ignore values that cannot be serialized
+			}
+		}
+	}
+	return parts.join(" ");
+}
+
+function matchFirst(patterns: ReadonlyArray<NamedPattern>, haystack: string): NamedPattern | null {
+	for (const p of patterns) {
+		if (p.re.test(haystack)) return p;
+	}
+	return null;
+}
+
+function resolveCandidate(p: string, baseCwd?: string): string {
+	// ~ expansion is not performed here; any ~-prefixed path is treated as an
+	// absolute user-home reference. We keep it as-is so the caller-visible
+	// string drives the escape check, and classify conservatively as modify.
+	if (p.startsWith("~")) return p;
+	const base = canonicalizeExistingPath(path.resolve(baseCwd ?? process.cwd()));
+	const resolved = path.isAbsolute(p) ? path.resolve(p) : path.resolve(base, p);
+	return canonicalizeExistingPath(resolved);
+}
+
+function isInsideCwd(abs: string): boolean {
+	const cwd = canonicalizeExistingPath(path.resolve(process.cwd()));
+	const candidate = canonicalizeExistingPath(abs);
+	const rel = path.relative(cwd, candidate);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+function writePathClass(pathArg: string, baseCwd?: string): { cls: "system_modify" | "write"; reason?: string } {
+	if (pathArg.startsWith("~")) {
+		return { cls: "system_modify", reason: `write-path-home-escape: ${pathArg}` };
+	}
+	const abs = resolveCandidate(pathArg, baseCwd);
+	const exempt = SYSTEM_WRITE_EXEMPT_PREFIXES.some((prefix) => isUnderPrefix(abs, prefix));
+	if (!exempt) {
+		for (const prefix of SYSTEM_WRITE_ROOT_PREFIXES) {
+			if (isUnderPrefix(abs, prefix)) {
+				return { cls: "system_modify", reason: `write-path-system-root: ${prefix}` };
+			}
+		}
+	}
+	if (!isInsideCwd(abs)) {
+		return { cls: "system_modify", reason: `write-path-outside-cwd: ${abs}` };
+	}
+	return { cls: "write" };
+}
+
+/**
+ * The artifact tool writes a default file name when the call names no path, so
+ * a classifier that only reads the path argument saw no target at all and
+ * returned plain write for a call that writes into whatever the cwd is. The
+ * live evidence: in a `/var/tmp` workspace where write, edit and every bash
+ * redirect were refused as system_modify, `artifact(kind:"report")` wrote a
+ * report into that same directory. The default now resolves through
+ * core/artifact-paths.ts, the one place the tool, the write-root check, and the
+ * protected-artifacts guard all read, so the four can never disagree.
+ */
+function extractWritePath(tool: string, args: Record<string, unknown> | undefined): string | null {
+	const candidate = args?.path ?? args?.file_path ?? args?.filePath;
+	if (typeof candidate === "string" && candidate.length > 0) return candidate;
+	return tool === ToolNames.Artifact ? artifactDefaultPath(args?.kind) : null;
+}
+
+export function classify(call: ClassifierCall): Classification {
+	const base = baseClassify(call.tool);
+	if (base === null) {
+		return { actionClass: "unknown", reasons: [`unknown tool: ${call.tool}`] };
+	}
+
+	const reasons: string[] = [];
+
+	if (call.tool === ToolNames.Bash) {
+		const scan = scanStringOf(call.args);
+		const gitHit = matchFirst(GIT_DESTRUCTIVE_PATTERNS, scan);
+		if (gitHit) {
+			return { actionClass: "git_destructive", reasons: [`pattern:${gitHit.name}`] };
+		}
+		const sysHit = matchFirst(SYSTEM_MODIFY_PATTERNS, scan);
+		if (sysHit) {
+			return { actionClass: "system_modify", reasons: [`pattern:${sysHit.name}`] };
+		}
+		// Apply the same path-class gate we use for the write tool to every
+		// shell write-target the command exposes (redirects, tee, cp/mv
+		// destinations). Without this the model can dodge the write tool's
+		// confirmation gate by emitting `echo X > /tmp/foo.txt` after the user
+		// cancels the original write call. Relative write targets are
+		// resolved against the bash call's explicit cwd argument when
+		// supplied so a model cannot launder a write outside the workspace
+		// by combining a relative redirect with a cwd outside the workspace.
+		const command = typeof call.args?.command === "string" ? call.args.command : null;
+		const argCwd = typeof call.args?.cwd === "string" && call.args.cwd.length > 0 ? call.args.cwd : undefined;
+		if (command !== null) {
+			const targetReasons: string[] = [];
+			for (const target of extractCommandWriteTargets(command)) {
+				const decision = writePathClass(target, argCwd);
+				if (decision.cls === "system_modify") {
+					targetReasons.push(decision.reason ?? `bash-write-target: ${target}`);
+				}
+			}
+			// A `cd` outside the workspace re-bases every relative path after it,
+			// so static write-target extraction stops describing what the command
+			// touches. Escalate through the same system_modify confirm gate as an
+			// out-of-workspace write target; inside-workspace `cd` stays plain
+			// execute.
+			for (const target of extractCommandCdTargets(command)) {
+				if (target.startsWith("~")) {
+					targetReasons.push(`bash-cd-home-escape: ${target}`);
+					continue;
+				}
+				const abs = resolveCandidate(target, argCwd);
+				if (!isInsideCwd(abs)) {
+					targetReasons.push(`bash-cd-outside-workspace: ${abs}`);
+				}
+			}
+			if (targetReasons.length > 0) {
+				return { actionClass: "system_modify", reasons: targetReasons };
+			}
+		}
+		return { actionClass: "execute", reasons };
+	}
+
+	if (base === "write") {
+		const pathArg = extractWritePath(call.tool, call.args);
+		if (pathArg) {
+			const decision = writePathClass(pathArg);
+			if (decision.cls === "system_modify") {
+				return { actionClass: "system_modify", reasons: decision.reason ? [decision.reason] : [] };
+			}
+		}
+		return { actionClass: "write", reasons };
+	}
+
+	return { actionClass: base, reasons };
+}

package/src/domains/safety/approval-axis.ts

@@ -0,0 +1,23 @@
+import type { AutonomyLevel } from "./autonomy.js";
+import type { SafetyDecision } from "./contract.js";
+
+/**
+ * Which axis produced an `ask`: a safety-net rail demands confirmation at
+ * every level, while an autonomy ask exists only because of the current level.
+ */
+export type AskAxis = { kind: "autonomy" } | { kind: "net"; ruleId: string };
+
+export function askAxis(decision: SafetyDecision): AskAxis {
+	if (decision.kind === "ask") {
+		if (decision.match) return { kind: "net", ruleId: decision.match.ruleId };
+		if (decision.policy?.kind === "ask") {
+			return { kind: "net", ruleId: decision.policy.ruleId ?? decision.policy.reasonCode };
+		}
+	}
+	return { kind: "autonomy" };
+}
+
+export function approvalAxisId(decision: SafetyDecision, level: AutonomyLevel): string {
+	const axis = askAxis(decision);
+	return axis.kind === "net" ? `net:${axis.ruleId}` : `autonomy:${level}`;
+}