@iowarp/clio-coder 0.4.3 → 0.4.4

package/src/tools/decide.ts

@@ -0,0 +1,136 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { DecisionBoardStore } from "../domains/session/decision-board.js";
+import { decisionRef } from "../domains/session/entries.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { byteLength } from "./truncate-utf8.js";
+
+/**
+ * The model's own design decisions, recorded on the session decision board
+ * beside the operator's `ask_user` answers. A `decide` call appends one
+ * `decisionLedger` entry with `origin: "agent"` and one `DecisionRecord` with
+ * `source: "agent"`, the alternatives the model rejected, and why. Dispatch
+ * seals every active decision's ref onto the run envelope and receipt, and
+ * the commit seams turn the same refs into `Clio-Decision:` trailers, so a
+ * receipt or a commit names the choices it was made under.
+ */
+
+export const DECIDE_CAPS = Object.freeze({
+	keyBytes: 64,
+	valueBytes: 512,
+	alternatives: 6,
+	alternativeBytes: 256,
+	rationaleBytes: 1024,
+	labelBytes: 128,
+});
+
+const KEBAB_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+export interface DecideToolDeps {
+	decisionBoard?: DecisionBoardStore;
+}
+
+function boundedText(value: unknown, field: string, cap: number): string | Error {
+	if (typeof value !== "string") return new Error(`decide: ${field} must be a string`);
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return new Error(`decide: ${field} is required`);
+	if (byteLength(trimmed) > cap) return new Error(`decide: ${field} exceeds the ${cap}-byte cap`);
+	return trimmed;
+}
+
+function boundedAlternatives(value: unknown): string[] | Error {
+	if (!Array.isArray(value) || value.length === 0) {
+		return new Error("decide: alternatives must list at least one option you rejected");
+	}
+	if (value.length > DECIDE_CAPS.alternatives) {
+		return new Error(`decide: alternatives exceeds the ${DECIDE_CAPS.alternatives}-entry cap`);
+	}
+	const alternatives: string[] = [];
+	for (const [index, entry] of value.entries()) {
+		const text = boundedText(entry, `alternatives[${index}]`, DECIDE_CAPS.alternativeBytes);
+		if (text instanceof Error) return text;
+		alternatives.push(text);
+	}
+	return alternatives;
+}
+
+export function createDecideTool(deps: DecideToolDeps = {}): ToolSpec {
+	return {
+		name: ToolNames.Decide,
+		description:
+			"Record a design decision you made between two or more viable options, with the alternatives you rejected and why. Call it before implementing the choice; a later call with the same key supersedes the earlier record.",
+		parameters: Type.Object({
+			key: Type.String({
+				description: `Stable kebab-case name for the decision, e.g. "cache-key-shape" (at most ${DECIDE_CAPS.keyBytes} bytes).`,
+			}),
+			value: Type.String({ description: `The option you chose (at most ${DECIDE_CAPS.valueBytes} bytes).` }),
+			alternatives: Type.Array(Type.String(), {
+				description: `Options you considered and rejected, 1 to ${DECIDE_CAPS.alternatives} entries.`,
+			}),
+			rationale: Type.String({
+				description: `Why the chosen option won over the alternatives (at most ${DECIDE_CAPS.rationaleBytes} bytes).`,
+			}),
+			label: Type.Optional(Type.String({ description: "Short human-readable title for the decision." })),
+		}),
+		// Read class on purpose: the only effect is one session-ledger append,
+		// so it must stay available at every autonomy level without a prompt.
+		baseActionClass: "read",
+		executionMode: "sequential",
+		async run(args): Promise<ToolResult> {
+			const key = boundedText(args.key, "key", DECIDE_CAPS.keyBytes);
+			if (key instanceof Error) return { kind: "error", message: key.message };
+			if (!KEBAB_KEY.test(key)) {
+				return { kind: "error", message: "decide: key must be kebab-case (lowercase letters, digits, single hyphens)" };
+			}
+			const value = boundedText(args.value, "value", DECIDE_CAPS.valueBytes);
+			if (value instanceof Error) return { kind: "error", message: value.message };
+			const alternatives = boundedAlternatives(args.alternatives);
+			if (alternatives instanceof Error) return { kind: "error", message: alternatives.message };
+			const rationale = boundedText(args.rationale, "rationale", DECIDE_CAPS.rationaleBytes);
+			if (rationale instanceof Error) return { kind: "error", message: rationale.message };
+			let label: string | undefined;
+			if (args.label !== undefined && args.label !== null) {
+				const bounded = boundedText(args.label, "label", DECIDE_CAPS.labelBytes);
+				if (bounded instanceof Error) return { kind: "error", message: bounded.message };
+				label = bounded;
+			}
+			if (deps.decisionBoard === undefined) {
+				return { kind: "error", message: "decide: no session decision board is available in this context" };
+			}
+			let outcome: ReturnType<DecisionBoardStore["recordAgentDecision"]>;
+			try {
+				outcome = deps.decisionBoard.recordAgentDecision({
+					key,
+					value,
+					alternatives,
+					rationale,
+					...(label !== undefined ? { label } : {}),
+				});
+			} catch (error) {
+				return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+			}
+			const ref = decisionRef(outcome.entry.interviewId, key);
+			const supersededNote =
+				outcome.superseded === null
+					? ""
+					: ` (supersedes ${decisionRef(outcome.superseded.interviewId, outcome.superseded.key)})`;
+			return {
+				kind: "ok",
+				output: `decision recorded: ${key} = ${value} [${ref}]${supersededNote}\n`,
+				details: {
+					decision: {
+						ref,
+						key,
+						value,
+						alternatives,
+						rationale,
+						...(label !== undefined ? { label } : {}),
+						...(outcome.superseded !== null
+							? { superseded: decisionRef(outcome.superseded.interviewId, outcome.superseded.key) }
+							: {}),
+					},
+				},
+			};
+		},
+	};
+}

