@iowarp/clio-coder 0.3.4 → 0.3.6

package/src/domains/providers/index.ts

@@ -32,6 +32,7 @@ export type { ModelCapabilityPatchTarget } from "./model-capabilities.js";
 export { applyModelCapabilityPatch, resolveModelCapabilities } from "./model-capabilities.js";
 export {
 	canonicalizeWireModelId,
+	contextSlotsForModel,
 	hasLiveModelCatalog,
 	loadedContextWindowForModel,
 	type ModelResidency,
@@ -96,6 +97,7 @@ export {
 	refineRuntimeTargetWithModelHints,
 	resolveRuntimeTarget,
 	runtimeResolutionWarnings,
+	runtimeResolutionWarningsBesideThinkingNotice,
 	runtimeTargetSnapshot,
 } from "./runtime-resolution.js";
 export {
@@ -126,6 +128,7 @@ export {
 	EMPTY_CAPABILITIES,
 	VALID_THINKING_LEVELS,
 } from "./types/capability-flags.js";
+export { type ContextWindowSlots, formatContextWindowSlots } from "./types/context-window-slots.js";
 export { type CostProvenance, normalizeCostProvenance } from "./types/cost-provenance.js";
 export type { KnowledgeBase, KnowledgeBaseEntry, KnowledgeBaseHit } from "./types/knowledge-base.js";
 export type {

package/src/domains/providers/model-discovery.ts

@@ -1,5 +1,6 @@
 import type { TargetStatus } from "./contract.js";
 import { listKnownModelsForRuntime } from "./support.js";
+import type { ContextWindowSlots } from "./types/context-window-slots.js";
 
 export type ProviderModelSource = "configured" | "live" | "catalog" | "default";
 
@@ -45,6 +46,14 @@ export function loadedContextWindowForModel(
 	return typeof reported === "number" && Number.isFinite(reported) && reported > 0 ? reported : null;
 }
 
+/** How the server splits its KV budget for this model, when the probe saw it split. */
+export function contextSlotsForModel(
+	status: DiscoveryStatus | null | undefined,
+	modelId: string,
+): ContextWindowSlots | null {
+	return status?.discoveredModelStates?.[modelId]?.contextSlots ?? null;
+}
+
 /**
  * Residency as one view, so the planner and the "not resident" notice cannot
  * disagree about the same model. A reported loaded window settles it whatever

package/src/domains/providers/runtime-resolution.ts

@@ -5,7 +5,7 @@ import { getCatalogModelForRuntime, resolveCostProvenance } from "./catalog.js";
 import type { ProvidersContract, TargetStatus } from "./contract.js";
 import { isDispatchEligibleRuntime, isOrchestratorEligibleRuntime, isTargetEligibleRuntime } from "./eligibility.js";
 import { probeCapabilitiesForModel, resolveModelCapabilities } from "./model-capabilities.js";
-import { hasLiveModelCatalog, loadedContextWindowForModel } from "./model-discovery.js";
+import { contextSlotsForModel, hasLiveModelCatalog, loadedContextWindowForModel } from "./model-discovery.js";
 import {
 	type ReasoningClass,
 	type ResolvedModelRuntimeCapabilities,
@@ -14,6 +14,7 @@ import {
 	resolveTargetRuntimeCapabilities,
 } from "./model-runtime-capabilities.js";
 import type { CapabilityFlags, ThinkingLevel } from "./types/capability-flags.js";
+import type { ContextWindowSlots } from "./types/context-window-slots.js";
 import type { CostProvenance } from "./types/cost-provenance.js";
 import type { KnowledgeBase } from "./types/knowledge-base.js";
 import type {
@@ -52,6 +53,12 @@ export interface ContextWindowDetails {
 	effectiveContextWindow: number;
 	/** Where `effectiveContextWindow` came from. */
 	contextWindowSource: ContextWindowSource;
+	/**
+	 * Present when the probed window is a per-request share of the server's
+	 * KV budget (llama.cpp `--ctx-size` over `--parallel` slots), so the
+	 * operator surfaces can render `196,608 (786,432 / 4 slots)`.
+	 */
+	contextWindowSlots: ContextWindowSlots | null;
 	/** The window is below what this kind of work wants. An actionable degradation. */
 	warning: string | null;
 	/** The window is a placeholder rather than something the target reported. */
@@ -406,6 +413,8 @@ export function resolveRuntimeTarget(
 		providers.knowledgeBase,
 		probedContextWindow,
 		loadedContextWindow,
+		undefined,
+		contextSlotsForModel(status, wireModelId),
 	);
 	capabilities.contextWindow = contextWindowDetails.effectiveContextWindow;
 	if (contextWindowDetails.warning) {
@@ -513,6 +522,7 @@ export function refineRuntimeTargetWithModelHints(
 		// hand the planner the declared window back on the first refinement.
 		target.contextWindowDetails.loadedContextWindow,
 		modelHintContextWindow,
+		target.contextWindowDetails.contextWindowSlots,
 	);
 	capabilities.contextWindow = contextWindowDetails.effectiveContextWindow;
 
@@ -582,6 +592,21 @@ export function runtimeResolutionWarnings(diagnostics: ReadonlyArray<RuntimeReso
 	return diagnostics.filter((entry) => entry.severity === "warning").map((entry) => entry.message);
 }
 
+/**
+ * The warnings a surface that prints its own thinking-clamp line should
+ * announce. `thinking-coerced` and `thinking-<kind>` are the two halves of
+ * that one line, so when the resolved thinking carries a notice they are
+ * dropped here: an always-on model printed three lines saying one thing
+ * (issue #191). With no notice, a bare coercion is still worth a line.
+ */
+export function runtimeResolutionWarningsBesideThinkingNotice(
+	diagnostics: ReadonlyArray<RuntimeResolutionDiagnostic>,
+	thinkingNotice: string,
+): string[] {
+	if (thinkingNotice.trim().length === 0) return runtimeResolutionWarnings(diagnostics);
+	return runtimeResolutionWarnings(diagnostics.filter((entry) => !entry.code.startsWith("thinking-")));
+}
+
 /**
  * Minimum context Clio is built for, applied to every tier rather than only to
  * local-native. A hosted target that reports less than this is as unable to
@@ -623,6 +648,7 @@ export function resolveContextWindowDetails(
 	probedContextWindow: number | null,
 	loadedContextWindow: number | null = null,
 	modelHintContextWindow?: number,
+	probedContextSlots: ContextWindowSlots | null = null,
 ): ContextWindowDetails {
 	const catalogModel = getCatalogModelForRuntime(runtime.id, wireModelId);
 	const kbHit = knowledgeBase?.lookup(wireModelId) ?? null;
@@ -707,6 +733,16 @@ export function resolveContextWindowDetails(
 			`Run 'clio-coder targets --probe' to read the real one.`;
 	}
 
+	// The split explains the probed number and nothing else: once an override
+	// or a loaded window decides the figure, `786,432 / 4 slots` no longer
+	// describes it.
+	const contextWindowSlots =
+		source === "probe" &&
+		probedContextSlots !== null &&
+		Math.floor(probedContextSlots.totalContextSize / probedContextSlots.slots) === effective
+			? probedContextSlots
+			: null;
+
 	return {
 		declaredContextWindow,
 		probedContextWindow,
@@ -714,6 +750,7 @@ export function resolveContextWindowDetails(
 		desiredContextWindow: desired,
 		effectiveContextWindow: effective,
 		contextWindowSource: source,
+		contextWindowSlots,
 		warning,
 		provenanceNotice,
 	};

package/src/domains/providers/runtimes/common/probe-helpers.ts

@@ -1,5 +1,6 @@
 import { probeHttp, probeJson } from "../../probe/http.js";
 import type { CapabilityFlags } from "../../types/capability-flags.js";
+import { type ContextWindowSlots, formatContextWindowSlots } from "../../types/context-window-slots.js";
 import type { ProbeContext, ProbeModelStatus, ProbeResult } from "../../types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../../types/target-descriptor.js";
 
@@ -88,7 +89,15 @@ export async function probeOpenAIModelCatalog(
 			// A reported loaded context is itself the residency answer: nothing
 			// serves a window for a model it has not loaded.
 			(loadedContext !== undefined ? { state: "loaded" as const } : undefined);
-		if (state) modelStates[row.id] = loadedContext === undefined ? state : { ...state, contextLength: loadedContext };
+		// The slot split rides on the load-state record because it is the same
+		// kind of fact: how this server is serving this model. A row with no
+		// recognized state still gets one, as `unknown`, so the split is kept
+		// without claiming residency the server did not report.
+		const contextSlots = contextSlotsFromEntry(row) ?? (detailRow ? contextSlotsFromEntry(detailRow) : undefined);
+		const withSlots = contextSlots ? { ...(state ?? { state: "unknown" as const }), contextSlots } : state;
+		if (withSlots) {
+			modelStates[row.id] = loadedContext === undefined ? withSlots : { ...withSlots, contextLength: loadedContext };
+		}
 	}
 	return { models, modelCapabilities, modelStates };
 }
@@ -159,7 +168,15 @@ function normalizeModelState(raw: string | undefined): ProbeModelStatus["state"]
 	if (!value) return undefined;
 	if (value === "loaded" || value === "ready" || value === "running" || value === "active") return "loaded";
 	if (value === "loading" || value === "pending" || value === "queued" || value === "starting") return "loading";
-	if (value === "unloaded" || value === "not-loaded" || value === "idle" || value === "stopped") return "unloaded";
+	if (
+		value === "unloaded" ||
+		value === "not-loaded" ||
+		value === "idle" ||
+		value === "sleeping" ||
+		value === "stopped"
+	) {
+		return "unloaded";
+	}
 	if (value === "failed" || value === "error" || value === "errored") return "failed";
 	if (value === "unknown") return "unknown";
 	return undefined;
@@ -203,12 +220,16 @@ function statusArgsFromEntry(row: Record<string, unknown>): string[] {
 	return argsFromStatus(status);
 }
 
+function contextSlotsFromEntry(row: Record<string, unknown>): ContextWindowSlots | undefined {
+	return llamaCppRequestContextWindow(parseLlamaCppServerFlags(statusArgsFromEntry(row)))?.slots;
+}
+
 function capabilitiesFromOpenAIModelEntry(row: Record<string, unknown>): Partial<CapabilityFlags> {
 	const caps: Partial<CapabilityFlags> = {};
 	const meta = nestedRecord(row, "meta");
 	const flags = parseLlamaCppServerFlags(statusArgsFromEntry(row));
 	const contextWindow =
-		positiveNumber(flags.contextSize) ??
+		llamaCppRequestContextWindow(flags)?.contextWindow ??
 		firstPositiveNumber(row, [
 			// What is actually loaded outranks what the model could support: a
 			// model served at 8k out of a possible 262k has an 8k window today,
@@ -310,10 +331,43 @@ export interface LlamaCppServerFlags {
 	topK?: number;
 	nGpuLayers?: number;
 	parallel?: number;
+	/** `--kv-unified` / `-kvu` true, `--no-kv-unified` false, absent when neither was given. */
+	kvUnified?: boolean;
 	mmproj?: string;
 	chatTemplateKwargs?: string;
 }
 
+export interface LlamaCppRequestContextWindow {
+	/** What one request can use. */
+	contextWindow: number;
+	/** Present when `contextWindow` is a quotient of the server's total. */
+	slots?: ContextWindowSlots;
+}
+
+/**
+ * The window one request actually gets from a llama.cpp server.
+ *
+ * `--ctx-size` is the total KV budget of the process. Without `--kv-unified`
+ * the server splits it evenly across `--parallel` slots, so a router started
+ * with `--ctx-size 786432 --parallel 4 --no-kv-unified` admits 196,608 tokens
+ * per request while reporting 786,432 as its context size. Reading the total
+ * as the window armed autocompact at a number the server would never admit
+ * and walked a long session into a hard context failure with the meter at
+ * 25% (issue #187). With `--kv-unified` every slot shares one sequence and
+ * the total is the window.
+ */
+export function llamaCppRequestContextWindow(flags: LlamaCppServerFlags): LlamaCppRequestContextWindow | undefined {
+	const total = positiveNumber(flags.contextSize);
+	if (total === undefined) return undefined;
+	const parallel = positiveNumber(flags.parallel);
+	if (parallel === undefined || parallel <= 1 || flags.kvUnified === true) return { contextWindow: Math.floor(total) };
+	const slots = Math.floor(parallel);
+	return {
+		contextWindow: Math.floor(total / slots),
+		slots: { totalContextSize: Math.floor(total), slots },
+	};
+}
+
 export interface LlamaCppStatusEnrichment {
 	discoveredCapabilities?: Partial<CapabilityFlags>;
 	modelId?: string;
@@ -329,22 +383,37 @@ function argsFromStatus(status: unknown): string[] {
 	return [];
 }
 
-function valueAfter(args: ReadonlyArray<string>, flag: string): string | undefined {
-	const index = args.indexOf(flag);
-	if (index < 0) return undefined;
-	const value = args[index + 1];
-	return value && !value.startsWith("--") ? value : undefined;
+/** `-1` is a value (`--reasoning-budget -1`); `-np` and `--jinja` are flags. */
+function looksLikeFlag(token: string): boolean {
+	return token.startsWith("-") && Number.isNaN(Number(token));
 }
 
-function numberFlag(args: ReadonlyArray<string>, flag: string): number | undefined {
-	const value = valueAfter(args, flag);
+/**
+ * The value after the first of `flags` present, or undefined. A token that
+ * reads as the next flag is not a value, which is how boolean flags read as
+ * present-without-value. Short spellings (`-c`, `-np`) come after the long
+ * one so the long form wins when both are given.
+ */
+function valueAfter(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): string | undefined {
+	for (const flag of flags) {
+		const index = args.indexOf(flag);
+		if (index < 0) continue;
+		const value = args[index + 1];
+		return value && !looksLikeFlag(value) ? value : undefined;
+	}
+	return undefined;
+}
+
+function numberFlag(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): number | undefined {
+	const value = valueAfter(args, ...flags);
 	if (value === undefined) return undefined;
 	const parsed = Number(value);
 	return Number.isFinite(parsed) ? parsed : undefined;
 }
 
-function booleanFlag(args: ReadonlyArray<string>, flag: string): boolean | undefined {
-	if (!args.includes(flag)) return undefined;
+function booleanFlag(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string>): boolean | undefined {
+	const flag = flags.find((candidate) => args.includes(candidate));
+	if (flag === undefined) return undefined;
 	const value = valueAfter(args, flag);
 	if (value === undefined) return true;
 	const normalized = value.toLowerCase();
@@ -353,9 +422,9 @@ function booleanFlag(args: ReadonlyArray<string>, flag: string): boolean | undef
 	return undefined;
 }
 
-function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
+export function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
 	const flags: LlamaCppServerFlags = {};
-	const ctxSize = numberFlag(args, "--ctx-size");
+	const ctxSize = numberFlag(args, "--ctx-size", "-c");
 	if (ctxSize !== undefined) flags.contextSize = ctxSize;
 	const maxTokens = numberFlag(args, "--n-predict");
 	if (maxTokens !== undefined) flags.maxTokens = maxTokens;
@@ -375,8 +444,14 @@ function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFl
 	if (topK !== undefined) flags.topK = topK;
 	const nGpuLayers = numberFlag(args, "--n-gpu-layers");
 	if (nGpuLayers !== undefined) flags.nGpuLayers = nGpuLayers;
-	const parallel = numberFlag(args, "--parallel");
+	const parallel = numberFlag(args, "--parallel", "-np");
 	if (parallel !== undefined) flags.parallel = parallel;
+	// The negative spelling is its own flag, and the last one given wins, which
+	// is how llama.cpp itself resolves a repeated boolean option.
+	const kvUnifiedAt = Math.max(args.lastIndexOf("--kv-unified"), args.lastIndexOf("-kvu"));
+	const noKvUnifiedAt = args.lastIndexOf("--no-kv-unified");
+	if (noKvUnifiedAt > kvUnifiedAt) flags.kvUnified = false;
+	else if (kvUnifiedAt >= 0) flags.kvUnified = booleanFlag(args, "--kv-unified", "-kvu") ?? true;
 	const cacheTypeK = valueAfter(args, "--cache-type-k");
 	if (cacheTypeK) flags.cacheTypeK = cacheTypeK;
 	const cacheTypeV = valueAfter(args, "--cache-type-v");
@@ -418,7 +493,8 @@ export async function probeLlamaCppModelStatus(
 	if (args.length === 0) return { notes: statusNotes(selected.id, selected.status) };
 	const flags = parseLlamaCppServerFlags(args);
 	const caps: Partial<CapabilityFlags> = {};
-	if (flags.contextSize !== undefined && flags.contextSize > 0) caps.contextWindow = flags.contextSize;
+	const window = llamaCppRequestContextWindow(flags);
+	if (window !== undefined) caps.contextWindow = window.contextWindow;
 	if (flags.maxTokens !== undefined && flags.maxTokens > 0) caps.maxTokens = flags.maxTokens;
 	if (flags.reasoning === true || flags.reasoningBudget !== undefined) caps.reasoning = true;
 	if (flags.mmproj) caps.vision = true;
@@ -426,6 +502,11 @@ export async function probeLlamaCppModelStatus(
 	const enrichment: LlamaCppStatusEnrichment = { modelId: selected.id, serverFlags: flags };
 	if (Object.keys(caps).length > 0) enrichment.discoveredCapabilities = caps;
 	const notes = statusNotes(selected.id, selected.status);
+	if (window?.slots) {
+		notes.push(
+			`${selected.id} context window ${formatContextWindowSlots(window.contextWindow, window.slots)}: --ctx-size is split across --parallel slots without --kv-unified`,
+		);
+	}
 	if (notes.length > 0) enrichment.notes = notes;
 	return enrichment;
 }

package/src/domains/providers/types/context-window-slots.ts

@@ -0,0 +1,18 @@
+/**
+ * A server that shares one KV budget across request slots serves each request
+ * a quotient of it. llama.cpp splits `--ctx-size` evenly across `--parallel`
+ * slots unless `--kv-unified`, so a router started with `--ctx-size 786432
+ * --parallel 4 --no-kv-unified` admits 196,608 tokens per request. The total
+ * and the slot count are kept beside the quotient so the operator surfaces can
+ * say where the number came from.
+ */
+export interface ContextWindowSlots {
+	totalContextSize: number;
+	slots: number;
+}
+
+/** `196,608 (786,432 / 4 slots)`: the per-request window with its derivation. */
+export function formatContextWindowSlots(contextWindow: number, slots: ContextWindowSlots): string {
+	const format = (n: number): string => Math.round(n).toLocaleString("en-US");
+	return `${format(contextWindow)} (${format(slots.totalContextSize)} / ${slots.slots} slots)`;
+}

package/src/domains/providers/types/runtime-descriptor.ts

@@ -1,6 +1,6 @@
 import type { Api, Model } from "../../../engine/types.js";
-
 import type { CapabilityFlags } from "./capability-flags.js";
+import type { ContextWindowSlots } from "./context-window-slots.js";
 import type { CompleteOptions, CompletionChunk, EmbedResult, InfillOptions, RerankResult } from "./inference.js";
 import type { KnowledgeBaseHit } from "./knowledge-base.js";
 import type { TargetDescriptor } from "./target-descriptor.js";
@@ -61,6 +61,8 @@ export type ProbeModelLoadState = "loaded" | "loading" | "unloaded" | "failed" |
 export interface ProbeModelStatus {
 	state: ProbeModelLoadState;
 	detail?: string;
+	/** The per-request window is `totalContextSize / slots`; absent when the server does not split. */
+	contextSlots?: ContextWindowSlots;
 	/**
 	 * Context the runtime has this model loaded at, when it reports one. LM
 	 * Studio serves a loaded instance at whatever window it was opened with,

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);
 }