@f5-sales-demo/xcsh 19.101.0 → 19.101.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.101.0",
+	"version": "19.101.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.101.0",
-		"@f5-sales-demo/pi-agent-core": "19.101.0",
-		"@f5-sales-demo/pi-ai": "19.101.0",
-		"@f5-sales-demo/pi-natives": "19.101.0",
-		"@f5-sales-demo/pi-resource-management": "19.101.0",
-		"@f5-sales-demo/pi-tui": "19.101.0",
-		"@f5-sales-demo/pi-utils": "19.101.0",
+		"@f5-sales-demo/xcsh-stats": "19.101.2",
+		"@f5-sales-demo/pi-agent-core": "19.101.2",
+		"@f5-sales-demo/pi-ai": "19.101.2",
+		"@f5-sales-demo/pi-natives": "19.101.2",
+		"@f5-sales-demo/pi-resource-management": "19.101.2",
+		"@f5-sales-demo/pi-tui": "19.101.2",
+		"@f5-sales-demo/pi-utils": "19.101.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/generate-extension-capabilities.ts

@@ -20,55 +20,182 @@ const here = import.meta.dir; // packages/coding-agent/scripts
 const vendoredPath = path.resolve(here, "../src/browser/capabilities.json");
 const generatedPath = path.resolve(here, "../src/browser/capabilities.generated.ts");
 