package/src/tools/dispatch-admission.ts

@@ -246,6 +246,27 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 							argv: [...check.command],
 							cwd: resolve(process.cwd(), check.cwd),
 							timeoutMs: entry.timeoutMs,
+							// A judged check seals its kind and absolute file paths here, so
+							// host verification judges against what the catalog declared at
+							// admission rather than whatever the file says at run time.
+							...(check.kind !== "command" ? { kind: check.kind } : {}),
+							...(check.numeric !== undefined
+								? {
+										numeric: {
+											reference: resolve(process.cwd(), check.numeric.reference),
+											tolerance: { ...check.numeric.tolerance },
+										},
+									}
+								: {}),
+							...(check.perf !== undefined
+								? {
+										perf: {
+											...(check.perf.budget !== undefined ? { budget: structuredClone(check.perf.budget) } : {}),
+											...(check.perf.baseline !== undefined ? { baseline: resolve(process.cwd(), check.perf.baseline) } : {}),
+											...(check.perf.tolerance !== undefined ? { tolerance: { ...check.perf.tolerance } } : {}),
+										},
+									}
+								: {}),
 						};
 					}),
 				};

package/src/tools/dispatch-plan.ts

@@ -487,7 +487,7 @@ function renderPlanText(
 		lines.push(...renderLegacyPathScope(task, cwd));
 		for (const check of task.resolvedVerification ?? []) {
 			lines.push(
-				`    verification check=${safeField(check.check)} argv=${JSON.stringify(check.argv)} cwd=${JSON.stringify(check.cwd)} timeout_ms=${check.timeoutMs}`,
+				`    verification check=${safeField(check.check)}${check.kind !== undefined ? ` kind=${check.kind}` : ""} argv=${JSON.stringify(check.argv)} cwd=${JSON.stringify(check.cwd)} timeout_ms=${check.timeoutMs}`,
 			);
 		}
 	}
