@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/resources/library.ts

@@ -0,0 +1,326 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { readSettings, updateSettings } from "../../core/config.js";
+import { runCommandVector, type SafeCommandResult } from "../../core/safe-exec.js";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { parseFrontmatter } from "../agents/frontmatter.js";
+import {
+	assertAgentSpecPolicy,
+	normalizeAgentSpec,
+	parseAgentRecipeSchema,
+	parseFleetContract,
+} from "../agents/index.js";
+import { loadPromptTemplates } from "./prompts/loader.js";
+import { normalizedSkillHash } from "./skills/install.js";
+import {
+	type DiscoverMarketplaceOptions,
+	discoverMarketplaceSkills,
+	installSkill,
+	type LibraryEntryKind,
+	type LibraryRequirementRef,
+	type MarketplaceSkill,
+} from "./skills/marketplace.js";
+
+export type LibraryEntry = MarketplaceSkill;
+
+export interface LibraryDiscoveryResult {
+	entries: LibraryEntry[];
+	diagnostics: string[];
+	refusals: Readonly<Record<string, string>>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function catalogPath(): string {
+	const configured = readSettings().library.catalog;
+	return path.resolve(configured ?? path.join(clioConfigDir(), "library.yaml"));
+}
+
+function parseCatalog(filePath: string, diagnostics: string[]): LibraryEntry[] {
+	if (!existsSync(filePath)) return [];
+	try {
+		const raw = readFileSync(filePath, "utf8");
+		const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : parseYaml(raw);
+		const rows = Array.isArray(parsed) ? parsed : isRecord(parsed) && Array.isArray(parsed.skills) ? parsed.skills : [];
+		return rows.flatMap((value): LibraryEntry[] => {
+			if (
+				!isRecord(value) ||
+				typeof value.name !== "string" ||
+				typeof value.description !== "string" ||
+				typeof value.sourceUrl !== "string"
+			) {
+				diagnostics.push(`library catalog entry malformed: ${filePath}`);
+				return [];
+			}
+			const kind: LibraryEntryKind =
+				value.kind === undefined || value.kind === "skill"
+					? "skill"
+					: value.kind === "agent" || value.kind === "prompt" || value.kind === "fleet"
+						? value.kind
+						: "skill";
+			if (value.kind !== undefined && !["skill", "agent", "prompt", "fleet"].includes(String(value.kind))) {
+				diagnostics.push(`library catalog entry has unsupported kind: ${value.name}`);
+				return [];
+			}
+			if (
+				value.requires !== undefined &&
+				(!Array.isArray(value.requires) || value.requires.some((item) => typeof item !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${value.name}`);
+				return [];
+			}
+			const sourceUrl = /^(?:https?:\/\/|git@)/.test(value.sourceUrl)
+				? value.sourceUrl
+				: path.resolve(path.dirname(filePath), value.sourceUrl);
+			const requires = Array.isArray(value.requires)
+				? value.requires.filter((item): item is LibraryRequirementRef => typeof item === "string")
+				: undefined;
+			return [
+				{
+					kind,
+					name: value.name.trim(),
+					description: value.description.trim(),
+					sourceUrl,
+					origin: "index",
+					...(typeof value.version === "string" ? { version: value.version } : {}),
+					...(requires ? { requires } : {}),
+				},
+			];
+		});
+	} catch (error) {
+		diagnostics.push(`library catalog unreadable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}
+
+export function libraryEntryRef(entry: Pick<LibraryEntry, "kind" | "name">): LibraryRequirementRef {
+	return `${entry.kind}:${entry.name}`;
+}
+
+export function discoverLibrary(
+	options: { catalog?: string; cwd?: string; marketplace?: DiscoverMarketplaceOptions } = {},
+): LibraryDiscoveryResult {
+	const marketplace = discoverMarketplaceSkills({
+		...(options.marketplace ?? {}),
+		...(options.cwd ? { cwd: options.cwd } : {}),
+	});
+	const diagnostics = [...marketplace.diagnostics.filter((item) => !item.includes("no local skill marketplace"))];
+	const privatePath = catalogPath();
+	const primary = options.catalog ? parseCatalog(path.resolve(options.catalog), diagnostics) : [];
+	const privateEntries = parseCatalog(privatePath, diagnostics);
+	const byRef = new Map<string, LibraryEntry>();
+	for (const entry of [...marketplace.skills, ...primary, ...privateEntries]) byRef.set(libraryEntryRef(entry), entry);
+	const refusals: Record<string, string> = {};
+	const entries = [...byRef.values()].filter((entry) => {
+		try {
+			resolveLibraryRequirements(entry, [...byRef.values()]);
+			return true;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			refusals[libraryEntryRef(entry)] = message;
+			if (!diagnostics.includes(message)) diagnostics.push(message);
+			return false;
+		}
+	});
+	return {
+		entries: entries.sort((a, b) => libraryEntryRef(a).localeCompare(libraryEntryRef(b))),
+		diagnostics,
+		refusals,
+	};
+}
+
+const REQUIREMENT_PATTERN = /^(skill|agent|prompt|fleet):([A-Za-z0-9][A-Za-z0-9._-]*)$/;
+
+export function resolveLibraryRequirements(entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>): LibraryEntry[] {
+	const byRef = new Map(catalog.map((item) => [libraryEntryRef(item), item]));
+	const ordered: LibraryEntry[] = [];
+	const visiting: string[] = [];
+	const visited = new Set<string>();
+	const visit = (current: LibraryEntry): void => {
+		const currentRef = libraryEntryRef(current);
+		if (visited.has(currentRef)) return;
+		const cycleAt = visiting.indexOf(currentRef);
+		if (cycleAt >= 0)
+			throw new Error(`library_requirement_cycle: ${[...visiting.slice(cycleAt), currentRef].join(" -> ")}`);
+		visiting.push(currentRef);
+		for (const requirement of current.requires ?? []) {
+			if (!REQUIREMENT_PATTERN.test(requirement)) throw new Error("library_requirement_malformed");
+			const dependency = byRef.get(requirement);
+			if (!dependency) throw new Error(`library_requirement_missing: ${requirement}`);
+			visit(dependency);
+		}
+		visiting.pop();
+		visited.add(currentRef);
+		ordered.push(current);
+	};
+	visit(entry);
+	return ordered;
+}
+
+function sourceFile(entry: LibraryEntry): string {
+	const source = path.resolve(entry.sourceUrl);
+	if (entry.kind === "skill") return source;
+	if (!existsSync(source)) throw new Error(`library source path does not exist: ${source}`);
+	return source;
+}
+
+function validateEntry(entry: LibraryEntry, raw: string, filePath: string): void {
+	if (entry.kind === "fleet") {
+		parseFleetContract(raw, filePath);
+		return;
+	}
+	if (entry.kind === "agent") {
+		const parsed = parseFrontmatter(raw, filePath);
+		const recipe = parseAgentRecipeSchema({ id: entry.name, source: "user", filepath: filePath, ...parsed });
+		assertAgentSpecPolicy(normalizeAgentSpec(recipe));
+		return;
+	}
+	if (entry.kind === "prompt") {
+		const loaded = loadPromptTemplates({ roots: [{ path: path.dirname(filePath), scope: "user", source: "library" }] });
+		if (!loaded.items.some((item) => item.filePath === filePath))
+			throw new Error(`prompt template is malformed: ${filePath}`);
+	}
+}
+
+export interface LibraryInstallPlan {
+	entry: LibraryEntry;
+	path: string;
+	sha256: string;
+}
+
+export function libraryInstallPath(entry: Pick<LibraryEntry, "kind" | "name">): string {
+	if (entry.kind === "skill") return path.join(clioConfigDir(), "skills", entry.name, "SKILL.md");
+	const root = entry.kind === "agent" ? "agents" : entry.kind === "fleet" ? "fleets" : "prompts";
+	return path.join(clioConfigDir(), root, `${entry.name}.md`);
+}
+
+function readLibraryPins(): Record<string, { sha256: string; sourceUrl: string }> {
+	const pinPath = path.join(clioConfigDir(), "library-pins.yaml");
+	if (!existsSync(pinPath)) return {};
+	const parsed = parseYaml(readFileSync(pinPath, "utf8"));
+	return isRecord(parsed) ? (parsed as Record<string, { sha256: string; sourceUrl: string }>) : {};
+}
+
+export interface LibraryRequirementStatus {
+	ordered: LibraryEntry[];
+	satisfied: LibraryEntry[];
+	unsatisfied: LibraryEntry[];
+}
+
+/**
+ * Whether this entry is already on disk for this operator. A kind-qualified pin
+ * and a kind-specific destination are each sufficient, which is the same rule
+ * the requirement classifier applies, so a surface that draws an installed or
+ * available column never disagrees with the gate that refuses an install.
+ */
+export function libraryEntryInstalled(entry: Pick<LibraryEntry, "kind" | "name">): boolean {
+	return readLibraryPins()[libraryEntryRef(entry)] !== undefined || existsSync(libraryInstallPath(entry));
+}
+
+/**
+ * The pin recorded for this entry, or undefined when nothing pinned it. A
+ * destination can exist without a pin, which is why this is a separate question
+ * from `libraryEntryInstalled`.
+ */
+export function libraryEntryPin(
+	entry: Pick<LibraryEntry, "kind" | "name">,
+): { sha256: string; sourceUrl: string } | undefined {
+	return readLibraryPins()[libraryEntryRef(entry)];
+}
+
+export function classifyLibraryRequirements(
+	entry: LibraryEntry,
+	catalog: ReadonlyArray<LibraryEntry>,
+): LibraryRequirementStatus {
+	const ordered = resolveLibraryRequirements(entry, catalog).slice(0, -1);
+	const satisfied = ordered.filter((requirement) => libraryEntryInstalled(requirement));
+	const satisfiedRefs = new Set(satisfied.map(libraryEntryRef));
+	return {
+		ordered,
+		satisfied,
+		unsatisfied: ordered.filter((requirement) => !satisfiedRefs.has(libraryEntryRef(requirement))),
+	};
+}
+
+export function planLibraryInstall(entry: LibraryEntry): LibraryInstallPlan {
+	if (entry.kind === "skill") {
+		const source = sourceFile(entry);
+		const file = statSync(source).isDirectory() ? path.join(source, "SKILL.md") : source;
+		const raw = readFileSync(file);
+		return {
+			entry,
+			path: libraryInstallPath(entry),
+			sha256: normalizedSkillHash(raw.toString("utf8")),
+		};
+	}
+	const source = sourceFile(entry);
+	const raw = readFileSync(source, "utf8");
+	validateEntry(entry, raw, source);
+	return {
+		entry,
+		path: libraryInstallPath(entry),
+		sha256: createHash("sha256").update(raw).digest("hex"),
+	};
+}
+
+function recordPin(plan: LibraryInstallPlan): void {
+	const pinPath = path.join(clioConfigDir(), "library-pins.yaml");
+	const pins = readLibraryPins();
+	pins[libraryEntryRef(plan.entry)] = { sha256: plan.sha256, sourceUrl: plan.entry.sourceUrl };
+	safeResourceWrite(pinPath, stringifyYaml(Object.fromEntries(Object.entries(pins).sort())), { encoding: "utf8" });
+}
+
+export function installLibraryPlan(plan: LibraryInstallPlan): void {
+	if (existsSync(plan.path)) throw new Error(`library destination already exists: ${plan.path}`);
+	if (plan.entry.kind === "skill") installSkill({ source: plan.entry.sourceUrl, scope: "user", name: plan.entry.name });
+	else safeResourceWrite(plan.path, readFileSync(sourceFile(plan.entry)));
+	recordPin(plan);
+}
+
+function confirmedRemote(): string {
+	const settings = readSettings().library;
+	if (!settings.remote || settings.remote !== settings.confirmedRemote) throw new Error("library_remote_unconfirmed");
+	return settings.remote;
+}
+
+export function confirmLibraryRemote(url: string): void {
+	const current = readSettings().library.remote;
+	if (current !== null && current !== url) throw new Error("library_remote_mismatch");
+	updateSettings((settings) => {
+		if (settings.library.remote === null) settings.library.remote = url;
+		settings.library.confirmedRemote = url;
+	});
+}
+
+export type LibraryCommandRunner = (
+	file: string,
+	args: ReadonlyArray<string>,
+	options: { cwd: string; workspaceRoot: string },
+) => Promise<SafeCommandResult>;
+
+export async function syncLibrary(
+	direction: "sync" | "push",
+	runner: LibraryCommandRunner = runCommandVector,
+): Promise<void> {
+	const settings = readSettings().library;
+	if (!settings.sync) throw new Error("library_sync_disabled");
+	const remote = confirmedRemote();
+	const cwd = path.dirname(catalogPath());
+	const remoteResult = await runner("git", ["remote", "get-url", "library"], { cwd, workspaceRoot: cwd });
+	if (remoteResult.exitCode !== 0 || remoteResult.stdout.trim() !== remote)
+		throw new Error("library_remote_unconfirmed");
+	if (direction === "sync") {
+		const fetched = await runner("git", ["fetch", "library"], { cwd, workspaceRoot: cwd });
+		if (fetched.exitCode !== 0) throw new Error(fetched.stderr.trim() || "library sync failed");
+		const advanced = await runner("git", ["merge", "--ff-only", "FETCH_HEAD"], { cwd, workspaceRoot: cwd });
+		if (advanced.exitCode !== 0) throw new Error(advanced.stderr.trim() || "library sync failed");
+		return;
+	}
+	const result = await runner("git", ["push", "library"], { cwd, workspaceRoot: cwd });
+	if (result.exitCode !== 0) throw new Error(result.stderr.trim() || `library ${direction} failed`);
+}

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

@@ -35,6 +35,8 @@ import { loadSkills, type Skill } from "./loader.js";
  */
 
 export type MarketplaceSkillOrigin = "catalog" | "index";
+export type LibraryEntryKind = "skill" | "agent" | "prompt" | "fleet";
+export type LibraryRequirementRef = `${LibraryEntryKind}:${string}`;
 
 /**
  * The diagnostic that means "nothing is wrong, nothing is configured". Callers
@@ -44,6 +46,7 @@ export type MarketplaceSkillOrigin = "catalog" | "index";
 export const MARKETPLACE_UNCONFIGURED = "no local skill marketplace catalog or index configured";
 
 export interface MarketplaceSkill {
+	kind: LibraryEntryKind;
 	name: string;
 	description: string;
 	/** Local path or URL accepted by `clio-coder skills install`. */
@@ -53,6 +56,7 @@ export interface MarketplaceSkill {
 	/** Catalog grouping ("git", "research", ...); absent in a flat catalog. */
 	category?: string;
 	origin: MarketplaceSkillOrigin;
+	requires?: LibraryRequirementRef[];
 }
 
 export type MarketplaceStatus = "installed" | "installable" | "unavailable";
@@ -131,7 +135,7 @@ function indexAudit(value: unknown): MarketplaceSkill["audit"] {
 	return value === "pass" || value === "warn" || value === "fail" || value === "unknown" ? value : undefined;
 }
 
-function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill[] {
+function parseMarketplaceIndex(indexPath: string, diagnostics: string[] = []): MarketplaceSkill[] {
 	try {
 		const parsed = JSON.parse(readFileSync(indexPath, "utf8")) as unknown;
 		const rawSkills = Array.isArray(parsed)
@@ -139,7 +143,7 @@ function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill
 			: parsed && typeof parsed === "object" && Array.isArray((parsed as { skills?: unknown }).skills)
 				? (parsed as { skills: unknown[] }).skills
 				: [];
-		return rawSkills.filter(isIndexSkill).map((skill) => {
+		return rawSkills.filter(isIndexSkill).flatMap((skill): MarketplaceSkill[] => {
 			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
@@ -147,15 +151,35 @@ function indexSkills(indexPath: string, diagnostics: string[]): MarketplaceSkill
 			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,
-			};
+			if (record.kind !== undefined && !["skill", "agent", "prompt", "fleet"].includes(String(record.kind))) {
+				diagnostics.push(`skill marketplace index entry has unsupported kind: ${skill.name}`);
+				return [];
+			}
+			if (
+				record.requires !== undefined &&
+				(!Array.isArray(record.requires) || record.requires.some((entry) => typeof entry !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${skill.name}`);
+				return [];
+			}
+			const kind: LibraryEntryKind =
+				record.kind === "agent" || record.kind === "prompt" || record.kind === "fleet" ? record.kind : "skill";
+			const requires = Array.isArray(record.requires)
+				? record.requires.filter((entry): entry is LibraryRequirementRef => typeof entry === "string")
+				: undefined;
+			return [
+				{
+					kind,
+					name: skill.name.trim(),
+					description: skill.description.trim(),
+					sourceUrl: skill.sourceUrl.trim(),
+					...(version ? { version } : {}),
+					...(audit ? { audit } : {}),
+					...(category ? { category } : {}),
+					...(requires ? { requires } : {}),
+					origin: "index" as const,
+				},
+			];
 		});
 	} catch (err) {
 		diagnostics.push(`skill marketplace index unreadable: ${err instanceof Error ? err.message : String(err)}`);
@@ -226,6 +250,7 @@ function catalogEntry(skill: Skill, catalogDir: string): MarketplaceSkill {
 		...(skill.provenance?.audit ? { audit: skill.provenance.audit } : {}),
 		...(category ? { category } : {}),
 		origin: "catalog",
+		kind: "skill",
 	};
 }
 
@@ -256,7 +281,7 @@ export function discoverMarketplaceSkills(options: DiscoverMarketplaceOptions =
 		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)) {
+		for (const skill of parseMarketplaceIndex(resolvedIndexPath, diagnostics)) {
 			if (seen.has(skill.name)) continue;
 			seen.add(skill.name);
 			skills.push(skill);

package/src/domains/safety/call-target.ts

@@ -7,6 +7,8 @@
  * or spoof the UI that approves it.
  */
 
+import { isSecretArgKey, redactSecretString } from "./redaction.js";
+
 const ESC_CHAR = String.fromCharCode(27);
 const BEL_CHAR = String.fromCharCode(7);
 // Built through the constructor so no control character appears in a regex
@@ -39,21 +41,216 @@ export function sanitizeCallTargetText(value: string): string {
 }
 
 /**
- * Derive the operator-facing object of a call for the approval overlay: the
- * command for bash, a path for file tools, else a compact args preview.
- * Returns an empty string when nothing meaningful is derivable, so callers
- * can omit the Target row instead of rendering a blank.
+ * What a tool call is doing, in the bounded form that may cross the worker
+ * stdout seam. The verb comes from a fixed vocabulary and the object from a
+ * fixed allowlist of argument fields, so an argument the table does not name
+ * cannot reach an operator surface however it is spelled.
+ */
+export interface CallActionDescriptor {
+	/** One word from the vocabulary below naming what the call does. */
+	verb: string;
+	/** The redacted, bounded thing the call acts on. Absent when nothing safe is derivable. */
+	object?: string;
+	/** Whether the object was cut to {@link CALL_ACTION_OBJECT_MAX_CHARS}. */
+	truncated?: boolean;
+}
+
+/**
+ * Characters of object text a descriptor carries. Bounded here rather than at
+ * the renderer: this string crosses a process boundary, so a hostile argument
+ * must be small before it is transported, not after.
  */
-export function describeCallTarget(args: Record<string, unknown> | undefined): string {
+export const CALL_ACTION_OBJECT_MAX_CHARS = 64;
+
+/** Maximum characters carried by the approval overlay's one-line call target. */
+export const CALL_TARGET_MAX_CHARS = 120;
+
+/**
+ * The verb and object field for each tool Clio ships, plus the ACP tool kinds
+ * a delegated peer reports. A tool absent from this table gets the neutral
+ * `calling` verb, never a verb guessed from its name.
+ */
+const CALL_ACTION_VOCABULARY: Readonly<Record<string, { verb: string; field: string }>> = {
+	read: { verb: "reading", field: "path" },
+	edit: { verb: "editing", field: "path" },
+	write: { verb: "writing", field: "path" },
+	ls: { verb: "listing", field: "path" },
+	bash: { verb: "running", field: "command" },
+	grep: { verb: "searching", field: "pattern" },
+	find: { verb: "finding", field: "pattern" },
+	web_fetch: { verb: "fetching", field: "url" },
+	git: { verb: "git", field: "op" },
+	verify: { verb: "verifying", field: "check" },
+	code_nav: { verb: "navigating", field: "query" },
+	context: { verb: "context", field: "scope" },
+	artifact: { verb: "writing", field: "kind" },
+	monitor: { verb: "monitoring", field: "run_id" },
+	steer: { verb: "steering", field: "run_id" },
+	tasks: { verb: "tasks", field: "action" },
+	dispatch: { verb: "dispatching", field: "agent" },
+	// ACP tool kinds. A peer names its own argument fields, so these rely on
+	// the shared allowlist below rather than on a field this side can predict.
+	execute: { verb: "running", field: "command" },
+	search: { verb: "searching", field: "query" },
+	fetch: { verb: "fetching", field: "url" },
+	delete: { verb: "deleting", field: "path" },
+	move: { verb: "moving", field: "path" },
+	think: { verb: "thinking", field: "" },
+};
+
+/**
+ * Argument fields any tool may surface as its object. A field outside this
+ * list is never read, so a tool that hides a credential in `body`, `headers`,
+ * or `env` cannot leak it through a descriptor.
+ */
+const CALL_ACTION_OBJECT_FIELDS = ["path", "file_path", "command", "pattern", "query", "url"] as const;
+
+/**
+ * Argument fields whose values may reach the approval overlay for each tool.
+ * Fields are ordered by decision value: the first present field is the plain
+ * target, and any later present fields are labeled facts. Everything outside
+ * the tool's list is described only by type and size.
+ */
+const CALL_TARGET_FIELDS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	read: ["path", "offset", "limit", "tail"],
+	grep: ["pattern", "path", "mode", "glob", "ignore_case", "literal", "context", "limit", "include_ignored"],
+	find: ["pattern", "path", "order", "limit", "include_ignored"],
+	ls: ["path", "limit"],
+	code_nav: ["mode", "query", "limit"],
+	context: ["scope", "query", "name", "limit", "ref", "include_tree"],
+	credential_present: ["name", "source", "file"],
+	write: ["path"],
+	edit: ["path"],
+	bash: ["command", "cwd", "timeout_ms", "output_policy"],
+	git: ["op", "path", "cached", "stat", "name_only", "limit", "cwd", "timeout_ms", "max_output_bytes"],
+	verify: ["check", "path", "browser", "cwd", "timeout_ms", "max_output_bytes"],
+	dispatch: [
+		"list",
+		"mode",
+		"agent",
+		"target",
+		"model",
+		"node",
+		"autonomy",
+		"tool_profile",
+		"thinking_level",
+		"detach",
+		"timeout_ms",
+	],
+	monitor: ["run_id", "mode"],
+	steer: ["run_id", "action"],
+	tasks: ["action", "id"],
+	ledger: ["action", "kind", "path", "line", "target", "passed", "since"],
+	web_fetch: ["url", "method", "timeout_ms", "max_bytes", "format"],
+	ask_user: ["action", "mode", "max_rounds", "exposure"],
+	artifact: ["kind", "path", "title"],
+	// ACP tool kinds use only fields whose meaning the protocol defines.
+	execute: ["command", "cwd"],
+	search: ["query", "path"],
+	fetch: ["url", "method"],
+	delete: ["path"],
+	move: ["path", "target"],
+};
+
+/** Sanitize, scrub, and bound one candidate object string. Null when nothing is left. */
+function boundActionObject(value: unknown): { object: string; truncated: boolean } | null {
+	if (typeof value !== "string") return null;
+	const clean = sanitizeCallTargetText(redactSecretString(value));
+	if (clean.length === 0) return null;
+	if (clean.length <= CALL_ACTION_OBJECT_MAX_CHARS) return { object: clean, truncated: false };
+	return { object: clean.slice(0, CALL_ACTION_OBJECT_MAX_CHARS), truncated: true };
+}
+
+/**
+ * Compose the redacted action descriptor for one tool call. Called at the
+ * trusted seams that hold the arguments (the tool registry's admission path,
+ * the Claude tool mapper, and the ACP update mapper) so the descriptor, and
+ * never the arguments, is what crosses into an operator surface.
+ *
+ * Returns null when the tool is unknown and no allowlisted field is present:
+ * a bare `calling` with nothing after it says less than the tool name already
+ * on the row.
+ */
+export function describeCallAction(
+	tool: string,
+	args: Record<string, unknown> | undefined,
+): CallActionDescriptor | null {
+	const known = CALL_ACTION_VOCABULARY[tool];
+	const candidates = known?.field ? [known.field, ...CALL_ACTION_OBJECT_FIELDS] : [...CALL_ACTION_OBJECT_FIELDS];
+	let bounded: { object: string; truncated: boolean } | null = null;
+	if (args) {
+		for (const field of candidates) {
+			if (isSecretArgKey(field)) continue;
+			bounded = boundActionObject(args[field]);
+			if (bounded !== null) break;
+		}
+	}
+	if (known === undefined && bounded === null) return null;
+	const verb = known?.verb ?? "calling";
+	if (bounded === null) return { verb };
+	return { verb, object: bounded.object, ...(bounded.truncated ? { truncated: true } : {}) };
+}
+
+function renderAllowedTargetValue(value: unknown): string | null {
+	if (typeof value === "string") {
+		const rendered = sanitizeCallTargetText(redactSecretString(value));
+		return rendered.length > 0 ? rendered : null;
+	}
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return String(value);
+	return null;
+}
+
+function countLabel(count: number, singular: string, plural: string): string {
+	return `${count} ${count === 1 ? singular : plural}`;
+}
+
+/** Describe an argument without copying any part of its value into display text. */
+function summarizeUnlistedTargetValue(value: unknown): string {
+	if (typeof value === "string") {
+		return `<string ${countLabel(Buffer.byteLength(value, "utf8"), "byte", "bytes")}>`;
+	}
+	if (Array.isArray(value)) return `<array ${countLabel(value.length, "item", "items")}>`;
+	if (value !== null && typeof value === "object") {
+		return `<object ${countLabel(Object.keys(value).length, "field", "fields")}>`;
+	}
+	if (value === null) return "<null 0 values>";
+	if (typeof value === "undefined") return "<undefined 0 values>";
+	return `<${typeof value} 1 value>`;
+}
+
+function targetFieldName(value: string): string {
+	return sanitizeCallTargetText(value).slice(0, 32) || "field";
+}
+
+/**
+ * Derive the operator-facing object of a call for the approval overlay. Only
+ * values in the named tool's allowlist may render. Every other argument is
+ * summarized by its field name, type, and size, so an unexpected credential
+ * or pasted document still informs the decision without disclosing content.
+ * Returns an empty string when the call carries no arguments.
+ */
+export function describeCallTarget(tool: string, args: Record<string, unknown> | undefined): string {
 	if (!args) return "";
-	const str = (value: unknown): string | null =>
-		typeof value === "string" && value.trim().length > 0 ? oneLine(sanitizeForDisplay(value)).trim() || null : null;
-	const candidate = str(args.command) ?? str(args.path) ?? str(args.file_path) ?? str(args.name) ?? str(args.pattern);
-	if (candidate) return candidate;
-	try {
-		const json = JSON.stringify(args);
-		return json === "{}" || json === undefined ? "" : oneLine(sanitizeForDisplay(json)).slice(0, 120);
-	} catch {
-		return "";
+	const allowedFields = CALL_TARGET_FIELDS[tool] ?? [];
+	const allowed = new Set(allowedFields);
+	const parts: string[] = [];
+	for (const field of allowedFields) {
+		if (!(field in args)) continue;
+		if (isSecretArgKey(field)) {
+			parts.push(`${targetFieldName(field)}=${summarizeUnlistedTargetValue(args[field])}`);
+			continue;
+		}
+		const rendered = renderAllowedTargetValue(args[field]);
+		if (rendered === null) {
+			parts.push(`${targetFieldName(field)}=${summarizeUnlistedTargetValue(args[field])}`);
+			continue;
+		}
+		parts.push(parts.length === 0 ? rendered : `${targetFieldName(field)}=${rendered}`);
+	}
+	for (const [field, value] of Object.entries(args)) {
+		if (allowed.has(field)) continue;
+		parts.push(`${targetFieldName(field)}=${summarizeUnlistedTargetValue(value)}`);
 	}
+	return sanitizeCallTargetText(parts.join(" · ")).slice(0, CALL_TARGET_MAX_CHARS);
 }