-// Co-build refresh: prefer the sibling extension's freshly-built contract.
-const siblingPath =
-	process.env.XCSH_EXTENSION_CAPABILITIES ?? path.resolve(here, "../../../../xcsh-chrome-extension/capabilities.json");
-if (fs.existsSync(siblingPath) && path.resolve(siblingPath) !== vendoredPath) {
-	fs.copyFileSync(siblingPath, vendoredPath);
+// Guarded so the regression checks below can be imported by tests without regenerating files.
+// Importing this module used to run the whole generator as a side effect (#2578).
+if (import.meta.main) {
+	// Co-build refresh: adopt the sibling extension's freshly-built contract — but only when it really is
+	// fresher. "The directory exists" is not evidence of that, and treating it as evidence silently rewrote a
+	// committed contract from whatever happened to be on the developer's disk (#2578).
+	//
+	// Measured on a real machine: a sibling checkout left at contractVersion 1.8.0 overwrote the committed
+	// 1.12.0 and deleted the whole `handshake` feature block, on every `bun run check`, `bun test` and
+	// `bun run build`. `release.ts` runs `git commit -a`, so the downgrade was one release away from shipping.
+	// The guard applies to the path found by *proximity*, which is the accidental one. An explicitly set
+	// XCSH_EXTENSION_CAPABILITIES is a deliberate statement about which manifest to compile in — including a
+	// major-version co-build that removes tools on purpose — so it is honoured and merely announced.
+	const explicitPath = process.env.XCSH_EXTENSION_CAPABILITIES;
+	const siblingPath = explicitPath ?? path.resolve(here, "../../../../xcsh-chrome-extension/capabilities.json");
+	if (explicitPath !== undefined && fs.existsSync(explicitPath) && path.resolve(explicitPath) !== vendoredPath) {
+		console.log(`Adopting ${explicitPath} (XCSH_EXTENSION_CAPABILITIES set explicitly).`);
+		fs.copyFileSync(explicitPath, vendoredPath);
+	} else if (explicitPath === undefined && fs.existsSync(siblingPath) && path.resolve(siblingPath) !== vendoredPath) {
+		adoptSiblingIfNotARegression(siblingPath, vendoredPath);
+	}
+
+	const manifest = JSON.parse(fs.readFileSync(vendoredPath, "utf8")) as {
+		contractVersion: string;
+		tools: Array<{ name: string }>;
+	};
+	const toolNames = manifest.tools.map(t => t.name);
+
+	const output = [
+		"// Auto-generated by scripts/generate-extension-capabilities.ts - DO NOT EDIT",
+		"// Source: src/browser/capabilities.json (the Chrome extension's published contract).",
+		"",
+		"export interface ExtensionToolFlags {",
+		"\treadonly readOnly?: boolean;",
+		"\treadonly mutates?: boolean;",
+		"\treadonly requiresExplainMode?: boolean;",
+		"}",
+		"",
+		"export interface ExtensionToolDef {",
+		"\treadonly name: string;",
+		"\treadonly summary: string;",
+		"\treadonly category: string;",
+		"\treadonly params: Record<string, unknown>;",
+		"\treadonly flags?: ExtensionToolFlags;",
+		"}",
+		"",
+		"export interface ExtensionCapabilities {",
+		"\treadonly version: string;",
+		"\treadonly contractVersion: string;",
+		"\treadonly multiPortDiscovery?: boolean;",
+		"\treadonly protocol: string;",
+		"\treadonly tools: readonly ExtensionToolDef[];",
+		"\treadonly features: Record<string, unknown>;",
+		"}",
+		"",
+		`export const EXTENSION_CAPABILITIES: ExtensionCapabilities = ${JSON.stringify(manifest, null, "\t")};`,
+		"",
+		`export const EXTENSION_CONTRACT_VERSION = ${JSON.stringify(manifest.contractVersion)};`,
+		"",
+		`export const EXTENSION_TOOL_NAMES: readonly string[] = ${JSON.stringify(toolNames)};`,
+		"",
+	].join("\n");
+
+	await Bun.write(generatedPath, output);
+	console.log(
+		`Generated ${path.relative(process.cwd(), generatedPath)} (${toolNames.length} tools, contract ${manifest.contractVersion})`,
+	);
+}
+
+/** A capability manifest, as far as the regression check needs to understand one. */
+interface CapabilityManifest {
+	contractVersion?: string;
+	tools?: Array<{ name?: string }>;
+	features?: Record<string, unknown>;
+}
+
+/**
+ * Decide whether a sibling manifest may replace the committed one.
+ *
+ * Exported for tests. Returns the reason to refuse, or undefined when adoption is safe.
+ *
+ * Two independent guards, because they catch different mistakes:
+ *  - a lower `contractVersion` is a stale checkout, the case that actually happened;
+ *  - a missing tool or feature key at the same-or-higher version is a broken build, which a version
+ *    comparison alone would wave through.
+ */
+export function regressionReason(sibling: CapabilityManifest, vendored: CapabilityManifest): string | undefined {
+	const siblingVersion = sibling.contractVersion ?? "";
+	const vendoredVersion = vendored.contractVersion ?? "";
+	const versionOrder = compareContractVersions(siblingVersion, vendoredVersion);
+	if (versionOrder < 0) {
+		return `contractVersion would go backwards, ${vendoredVersion} -> ${siblingVersion}`;
+	}
+
+	const lostTools = missingKeys(
+		(vendored.tools ?? []).map(tool => tool.name ?? ""),
+		(sibling.tools ?? []).map(tool => tool.name ?? ""),
+	);
+	if (lostTools.length > 0) return `tools would be lost: ${lostTools.join(", ")}`;
+
+	const lostFeatures = missingKeys(Object.keys(vendored.features ?? {}), Object.keys(sibling.features ?? {}));
+	if (lostFeatures.length > 0) return `features would be lost: ${lostFeatures.join(", ")}`;
+
+	// Equal versions with different content mean one side changed without bumping, so the version says
+	// nothing about which is fresher. That is not hypothetical: a tool was once added while contractVersion
+	// stayed put, which is exactly how a stale same-version sibling could regress nested tool params or
+	// feature internals past a check that only compares names. Refuse and let the operator decide, via
+	// XCSH_EXTENSION_CAPABILITIES if they mean it.
+	if (versionOrder === 0 && !sameContent(sibling, vendored)) {
+		return `contractVersion is unchanged at ${vendoredVersion} but the content differs, so neither copy is provably fresher`;
+	}
+
+	return undefined;
 }
 
-const manifest = JSON.parse(fs.readFileSync(vendoredPath, "utf8")) as {
-	contractVersion: string;
-	tools: Array<{ name: string }>;
-};
-const toolNames = manifest.tools.map(t => t.name);
-
-const output = [
-	"// Auto-generated by scripts/generate-extension-capabilities.ts - DO NOT EDIT",
-	"// Source: src/browser/capabilities.json (the Chrome extension's published contract).",
-	"",
-	"export interface ExtensionToolFlags {",
-	"\treadonly readOnly?: boolean;",
-	"\treadonly mutates?: boolean;",
-	"\treadonly requiresExplainMode?: boolean;",
-	"}",
-	"",
-	"export interface ExtensionToolDef {",
-	"\treadonly name: string;",
-	"\treadonly summary: string;",
-	"\treadonly category: string;",
-	"\treadonly params: Record<string, unknown>;",
-	"\treadonly flags?: ExtensionToolFlags;",
-	"}",
-	"",
-	"export interface ExtensionCapabilities {",
-	"\treadonly version: string;",
-	"\treadonly contractVersion: string;",
-	"\treadonly multiPortDiscovery?: boolean;",
-	"\treadonly protocol: string;",
-	"\treadonly tools: readonly ExtensionToolDef[];",
-	"\treadonly features: Record<string, unknown>;",
-	"}",
-	"",
-	`export const EXTENSION_CAPABILITIES: ExtensionCapabilities = ${JSON.stringify(manifest, null, "\t")};`,
-	"",
-	`export const EXTENSION_CONTRACT_VERSION = ${JSON.stringify(manifest.contractVersion)};`,
-	"",
-	`export const EXTENSION_TOOL_NAMES: readonly string[] = ${JSON.stringify(toolNames)};`,
-	"",
-].join("\n");
-
-await Bun.write(generatedPath, output);
-console.log(
-	`Generated ${path.relative(process.cwd(), generatedPath)} (${toolNames.length} tools, contract ${manifest.contractVersion})`,
-);
+/**
+ * Whole-manifest equality, by canonical JSON.
+ *
+ * Deliberately not a deep field-by-field comparison: the question is only "are these the same document",
+ * and any difference at an equal version is enough to refuse.
+ */
+function sameContent(left: CapabilityManifest, right: CapabilityManifest): boolean {
+	return canonicalJson(left) === canonicalJson(right);
+}
+
+/** JSON with object keys sorted, so key order alone does not read as a difference. */
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+function missingKeys(expected: readonly string[], actual: readonly string[]): string[] {
+	const present = new Set(actual.filter(Boolean));
+	return expected.filter(key => key !== "" && !present.has(key));
+}
+
+/** Numeric-segment comparison. Enough for a dotted contract version, and no dependency. */
+export function compareContractVersions(left: string, right: string): number {
+	const parse = (value: string): number[] => value.split(".").map(part => Number.parseInt(part, 10) || 0);
+	const a = parse(left);
+	const b = parse(right);
+	for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+		const diff = (a[index] ?? 0) - (b[index] ?? 0);
+		if (diff !== 0) return diff < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
+function adoptSiblingIfNotARegression(from: string, to: string): void {
+	let sibling: CapabilityManifest;
+	let vendored: CapabilityManifest;
+	try {
+		sibling = JSON.parse(fs.readFileSync(from, "utf8")) as CapabilityManifest;
+		vendored = JSON.parse(fs.readFileSync(to, "utf8")) as CapabilityManifest;
+	} catch (error) {
+		// Unreadable input must not silently leave the committed copy in place either — say so.
+		console.warn(`Keeping the committed capabilities: could not compare with ${from} (${String(error)}).`);
+		return;
+	}
+
+	const reason = regressionReason(sibling, vendored);
+	if (reason === undefined) {
+		fs.copyFileSync(from, to);
+		return;
+	}
+
+	// Refused rather than fatal: this generator runs from `check:types`, `test` and `build`, so failing
+	// here would block every command on any machine with a stale sibling checkout. Skipping keeps the
+	// committed contract — the correct one — and names what was ignored so it is fixable.
+	console.warn(
+		`Ignoring ${from}: ${reason}.\n` +
+			"  The committed capabilities.json is being kept. Update or remove that checkout, or set\n" +
+			"  XCSH_EXTENSION_CAPABILITIES to the manifest you actually want compiled in.",
+	);
+}

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.101.0",
-	"commit": "389279d7ee7ae16a82af6b03d9f6ea3920e8925e",
-	"shortCommit": "389279d",
+	"version": "19.101.2",
+	"commit": "aa04beb39731933015b85ba67e1107c2c301ac01",
+	"shortCommit": "aa04beb",
 	"branch": "main",
-	"tag": "v19.101.0",
-	"commitDate": "2026-07-29T21:37:59Z",
-	"buildDate": "2026-07-29T22:01:44.081Z",
+	"tag": "v19.101.2",
+	"commitDate": "2026-07-30T03:09:56Z",
+	"buildDate": "2026-07-30T03:38:03.284Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/389279d7ee7ae16a82af6b03d9f6ea3920e8925e",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.101.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/aa04beb39731933015b85ba67e1107c2c301ac01",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.101.2"
 };

package/src/sandbox/command-operands.ts

@@ -278,3 +278,380 @@ export function provenExemptWords(cmd: ShellSimpleCommand): ShellWord[] {
 
 	return exempt;
 }
+
+/** Flag-only options shared by the compressors. */
+const GZIP_BOOLEAN_OPTIONS = [
+	"-1",
+	"-2",
+	"-3",
+	"-4",
+	"-5",
+	"-6",
+	"-7",
+	"-8",
+	"-9",
+	"-c",
+	"--stdout",
+	"-d",
+	"--decompress",
+	"-f",
+	"--force",
+	"-k",
+	"--keep",
+	"-q",
+	"--quiet",
+	"-r",
+	"--recursive",
+	"-t",
+	"--test",
+	"-v",
+	"--verbose",
+] as const satisfies readonly string[];
+
+/** curl options that consume a separate value, so it is not mistaken for a path. */
+const CURL_VALUE_OPTIONS = [
+	"-H",
+	"--header",
+	"-X",
+	"--request",
+	"-d",
+	"--data",
+	"-u",
+	"--user",
+	"-A",
+	"--user-agent",
+	"--connect-timeout",
+	"--max-time",
+	"-m",
+	"--retry",
+	"-b",
+	"--cookie",
+	"-c",
+	"--cookie-jar",
+] as const satisfies readonly string[];
+
+/** cp's flag-only options; shared so the mv/install entries stay readable. */
+const COPY_BOOLEAN_OPTIONS = [
+	"-a",
+	"--archive",
+	"-b",
+	"--backup",
+	"-d",
+	"-f",
+	"--force",
+	"-i",
+	"--interactive",
+	"-H",
+	"-l",
+	"--link",
+	"-L",
+	"--dereference",
+	"-n",
+	"--no-clobber",
+	"-P",
+	"--no-dereference",
+	"-p",
+	"-R",
+	"-r",
+	"--recursive",
+	"-s",
+	"--symbolic-link",
+	"-u",
+	"--update",
+	"-v",
+	"--verbose",
+	"-x",
+	"--one-file-system",
+] as const satisfies readonly string[];
+
+/**
+ * Which operands a command *writes*, so the boundary check picks the right direction.
+ *
+ * The read/write split in `enforce.ts` is derived from shell redirections. A write the invoked program
+ * performs on one of its own operands — `tee FILE`, `dd of=FILE`, `cp SRC DST`, `sort -o FILE` — had no
+ * such signal and defaulted to a read check. Under an `allowRead`-only grant that check passes, so the
+ * write lands on a path shared for reading only; confirmed at the decision layer, where all four returned
+ * `block: false` (GHSA-q4hg). The same misclassification refused those commands against a *write-only*
+ * grant, which is the mirror-image false refusal.
+ *
+ * Adding to this table is monotonic. Marking an operand as a write that is really a read costs a false
+ * refusal, which is the direction the surrounding code already errs in; missing one leaves today's
+ * behaviour untouched. So it is safe to extend, and deliberately incomplete rather than guessed at:
+ * `tar -f` is absent because whether it reads or writes depends on the mode letters, and getting that
+ * wrong in the permissive direction is the bug being fixed.
+ *
+ * Same suppression rule as `provenExemptWords`: an option this model cannot parse exactly shifts operand
+ * positions, so anything unrecognized abandons the command rather than guessing at a slot.
+ */
+interface WriteOperandSpec {
+	/** Options taking a separate value, so it is not mistaken for a positional operand. */
+	valueOptions: readonly string[];
+	/** Options that are flags only. */
+	booleanOptions: readonly string[];
+	/** `--output=F` style options whose value is the written path. */
+	outputOptions?: readonly string[];
+	/** `of=F` style prefixes whose value is the written path. */
+	outputPrefixes?: readonly string[];
+	/** Every positional operand is written (`tee a b c`). */
+	writesAllPositional?: boolean;
+	/** The final positional operand is written (`cp src dst`). */
+	writesLastPositional?: boolean;
+	/** With this option present the destination moves into it, so positional slots stop being writes. */
+	destinationOption?: string;
+	/** Positional operands that are not paths at all — `chmod 644 f`, `chown me f`. */
+	skipLeadingPositional?: number;
+	/** Every positional is written once this option appears (`install -d a b c`). */
+	allPositionalOption?: string;
+	/** Sources are written too, because the command removes them (`mv`). */
+	writesSourcesToo?: boolean;
+}
+
+const WRITE_OPERAND_SPECS: Record<string, WriteOperandSpec> = {
+	// tee writes every file operand; it reads stdin, never the files.
+	tee: {
+		valueOptions: [],
+		booleanOptions: ["-a", "--append", "-i", "--ignore-interrupts", "-p"],
+		writesAllPositional: true,
+	},
+	// `of=` is the output file. `if=` stays a read, which is what the floor already gives it.
+	dd: { valueOptions: [], booleanOptions: [], outputPrefixes: ["of="] },
+	sort: {
+		valueOptions: ["-k", "-t", "-S", "-T", "--key", "--field-separator", "--buffer-size"],
+		booleanOptions: ["-b", "-d", "-f", "-g", "-i", "-M", "-h", "-n", "-R", "-r", "-u", "-V", "-z", "-c", "-s"],
+		outputOptions: ["-o", "--output"],
+	},
+	cp: {
+		valueOptions: ["-S", "--suffix", "-t", "--target-directory"],
+		booleanOptions: COPY_BOOLEAN_OPTIONS,
+		writesLastPositional: true,
+		destinationOption: "-t",
+	},
+	// `mv` also REMOVES its sources, so a source in a read-only root is a mutation of that root.
+	// Marking only the destination let `mv /shared/ctx/file .` delete from a read-allowed grant.
+	mv: {
+		valueOptions: ["-S", "--suffix", "-t", "--target-directory"],
+		booleanOptions: ["-f", "--force", "-i", "--interactive", "-n", "--no-clobber", "-v", "--verbose", "-u"],
+		writesLastPositional: true,
+		writesSourcesToo: true,
+		destinationOption: "-t",
+	},
+	install: {
+		valueOptions: ["-m", "--mode", "-o", "--owner", "-g", "--group", "-t", "--target-directory", "-S", "--suffix"],
+		booleanOptions: ["-b", "-c", "-C", "-d", "-D", "-p", "-s", "-v", "--verbose", "--backup"],
+		writesLastPositional: true,
+		destinationOption: "-t",
+		// `install -d a b c` creates every operand as a directory rather than copying into the last.
+		allPositionalOption: "-d",
+	},
+	// Plain mutators: every path operand is written. Their absence was the largest hole in the table —
+	// `rm` and `touch` against a read-only root are the obvious cases, and both were classified as reads.
+	rm: {
+		valueOptions: [],
+		booleanOptions: ["-f", "--force", "-i", "-I", "-r", "-R", "--recursive", "-d", "--dir", "-v", "--verbose"],
+		writesAllPositional: true,
+	},
+	rmdir: { valueOptions: [], booleanOptions: ["-p", "--parents", "-v", "--verbose"], writesAllPositional: true },
+	touch: {
+		valueOptions: ["-d", "--date", "-r", "--reference", "-t"],
+		booleanOptions: ["-a", "-c", "--no-create", "-f", "-h", "--no-dereference", "-m"],
+		writesAllPositional: true,
+	},
+	mkdir: {
+		valueOptions: ["-m", "--mode"],
+		booleanOptions: ["-p", "--parents", "-v", "--verbose"],
+		writesAllPositional: true,
+	},
+	ln: {
+		valueOptions: ["-S", "--suffix", "-t", "--target-directory"],
+		booleanOptions: ["-b", "-f", "--force", "-i", "-L", "-n", "-P", "-r", "-s", "--symbolic", "-v"],
+		writesLastPositional: true,
+		destinationOption: "-t",
+	},
+	shred: {
+		valueOptions: ["-n", "--iterations", "-s", "--size"],
+		booleanOptions: ["-f", "--force", "-u", "--remove", "-v", "--verbose", "-x", "-z", "--zero"],
+		writesAllPositional: true,
+	},
+	unlink: { valueOptions: [], booleanOptions: [], writesAllPositional: true },
+	// The first positional is a mode or an owner, not a path.
+	chmod: {
+		valueOptions: ["--reference"],
+		booleanOptions: ["-c", "-f", "-v", "-R", "--recursive", "--silent", "--changes", "--verbose"],
+		writesAllPositional: true,
+		skipLeadingPositional: 1,
+	},
+	chown: {
+		valueOptions: ["--reference", "--from"],
+		booleanOptions: ["-c", "-f", "-v", "-R", "--recursive", "-h", "--no-dereference", "--silent", "--changes"],
+		writesAllPositional: true,
+		skipLeadingPositional: 1,
+	},
+	// In-place editors and compressors REPLACE the file they are given.
+	//
+	// `sed -i` has famously ambiguous arity — GNU takes an attached suffix, BSD a separate one — so
+	// which positional is the script cannot be settled. Every literal positional is therefore marked
+	// written, which over-marks the script operand. That is the safe direction: a false refusal, not a
+	// permitted write. The marking only applies when `-i` is present at all.
+	sed: {
+		valueOptions: ["-e", "--expression", "-f", "--file", "-l", "--line-length"],
+		booleanOptions: ["-n", "--quiet", "--silent", "-E", "-r", "--regexp-extended", "-s", "-u", "-z", "--debug"],
+		writesAllPositional: false,
+		allPositionalOption: "-i",
+	},
+	gzip: { valueOptions: ["-S", "--suffix"], booleanOptions: GZIP_BOOLEAN_OPTIONS, writesAllPositional: true },
+	gunzip: { valueOptions: ["-S", "--suffix"], booleanOptions: GZIP_BOOLEAN_OPTIONS, writesAllPositional: true },
+	bzip2: { valueOptions: [], booleanOptions: GZIP_BOOLEAN_OPTIONS, writesAllPositional: true },
+	xz: { valueOptions: ["-T", "--threads"], booleanOptions: GZIP_BOOLEAN_OPTIONS, writesAllPositional: true },
+	// Downloaders name their output explicitly; the URL operand is not a path.
+	curl: {
+		valueOptions: CURL_VALUE_OPTIONS,
+		booleanOptions: ["-L", "--location", "-s", "--silent", "-S", "--show-error", "-f", "--fail", "-k", "-I", "-v"],
+		outputOptions: ["-o", "--output"],
+	},
+	wget: {
+		valueOptions: ["--user-agent", "--header", "-P", "--directory-prefix", "-T", "--timeout"],
+		booleanOptions: ["-q", "--quiet", "-c", "--continue", "-N", "--no-verbose", "-nv"],
+		outputOptions: ["-O", "--output-document"],
+	},
+	truncate: {
+		valueOptions: ["-s", "--size", "-r", "--reference"],
+		booleanOptions: ["-c", "--no-create", "-o", "--io-blocks"],
+		writesAllPositional: true,
+	},
+};
+
+/**
+ * Words of `cmd` the invoked command writes to.
+ *
+ * Empty whenever anything is uncertain — an unknown command, an unrecognized option, a non-literal word.
+ * A word returned here is checked against the write boundary instead of the read one.
+ */
+export function writtenOperandWords(cmd: ShellSimpleCommand): ShellWord[] {
+	if (cmd.name === undefined) return [];
+	const spec = WRITE_OPERAND_SPECS[cmd.name];
+	if (spec === undefined) return [];
+
+	const operandWords = cmd.words.slice(cmd.operandStart).filter(word => word.redirect === undefined);
+
+	// An unparsable option shifts every positional slot, so abandon rather than mark the wrong word.
+	// Everything after `--` is a positional, however much it looks like an option — otherwise a file
+	// literally named `-t` makes `cp -- -t /drop/secret out/` read as a target-directory option and
+	// relabels a source as a write target.
+	let sawEndOfOptions = false;
+	for (const word of operandWords) {
+		if (word.text === "--") {
+			sawEndOfOptions = true;
+			continue;
+		}
+		if (sawEndOfOptions) continue;
+		const option = optionName(word.text);
+		if (option === undefined) continue;
+		if (isOutputOption(spec, option) || spec.valueOptions.includes(option)) continue;
+		if (spec.booleanOptions.includes(option)) continue;
+		if (matchesAllPositionalOption(spec, option)) continue;
+		if (bundledBooleans(option, spec) !== undefined) continue;
+		return [];
+	}
+
+	const written: ShellWord[] = [];
+	const positional: ShellWord[] = [];
+	let destinationMoved = false;
+	let allPositionalWritten = spec.writesAllPositional ?? false;
+	let pastEndOfOptions = false;
+
+	for (let index = 0; index < operandWords.length; index += 1) {
+		const word = operandWords[index];
+		if (!pastEndOfOptions && word.text === "--") {
+			pastEndOfOptions = true;
+			continue;
+		}
+		const option = pastEndOfOptions ? undefined : optionName(word.text);
+
+		if (option !== undefined && matchesAllPositionalOption(spec, option)) {
+			// `install -d` stops copying and starts creating, so every operand becomes a written path.
+			allPositionalWritten = true;
+			continue;
+		}
+
+		if (option !== undefined) {
+			const attached = word.text.includes("=");
+			if (isOutputOption(spec, option)) {
+				// `--output=F` carries its value; `-o F` takes the next word.
+				const target = attached ? valueAfterEquals(word) : operandWords[index + 1];
+				if (!attached) index += 1;
+				if (target?.literal) written.push(target);
+				continue;
+			}
+			if (spec.valueOptions.includes(option)) {
+				if (option === spec.destinationOption) destinationMoved = true;
+				if (!attached) {
+					const target = operandWords[index + 1];
+					index += 1;
+					if (target?.literal) written.push(target);
+				} else if (word.literal) {
+					written.push(word);
+				}
+			}
+			continue;
+		}
+
+		// `of=PATH` and friends are positional in shape but name their own direction.
+		const prefix = spec.outputPrefixes?.find(candidate => word.text.startsWith(candidate));
+		if (prefix !== undefined) {
+			if (word.literal) written.push(word);
+			continue;
+		}
+
+		positional.push(word);
+	}
+
+	const paths = positional.slice(spec.skipLeadingPositional ?? 0);
+	if (allPositionalWritten) {
+		written.push(...paths.filter(word => word.literal));
+	} else if (spec.writesSourcesToo && spec.writesLastPositional && !destinationMoved && paths.length >= 2) {
+		// Destination AND sources: `mv` removes what it moves.
+		written.push(...paths.filter(word => word.literal));
+	} else if (spec.writesLastPositional && !destinationMoved && paths.length >= 2) {
+		// Only with a source present. A lone operand is `cp x` — an error, not a write to model.
+		const destination = paths[paths.length - 1];
+		if (destination.literal) written.push(destination);
+	}
+
+	return written;
+}
+
+/**
+ * Split a bundled short option (`-ai`) into its letters when every one is a known boolean flag.
+ *
+ * Without this, `tee -ai /shared/ctx/x` hit the unrecognized-option path and abandoned the command —
+ * failing open to a read check on a write, which is the defect this module exists to fix.
+ */
+function bundledBooleans(option: string, spec: WriteOperandSpec): string[] | undefined {
+	if (!option.startsWith("-") || option.startsWith("--") || option.length <= 2) return undefined;
+	const letters = [...option.slice(1)].map(letter => `-${letter}`);
+	return letters.every(letter => spec.booleanOptions.includes(letter)) ? letters : undefined;
+}
+
+/**
+ * Whether an option turns every operand into a written path.
+ *
+ * Prefix-matched for the single-letter form, because GNU `sed` attaches the backup suffix to the flag:
+ * `-i.bak` is the same in-place edit as `-i`, and exact matching let that spelling through.
+ */
+function matchesAllPositionalOption(spec: WriteOperandSpec, option: string): boolean {
+	const target = spec.allPositionalOption;
+	if (target === undefined) return false;
+	if (option === target) return true;
+	return target.length === 2 && !target.startsWith("--") && option.startsWith(target);
+}
+
+function isOutputOption(spec: WriteOperandSpec, option: string): boolean {
+	return spec.outputOptions?.includes(option) ?? false;
+}
+
+/** The value half of an `--option=value` word, as a span the caller can mark. */
+function valueAfterEquals(word: ShellWord): ShellWord | undefined {
+	const equals = word.text.indexOf("=");
+	if (equals === -1) return undefined;
+	return { ...word, text: word.text.slice(equals + 1) };
+}

package/src/sandbox/enforce.ts

@@ -44,7 +44,7 @@ import * as path from "node:path";
 import { pathIsWithin } from "@f5-sales-demo/pi-utils";
 import { expandPath, parseFindPattern, parseSearchPath, resolveToCwd, splitTopLevel } from "../tools/path-utils";
 import { lexShellCommand, type ShellSimpleCommand } from "../tools/shell-lex";
-import { provenExemptWords } from "./command-operands";
+import { provenExemptWords, writtenOperandWords } from "./command-operands";
 import type { SandboxAccess, SandboxPolicy } from "./policy";
 
 export interface ToolCallCheck {
@@ -585,7 +585,12 @@ function shellPathCandidates(command: string): ShellScan {
 	// `<>` opens for both, so it stays a read here and picks up its write below: a floor occurrence
 	// may carry only one access, and read is the one the floor would have used anyway.
 	const writeTargets = lexed.words.filter(word => word.redirect === "write");
-	const inWriteTarget = (at: number): boolean => writeTargets.some(word => at >= word.start && at < word.end);
+	// Plus the operands the invoked program writes itself — `tee FILE`, `dd of=FILE`, `cp SRC DST`.
+	// Those had no direction signal and defaulted to a read check, so a write into an allowRead-only
+	// root passed and a write into an allowWrite-only root was refused (GHSA-q4hg).
+	const writtenOperands = lexed.commands.flatMap(simpleCommand => writtenOperandWords(simpleCommand));
+	const inWriteTarget = (at: number): boolean =>
+		[...writeTargets, ...writtenOperands].some(word => at >= word.start && at < word.end);
 
 	// A floor occurrence takes the access its own operator gave it; failing that, the span of a
 	// lexed write target it sits inside; failing that, read.