@@ -616,7 +616,10 @@ function isResolvedTask(value: unknown): value is ResolvedDispatchPlanArtifact["
 					Array.isArray(check.argv) &&
 					check.argv.every((arg) => typeof arg === "string") &&
 					typeof check.cwd === "string" &&
-					typeof check.timeoutMs === "number",
+					typeof check.timeoutMs === "number" &&
+					(check.kind === undefined || check.kind === "numeric-compare" || check.kind === "perf-budget") &&
+					(check.numeric === undefined || (isRecord(check.numeric) && typeof check.numeric.reference === "string")) &&
+					(check.perf === undefined || isRecord(check.perf)),
 			))
 	)
 		return false;

package/src/tools/dispatch-runner.ts

@@ -50,6 +50,7 @@ import { extractRunProvenance, provenanceCompactSuffix } from "../domains/eviden
 import { summarizeTrustStatus } from "../domains/evidence/trust-projection.js";
 import { adaptRunReceiptTrustStatus } from "../domains/evidence/trust-status.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+import { activeDecisionRefs } from "../domains/session/decision-board.js";
 import {
 	type CandidateWorktree,
 	type CompeteGroupOwnership,
@@ -802,6 +803,7 @@ async function runReviewGated(
 				...(review.target !== undefined ? { target: review.target } : {}),
 				...(base.plan !== undefined ? { plan: base.plan } : {}),
 				...(base.parentToolCallId !== undefined ? { parentToolCallId: base.parentToolCallId } : {}),
+				...(base.decisionRefs !== undefined ? { decisionRefs: base.decisionRefs } : {}),
 				...(base.reservation !== undefined
 					? { reservation: { ownerId: base.reservation.ownerId, memberId: base.reservation.memberId } }
 					: {}),
@@ -1334,7 +1336,11 @@ async function runCompete(
 				const receipt = candidateRuns[index]?.receipt;
 				const failed = receipt !== undefined && isPipelineStepFailure(receipt);
 				if (failed) return "builder failed";
-				commitCandidateWork(worktree, `clio-coder compete ${group} candidate ${worktree.index}`);
+				// The receipt records the candidate's effective authority after recipe
+				// and invocation narrowing, independently of the coordinator's autonomy.
+				if (receipt?.autonomyEnforcement?.autonomy !== "read-only") {
+					commitCandidateWork(worktree, `clio-coder compete ${group} candidate ${worktree.index}`);
+				}
 				return candidateDiffStat(root, worktree.branch);
 			});
 			if (candidateRuns.every((run) => isPipelineStepFailure(run.receipt))) {
@@ -1367,6 +1373,7 @@ async function runCompete(
 				...(compete.judge?.node !== undefined ? { node: compete.judge.node } : {}),
 				...(base.plan !== undefined ? { plan: base.plan } : {}),
 				...(base.parentToolCallId !== undefined ? { parentToolCallId: base.parentToolCallId } : {}),
+				...(base.decisionRefs !== undefined ? { decisionRefs: base.decisionRefs } : {}),
 				...(base.reservation !== undefined
 					? { reservation: { ownerId: base.reservation.ownerId, memberId: base.reservation.memberId } }
 					: {}),
@@ -2010,6 +2017,7 @@ async function runCouncil(
 			...(council.judge?.node ? { node: council.judge.node } : {}),
 			...(base.plan ? { plan: base.plan } : {}),
 			...(base.parentToolCallId ? { parentToolCallId: base.parentToolCallId } : {}),
+			...(base.decisionRefs !== undefined ? { decisionRefs: base.decisionRefs } : {}),
 		};
 		const pinned = council.resolvedTasks?.find((task) => task.role === "synthesis");
 		const judgeRun = await runMember(
@@ -2189,6 +2197,12 @@ export async function runDispatchTool(
 		parentToolCallId === undefined || parentToolCallId.length === 0
 			? structuredClone(snapshot.requests)
 			: snapshot.requests.map((request) => ({ ...structuredClone(request), parentToolCallId }));
+	// Seal the parent board's active decisions onto every request on the same
+	// terms as the parent id: from the live board here, never from model
+	// arguments (the validation projection strips the field). Derived reviewer,
+	// judge, and synthesis requests copy it from their base explicitly.
+	const decisionRefs = activeDecisionRefs(deps.getDecisionBoard?.() ?? []);
+	if (decisionRefs.length > 0) requests = requests.map((request) => ({ ...request, decisionRefs }));
 	if (planView.planScale && deps.dispatch.preview !== undefined && resolvedPlan === null) {
 		return { kind: "error", message: "dispatch: resolved plan is missing after admission" };
 	}

package/src/tools/dispatch-types.ts

@@ -3,6 +3,7 @@ import type { AgentSpec } from "../domains/agents/spec.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
 import type {
 	CandidateWorktree,
 	CompeteGroupOwnership,
@@ -108,4 +109,9 @@ export interface DispatchToolDeps {
 	getWorkerRosters?: () => Readonly<Record<string, { members: ReadonlyArray<DispatchCouncilMember> }>>;
 	/** Which optional schema blocks this session advertises; absent means every block. */
 	getSchemaComposition?: () => DispatchSchemaComposition;
+	/**
+	 * Live decision board snapshot. Every request the tool builds carries the
+	 * active decisions' refs, sealed here and never from model arguments.
+	 */
+	getDecisionBoard?: () => ReadonlyArray<DecisionLedgerEntry>;
 }

package/src/tools/evidence.ts

@@ -0,0 +1,96 @@
+import { Type } from "typebox";
+import { assertSafeId } from "../core/safe-id.js";
+import { ToolNames } from "../core/tool-names.js";
+import { clioDataDir, clioStateDir } from "../core/xdg.js";
+import { StringEnum } from "../engine/ai.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { truncateUtf8 } from "./truncate-utf8.js";
+
+export const EVIDENCE_TOOL_MAX_BYTES = 16_384;
+
+/** Keep truncated results valid JSON and never hide an unbounded copy in details. */
+function boundedResult(value: unknown): ToolResult {
+	const serialized = JSON.stringify(value, null, 2);
+	if (Buffer.byteLength(serialized, "utf8") <= EVIDENCE_TOOL_MAX_BYTES) {
+		return { kind: "ok", output: serialized, details: { truncated: false } };
+	}
+	const hint = "Inspect one run to narrow the output; this preview is incomplete JSON text.";
+	let preview = truncateUtf8(serialized, EVIDENCE_TOOL_MAX_BYTES, "");
+	let output = JSON.stringify({ truncated: true, hint, preview });
+	while (Buffer.byteLength(output, "utf8") > EVIDENCE_TOOL_MAX_BYTES) {
+		const excess = Buffer.byteLength(output, "utf8") - EVIDENCE_TOOL_MAX_BYTES;
+		preview = truncateUtf8(preview, Math.max(0, Buffer.byteLength(preview, "utf8") - excess), "");
+		output = JSON.stringify({ truncated: true, hint, preview });
+	}
+	return { kind: "ok", output, details: { truncated: true } };
+}
+
+export const evidenceTool: ToolSpec = {
+	name: ToolNames.Evidence,
+	description:
+		"Read canonical evidence as JSON. List recent bundles, inspect a bundle's overview, trust axes and tier, gate decisions, and findings, or build/read evidence for a run.",
+	parameters: Type.Object({
+		mode: StringEnum(["list", "inspect", "run"]),
+		id: Type.Optional(Type.String({ description: "Evidence bundle id for inspect." })),
+		runId: Type.Optional(Type.String({ description: "Run id for run." })),
+	}),
+	baseActionClass: "read",
+	// Run mode may materialize a derived bundle in Clio's data directory.
+	executionMode: "sequential",
+	async run(args): Promise<ToolResult> {
+		const mode = args.mode;
+		if (mode !== "list" && mode !== "inspect" && mode !== "run") {
+			return { kind: "error", message: "evidence: mode must be list, inspect, or run" };
+		}
+		try {
+			const dataDir = clioDataDir();
+			if (mode === "list") {
+				const { evidenceInventorySnapshot } = await import("../domains/evidence/inventory.js");
+				return boundedResult(await evidenceInventorySnapshot(Date.now, dataDir));
+			}
+			const id = mode === "inspect" ? args.id : args.runId;
+			if (typeof id !== "string" || id.length === 0) {
+				return { kind: "error", message: `evidence: ${mode} requires ${mode === "inspect" ? "id" : "runId"}` };
+			}
+			assertSafeId(id, mode === "inspect" ? "evidence" : "run");
+			const { buildEvidence, EvidenceNotFoundError, inspectEvidence, loadEvidenceGateDecisions } = await import(
+				"../domains/evidence/index.js"
+			);
+			const { evidenceDetailSnapshot } = await import("../domains/evidence/detail.js");
+			let evidenceId = mode === "run" ? `run-${id}` : id;
+			let inspected: Awaited<ReturnType<typeof inspectEvidence>>;
+			try {
+				inspected = await inspectEvidence(dataDir, evidenceId);
+			} catch (error) {
+				if (mode !== "run" || !(error instanceof EvidenceNotFoundError)) throw error;
+				try {
+					evidenceId = (await buildEvidence({ dataDir, stateDir: clioStateDir(), runId: id })).evidenceId;
+				} catch (buildError) {
+					if (
+						buildError instanceof Error &&
+						(buildError.message === "run ledger not found" || buildError.message === `run not found: ${id}`)
+					)
+						throw new EvidenceNotFoundError(evidenceId);
+					throw buildError;
+				}
+				inspected = await inspectEvidence(dataDir, evidenceId);
+			}
+			return boundedResult({
+				...inspected,
+				...(await evidenceDetailSnapshot(evidenceId, Date.now, dataDir)),
+				gateDecisions: await loadEvidenceGateDecisions(dataDir, evidenceId),
+			});
+		} catch (error) {
+			const absent = error instanceof Error && error.name === "EvidenceNotFoundError";
+			return {
+				kind: "error",
+				message: truncateUtf8(
+					`evidence: ${error instanceof Error ? error.message : String(error)}`,
+					EVIDENCE_TOOL_MAX_BYTES - 3,
+					"...",
+				),
+				details: { code: absent ? "artifact_absent" : "evidence_error", artifactAbsent: absent },
+			};
+		}
+	},
+};

package/src/tools/limitation.ts

@@ -0,0 +1,76 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import { StringEnum } from "../engine/ai.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+
+/**
+ * The typed limitation signal the finish contract reads. Calling the tool
+ * records a `limitation` tool_call and tool_result pair in the session ledger,
+ * and that successful receipt is what `assessFinishContract` accepts in place
+ * of validation evidence. The tool is pure: it touches no filesystem and runs
+ * no shell, so the receipt itself is its whole effect.
+ */
+
+export const LIMITATION_REASONS = ["no-runner", "blocked", "out-of-scope", "environment", "other"] as const;
+
+export type LimitationReason = (typeof LIMITATION_REASONS)[number];
+
+export interface LimitationRecord {
+	scope: string;
+	reason: LimitationReason;
+	paths: string[];
+}
+
+function isLimitationReason(value: unknown): value is LimitationReason {
+	return typeof value === "string" && (LIMITATION_REASONS as ReadonlyArray<string>).includes(value);
+}
+
+function trimString(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizePaths(value: unknown): string[] | null {
+	if (value === undefined || value === null) return [];
+	if (!Array.isArray(value)) return null;
+	const paths: string[] = [];
+	for (const item of value) {
+		const path = trimString(item);
+		if (path === null) return null;
+		if (!paths.includes(path)) paths.push(path);
+	}
+	return paths;
+}
+
+export const limitationTool: ToolSpec = {
+	name: ToolNames.Limitation,
+	description:
+		"Record what this turn could not verify and why. Call it once, before your final reply, when you changed files but could not run validation; the receipt stands in for validation evidence at the finish gate.",
+	parameters: Type.Object({
+		scope: Type.String({ description: "What could not be verified, in one sentence." }),
+		reason: StringEnum(LIMITATION_REASONS, {
+			description:
+				"no-runner: no test or build runner is available; blocked: a safety gate or denial stopped the check; out-of-scope: verification was excluded by the task; environment: the environment cannot run the check; other.",
+		}),
+		paths: Type.Optional(Type.Array(Type.String(), { description: "Repository-relative paths left unverified." })),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+	async run(args): Promise<ToolResult> {
+		const scope = trimString(args.scope);
+		if (scope === null) return { kind: "error", message: "limitation: scope is required" };
+		if (!isLimitationReason(args.reason)) {
+			return { kind: "error", message: `limitation: reason must be one of ${LIMITATION_REASONS.join(", ")}` };
+		}
+		const paths = normalizePaths(args.paths);
+		if (paths === null) return { kind: "error", message: "limitation: paths must be an array of non-empty strings" };
+		const limitation: LimitationRecord = { scope, reason: args.reason, paths };
+		const pathSuffix = paths.length > 0 ? ` paths=${paths.join(",")}` : "";
+		return {
+			kind: "ok",
+			output: `limitation recorded: ${scope} (reason=${limitation.reason}${pathSuffix})\n`,
+			details: { limitation },
+		};
+	},
+};

package/src/tools/policy.ts

@@ -21,6 +21,7 @@ interface PlaneExpectation {
 
 /** One row per registered tool: plane, action class, and concurrency rule. */
 export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> = {
+	[ToolNames.Evidence]: { plane: "observe", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Read]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Grep]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
@@ -53,6 +54,14 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	// panes. It mutates no workspace, so it stays read class; sequential because
 	// two pane operations in one batch would race the same pane registry.
 	[ToolNames.Panes]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	// limitation records a typed receipt in the session ledger and nothing
+	// else: no filesystem, no shell. Read class so it never trips a safety
+	// gate; parallel because the call is pure and idempotent.
+	[ToolNames.Limitation]: { plane: "orchestrate", actionClass: "read", executionMode: "parallel" },
+	// decide appends one decision-board entry to the session ledger and
+	// nothing else. Read class so it never trips a safety gate; sequential so
+	// two decisions in one batch never race the supersede lookup.
+	[ToolNames.Decide]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" },

package/src/tools/presentation.ts

@@ -50,6 +50,7 @@ const FOLDED_WITH_DIFF: ToolPresentationPolicy = {
  * tools, folds the same way.
  */
 export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>> = {
+	[ToolNames.Evidence]: FOLDED,
 	[ToolNames.Read]: FOLDED,
 	[ToolNames.Grep]: FOLDED,
 	[ToolNames.Find]: FOLDED,
@@ -68,6 +69,8 @@ export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>>
 	[ToolNames.Tasks]: FOLDED,
 	[ToolNames.Ledger]: FOLDED,
 	[ToolNames.Panes]: FOLDED,
+	[ToolNames.Limitation]: FOLDED,
+	[ToolNames.Decide]: FOLDED,
 	[ToolNames.WebFetch]: FOLDED,
 	[ToolNames.AskUser]: FOLDED,
 	[ToolNames.Artifact]: FOLDED,

package/src/tools/registry.ts

@@ -1099,7 +1099,7 @@ function skillSurfaceBlockedVerdict(
 	const reason =
 		violation.disallowedBy.length > 0
 			? `${tool} is disallowed by the active skill(s) ${violation.disallowedBy.join(", ")} (disallowed-tools). ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`
-			: `${tool} is outside the tool surface declared by the active skill(s) ${violation.skills.join(", ")}. Tools are narrowed to: ${(violation.mergedAllowedTools ?? []).join(", ")} (plus context and ask_user). ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`;
+			: `${tool} is outside the tool surface declared by the active skill(s) ${violation.skills.join(", ")}. Tools are narrowed to: ${(violation.mergedAllowedTools ?? []).join(", ")} (plus context and ask_user). The limitation receipt is also available unless explicitly disallowed. ${lifetime} Work within the skill workflow; if it genuinely needs this step, use ask_user when available or state the blocker in your reply.`;
 	const blocked: SafetyDecision = {
 		kind: "block",
 		classification: decision.classification,

package/src/tools/result-shaping.ts

@@ -127,11 +127,17 @@ function offloadBody(text: string, bytes: number, maxBytes: number): string {
 	return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
 }
 
+export interface ToolOffloadSweepResult {
+	removed: number;
+	skipped: number;
+}
+
 /** Remove regular offload files older than the boot retention cap. */
-export function sweepExpiredToolOffloads(now = Date.now()): number {
+export function sweepExpiredToolOffloads(now = Date.now()): ToolOffloadSweepResult {
 	const root = join(clioStateDir(), "scratch");
 	const cutoff = now - TOOL_OFFLOAD_MAX_AGE_MS;
 	let removed = 0;
+	let skipped = 0;
 	try {
 		for (const session of readdirSync(root, { withFileTypes: true })) {
 			if (!session.isDirectory()) continue;
@@ -143,14 +149,20 @@ export function sweepExpiredToolOffloads(now = Date.now()): number {
 					if (statSync(path).mtimeMs >= cutoff) continue;
 					rmSync(path, { force: true });
 					removed += 1;
-				} catch {}
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+				}
 			}
 			try {
 				if (readdirSync(sessionDir).length === 0) rmdirSync(sessionDir);
-			} catch {}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+			}
 		}
-	} catch {}
-	return removed;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+	}
+	return { removed, skipped };
 }
 
 /**

package/src/tools/task-worktree.ts

@@ -57,9 +57,19 @@ export function isCanonicalWorktreePathInside(parent: string, candidate: string)
 	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 
-export function commitWorktreePath(path: string, identity: string, message: string): boolean {
-	git(path, ["add", "-A"]);
-	if (git(path, ["status", "--porcelain"]).length === 0) return false;
+export function commitWorktreePath(
+	path: string,
+	identity: string,
+	message: string,
+	excludedPaths: ReadonlyArray<string> = [],
+): boolean {
+	// Runtime state can already be staged by a worker. Reset only these exact
+	// index entries, leaving their working files and every authored path intact.
+	if (excludedPaths.length > 0) {
+		git(path, ["reset", "-q", "HEAD", "--", ...excludedPaths.map((entry) => `:(top,literal)${entry}`)]);
+	}
+	git(path, ["add", "-A", "--", ".", ...excludedPaths.map((entry) => `:(top,exclude,literal)${entry}`)]);
+	if (git(path, ["diff", "--cached", "--name-only", "-z"]).length === 0) return false;
 	git(path, [
 		"-c",
 		`user.name=${identity}`,

package/src/tools/tasks.ts

@@ -60,6 +60,10 @@ function renderTaskBoardText(board: TaskBoardSnapshot, userTasks: ReadonlyArray<
 		if (task.status === "blocked" && task.reason) line += ` — blocked: ${task.reason}`;
 		if (task.status === "cancelled" && task.reason) line += ` — dropped: ${task.reason}`;
 		lines.push(line);
+		const outputs = userTasks.find((item) => item.id === task.userTaskId)?.acceptance?.expectedOutputs;
+		if (outputs?.length) lines.push(`  expected outputs: ${outputs.join(", ")}`);
+		for (const item of task.requiredValidationEvidence ?? [])
+			lines.push(`  acceptance: ${item.command} (${item.status}; ${item.notes})`);
 	}
 	if (counts.open > 0 && counts.active === 0) {
 		lines.push(`next: start a task with action="start" before working it`);
@@ -210,7 +214,12 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 				if (userTask.status !== "open" && userTask.status !== "handed") {
 					return { kind: "error", message: `tasks: operator task ${id} is ${userTask.status}; it cannot be picked` };
 				}
-				const result = deps.board.apply({ op: "pick", title: userTask.title, userTaskId: userTask.id });
+				const result = deps.board.apply({
+					op: "pick",
+					title: userTask.title,
+					userTaskId: userTask.id,
+					...(userTask.acceptance ? { verification: userTask.acceptance.verification } : {}),
+				});
 				if (!result.ok) return { kind: "error", message: `tasks: ${result.message}` };
 				const picked = result.board.tasks.find((task) => task.userTaskId === userTask.id && task.status === "pending");
 				if (!picked) return { kind: "error", message: `tasks: durable pickup for ${id} did not produce a board row` };