@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/tools/delegate-tool.ts

@@ -2,6 +2,10 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../agents/agent.ts";
 import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { THINKING_LEVELS, isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
+import { validateParallelWriteSets } from "../core/ownership.ts";
+import { effortFullName } from "../core/leg-thinking.ts";
 import { END_TURN_NOTE } from "../core/brief.ts";
 import { fenceUntrusted } from "../core/fence.ts";
 import { Text, visibleWidth } from "@earendil-works/pi-tui";
@@ -16,7 +20,7 @@ import { expandDetailHint, failureDetails, isInline } from "../extension/shared.
 import {
 	DelegationLedger, type DelegateParams as DelegateCall, keyInputOf, nameFor, normalizeDelegateConcurrency,
 	shortModel, shouldRecordDelegationOutcome, specOf, unknownAgentError, unknownContractError,
-	validateDelegationBrief, validateParallelWriteSets, coerceDelegateParams,
+	validateDelegationBrief, coerceDelegateParams,
 } from "./delegate.ts";
 import { Semaphore } from "../orchestration/parallel.ts";
 import type { AgentRunSpec, SteerFn, StrategyEngine } from "../orchestration/sdk.ts";
@@ -24,7 +28,7 @@ import type { AgentResult } from "../orchestration/types.ts";
 import { sanitizeLabel } from "../extension/shared.ts";
 import type { PersonaController } from "../persona/controller.ts";
 import type { AgentTree } from "../ui/agent-tree.ts";
-import { buildCompletionReport, runDisplayName, type AsyncRunTracker } from "../engine/async.ts";
+import { buildCompletionReport, observedRunModel, runDisplayName, type AsyncRunTracker } from "../engine/async.ts";
 import type { BackgroundRuns } from "./background-run.ts";
 import { emptyUsage, type ProgressSnapshot, type ToolEvent } from "../engine/stream.ts";
 import { progressPatch } from "../ui/agent-tree.ts";
@@ -35,6 +39,8 @@ interface DelegateLaunchSnapshot {
 	label: string;
 	agent: string;
 	model?: string;
+	/** Effort THIS call declared in its args (spec-level); absent when the call declared none. */
+	thinking?: ThinkingLevel;
 }
 
 interface DelegateLaunchRow {
@@ -43,6 +49,7 @@ interface DelegateLaunchRow {
 	detailLabel: string;
 	agent: string;
 	model?: string;
+	thinking?: ThinkingLevel;
 	displayLabel: string;
 	clipped: boolean;
 	hasAlias: boolean;
@@ -57,6 +64,12 @@ interface CollapsedLaunchLine {
 
 const COLLAPSED_LAUNCH_ROWS = 3;
 
+/** One formatter for every launch-card metadata line: agent · model · FULL effort name —
+ * only the effort this call declared; `off` renders nothing (absence means off). */
+function launchRowMetadata(row: { agent?: string; model?: string; thinking?: ThinkingLevel }): string {
+	return [row.agent, row.model, row.thinking ? effortFullName(row.thinking) : ""].filter((value): value is string => !!value).join(" · ");
+}
+
 /** Prefer session-persisted identity, then recover old launch cards from the live tracker. */
 function launchRows(
 	details: { runId?: unknown; runIds?: unknown; runs?: unknown },
@@ -74,6 +87,7 @@ function launchRows(
 				label: run.label,
 				agent: run.agent,
 				...(typeof run.model === "string" ? { model: run.model } : {}),
+				...(isThinkingLevel(run.thinking) ? { thinking: run.thinking } : {}),
 			});
 		}
 	}
@@ -111,6 +125,7 @@ function launchRows(
 		label: sanitizeTerminalText(run.label),
 		agent: sanitizeTerminalText(run.agent),
 		...(run.model ? { model: sanitizeTerminalText(run.model) } : {}),
+		...(run.thinking ? { thinking: run.thinking } : {}),
 		fullName: runDisplayName(run),
 		hasAlias,
 	}));
@@ -120,7 +135,7 @@ function launchRows(
 		const duplicateSuffix = counts.get(row.fullName)! > 1 ? ` [${compactInlineText(row.id, { maxChars: 16 })}]` : "";
 		const detailLabel = `${row.label}${duplicateSuffix}`;
 		const displayLabel = compactInlineText(detailLabel, { maxChars: 80 });
-		const displayMetadata = [row.agent, row.model].filter((value): value is string => !!value).join(" · ");
+		const displayMetadata = launchRowMetadata(row);
 		return {
 			...row,
 			detailLabel,
@@ -141,7 +156,7 @@ function collapsedLaunchRows(rows: readonly DelegateLaunchRow[], dropped: number
 	];
 	const hintText = compactInlineText(expandDetailHint(), { maxChars: 32 });
 	const rowsNeedHint = rows.slice(0, visibleCount).some((row, index) => {
-		const metadata = [row.agent, row.model].filter((value): value is string => !!value).join(" · ");
+		const metadata = launchRowMetadata(row);
 		const prefixWidth = index === 0 ? visibleWidth("launched ") : visibleWidth("  ");
 		return row.clipped || prefixWidth + visibleWidth(row.displayLabel) + (metadata ? 3 + visibleWidth(metadata) : 0) > MAX_COLLAPSED_CARD_COLUMNS;
 	});
@@ -151,7 +166,7 @@ function collapsedLaunchRows(rows: readonly DelegateLaunchRow[], dropped: number
 		const prefix = index === 0 ? "launched " : "  ";
 		const fixedWidth = visibleWidth(prefix) + (index === visibleCount - 1 ? visibleWidth(suffix) : 0);
 		const budget = Math.max(16, MAX_COLLAPSED_CARD_COLUMNS - fixedWidth);
-		const metadata = [row.agent, row.model].filter((value): value is string => !!value).join(" · ");
+		const metadata = launchRowMetadata(row);
 		const metadataBudget = Math.min(36, visibleWidth(metadata));
 		const labelBudget = Math.max(16, budget - (metadata ? metadataBudget + 3 : 0));
 		const label = compactInlineText(row.displayLabel, { maxChars: labelBudget });
@@ -167,7 +182,7 @@ function collapsedLaunchRows(rows: readonly DelegateLaunchRow[], dropped: number
 
 function expandedLaunchDetails(text: string, rows: readonly DelegateLaunchRow[]): string {
 	if (rows.length === 0 || !rows.some((row) => row.hasAlias)) return text;
-	const diagnostics = rows.map((row) => `- ${[row.detailLabel, row.agent, row.model].filter((value): value is string => !!value).join(" · ")} [${row.id}]`).join("\n");
+	const diagnostics = rows.map((row) => `- ${[row.detailLabel, row.agent, row.model, row.thinking ? effortFullName(row.thinking) : ""].filter((value): value is string => !!value).join(" · ")} [${row.id}]`).join("\n");
 	return `${text}\n\nLaunched workers:\n${diagnostics}`;
 }
 
@@ -190,7 +205,7 @@ function singleLaunchReceipt(row: DelegateLaunchRow): string[] {
 	const labelBudget = Math.max(16, MAX_COLLAPSED_CARD_COLUMNS - visibleWidth(prefix) - visibleWidth(suffix));
 	const label = compactInlineText(row.displayLabel, { maxChars: labelBudget });
 	const rows = [compactVisibleLine(`${prefix}${label}${suffix}`, MAX_COLLAPSED_CARD_COLUMNS)];
-	const metadata = [row.agent, row.model].filter((value): value is string => !!value).join(" · ");
+	const metadata = launchRowMetadata(row);
 	if (metadata) rows.push(compactVisibleLine(`  ${compactInlineText(metadata, { maxChars: MAX_COLLAPSED_CARD_COLUMNS - 2 })}`, MAX_COLLAPSED_CARD_COLUMNS));
 	return rows;
 }
@@ -222,6 +237,9 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 	const JsonString = Type.String({
 		description: "JSON text of the same value — accepted when a client stringifies nested args",
 	});
+	const ThinkingSchema = StringEnum(THINKING_LEVELS, {
+		description: "Requested effort for this leg (off, minimal, low, medium, high, xhigh, max). Overrides the agent and shared child defaults; Pi clamps to the selected model's capabilities. Results distinguish requested from observed Pi effort, not provider cognition.",
+	});
 	const SkillsSchema = Type.Array(Type.String(), {
 		description: "Skills the sub-agent loads first — spawns a dynamic specialist (skills are inherited from the host)",
 	});
@@ -253,6 +271,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 		),
 		skills: Type.Optional(Type.Union([SkillsSchema, JsonString])),
 		role: Type.Optional(RoleSchema),
+		thinking: Type.Optional(ThinkingSchema),
 		model: Type.Optional(
 			Type.String({ description: "Optional exact provider/id. Prefer cached nearby family/generation candidates; use `models` for targeted lookup or refresh only when needed. Omission retains saved/agent selections and defaults; an explicit current supervisor provider/id selects it deliberately, maintaining provider/billing authorization. Explicit user selections win." }),
 		),
@@ -278,6 +297,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 		name: Type.Optional(Type.String({ description: LeaderNameDescription })),
 		skills: Type.Optional(Type.Union([SkillsSchema, JsonString])),
 		role: Type.Optional(RoleSchema),
+		thinking: Type.Optional(ThinkingSchema),
 		model: Type.Optional(Type.String({ description: "Optional exact provider/id (single mode). Prefer cached nearby family/generation candidates; use `models` for targeted lookup or refresh only when needed. Omission retains saved/agent selections and defaults; an explicit current supervisor provider/id selects it deliberately, maintaining provider/billing authorization. Explicit user selections win." })),
 		tools: Type.Optional(Type.Union([Type.Array(Type.String(), { description: "Tool allowlist override (single mode); [] explicitly grants no tools" }), JsonString])),
 		isolation: Type.Optional(
@@ -476,6 +496,10 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 			kind: "subagent",
 			agent,
 			...(runSpec.model ? { model: runSpec.model } : {}),
+			// The requested effort rides the SAME launch seam as the model above — spec-level, what
+			// the launch row carried. Rendered as the compact sigla after the model; the drill-in
+			// uses full names. Absent ⇒ nothing. Nothing observed is claimed here.
+			...(runSpec.thinking ? { thinking: runSpec.thinking } : {}),
 			detail: "queued",
 		});
 		// Arm the async-run status/stall monitor (no-op if both cadences are disabled). A headless leg runs
@@ -494,9 +518,14 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 		const dropped = droppedNote && `
 
 [pi-persona]${droppedNote}`;
+		const settledRuns = runs.map((run) => {
+			const modelUsed = observedRunModel(run);
+			return { id: run.id, agent: run.agent, ...(run.label ? { label: run.label } : {}),
+				...(run.model ? { requestedModel: run.model } : {}), ...(modelUsed ? { modelUsed } : {}) };
+		});
 		return {
 			content: [{ type: "text" as const, text: `${buildCompletionReport(runs, fenceUntrusted, { bounded: false })}${dropped}${d.drainBusBlock()}` }],
-			details: ok ? {} : failureDetails({}),
+			details: ok ? { settledRuns } : failureDetails({ settledRuns }),
 			isError: !ok,
 			...toolUsageField(usage),
 		};
@@ -513,7 +542,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 			"No fitting agent? Shape one on the fly: `operator` + `role` (extra system prompt) + `skills`.",
 			"Assign each worker's name before launch so it sees the same identity from its first turn; omitted names keep the generic fallback.",
 			"A `model` may be a loose name ('sonnet', 'opus-4.6', 'claude-pro-max-native/opus-4-6') — it resolves to YOUR provider's id; ambiguous names return",
-			"candidates. Other options: name, tools, outputContract, writeSet, isolation: \"worktree\", mcp, concurrency, tasks[].timeoutMs.",
+			"candidates. Other options: name, thinking (per-leg effort; Pi clamps), tools, outputContract, writeSet, isolation: \"worktree\", mcp, concurrency, tasks[].timeoutMs.",
 		].join(" "),
 		parameters: DelegateParams,
 		async execute(_toolCallId, rawParams, signal, onUpdate, ctx) {
@@ -665,7 +694,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 					const label = nameFor(t, nameOffset + i);
 					const id = launchAsyncRun(t.agent, t.task, spec, label, inline, fanOut);
 					const model = shortModel(spec.model);
-					return { id, label, agent: t.agent, ...(model ? { model } : {}) };
+					return { id, label, agent: t.agent, ...(model ? { model } : {}), ...(spec.thinking ? { thinking: spec.thinking } : {}) };
 				});
 				const ids = runs.map((run) => run.id);
 				const droppedNote = dropped > 0 ? ` ${dropped} task(s) beyond the max-children limit (${d.RUN_LIMITS.maxChildren}) were dropped.` : "";
@@ -700,7 +729,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 							text: `Launched async run ${id} (${agent}) — runs in the background and wakes you on completion (${END_TURN_NOTE}).`,
 						},
 					],
-					details: { runId: id, runs: [{ id, label, agent, ...(model ? { model } : {}) }] },
+					details: { runId: id, runs: [{ id, label, agent, ...(model ? { model } : {}), ...(runSpec.thinking ? { thinking: runSpec.thinking } : {}) }] },
 					isError: false,
 				};
 			}
@@ -716,8 +745,13 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 			const coerced = coerceDelegateParams(args);
 			const view = coerced.ok ? coerced.params : undefined;
 			if (view?.tasks && view.tasks.length > 0) {
-				// Names live in the tree / final card — keep the call line itself minimal.
-				return new Text(`${title}${theme.fg("accent", `parallel (${view.tasks.length})`)}`, 0, 0);
+				// Names live in the tree / final card — keep the call line itself minimal. A UNIFORM
+				// declared effort rides along (every leg declares the same level; mixed or undeclared
+				// stays silent — no re-parsing of stringified tasks); per-leg rows carry their own.
+				const first = view.tasks[0]!;
+				const uniform = view.tasks.every((task) => task.thinking === first.thinking) ? first.thinking : undefined;
+				const effort = uniform ? effortFullName(uniform) : "";
+				return new Text(`${title}${theme.fg("accent", `parallel (${view.tasks.length})${effort ? ` · ${effort}` : ""}`)}`, 0, 0);
 			}
 			if (typeof args.tasks === "string" && args.tasks.trim()) {
 				return new Text(`${title}${theme.fg("accent", "parallel")}`, 0, 0);
@@ -728,7 +762,9 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 			const agent = compactInlineText(view?.agent ?? (typeof args.agent === "string" ? args.agent : ""), { maxChars: 40 });
 			const model = typeof modelValue === "string" && modelValue.trim() ? compactInlineText(modelValue, { maxChars: 80 }) : "";
 			const titleLine = `${title}${theme.fg("accent", theme.bold(compactVisibleLine(alias, MAX_COLLAPSED_CARD_COLUMNS - visibleWidth("delegate "))))}`;
-			const metadata = [agent, model].filter(Boolean).join(" · ");
+			// Only the effort THIS call's args declare — never a value inherited from agent config.
+			const thinking = view?.thinking ?? (isThinkingLevel(args.thinking) ? args.thinking : undefined);
+			const metadata = [agent, model, thinking ? effortFullName(thinking) : ""].filter(Boolean).join(" · ");
 			const metadataLine = metadata ? theme.fg("dim", compactVisibleLine(`  ${metadata}`, MAX_COLLAPSED_CARD_COLUMNS)) : "";
 			return new Text([titleLine, metadataLine].filter(Boolean).join("\n"), 0, 0);
 		},

package/src/tools/delegate.ts

@@ -6,6 +6,7 @@
  */
 
 import { cappedList } from "../core/format.ts";
+import { isThinkingLevel, THINKING_LEVELS, type ThinkingLevel } from "../core/types.ts";
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
 import { type AgentRunSpec, type InfrastructureFailure, isInfrastructureFailure, isPositiveFiniteMs } from "../orchestration/sdk.ts";
 
@@ -20,6 +21,8 @@ export interface DelegateTask {
 	skills?: string[];
 	/** Model override for this sub-agent. */
 	model?: string;
+	/** Requested effort for this leg; overrides agent and shared child defaults. Pi clamps it. */
+	thinking?: ThinkingLevel;
 	/** Tool allowlist override for this sub-agent. */
 	tools?: string[];
 	/** Extra system-prompt text: an ON-THE-FLY specialist persona, appended to the
@@ -47,6 +50,7 @@ export interface DelegateParams {
 	name?: string;
 	skills?: string[];
 	model?: string;
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	role?: string;
 	isolation?: "none" | "worktree";
@@ -133,10 +137,6 @@ export function validateDelegationBrief(params: DelegateParams): string | undefi
 	return undefined;
 }
 
-// Moved to core/ownership.ts (so a strategy can call it without importing a tool module);
-// re-exported here unchanged for this file's own call sites and existing tests.
-export { findWriteSetOverlaps, validateParallelWriteSets, type WriteSetOverlap } from "../core/ownership.ts";
-
 function unwrapJsonish(value: unknown, label: string): { ok: true; value: unknown } | { ok: false; error: string } {
 	let current = value;
 	for (let depth = 0; depth < 2; depth++) {
@@ -205,6 +205,9 @@ function decodedTaskFieldError(bag: Record<string, unknown>, index: number): str
 			return `delegate: ${label}.${field} must be a string.`;
 		}
 	}
+	if (bag.thinking !== undefined && !isThinkingLevel(bag.thinking)) {
+		return `delegate: ${label}.thinking must be one of: ${THINKING_LEVELS.join(", ")}.`;
+	}
 	if (bag.isolation !== undefined && bag.isolation !== "none" && bag.isolation !== "worktree") {
 		return `delegate: ${label}.isolation must be "none" or "worktree".`;
 	}
@@ -264,6 +267,9 @@ export function coerceDelegateParams(raw: unknown): { ok: true; params: Delegate
 		return { ok: false, error: "delegate: arguments must be an object." };
 	}
 	const bag = { ...(raw as Record<string, unknown>) };
+	if (bag.thinking !== undefined && !isThinkingLevel(bag.thinking)) {
+		return { ok: false, error: `delegate: thinking must be one of: ${THINKING_LEVELS.join(", ")}.` };
+	}
 	const tasks = coerceTaskList(bag.tasks);
 	if (!tasks.ok) return tasks;
 	if (tasks.value !== undefined) bag.tasks = tasks.value;
@@ -282,10 +288,10 @@ export function coerceDelegateParams(raw: unknown): { ok: true; params: Delegate
 	return { ok: true, params: bag as DelegateParams };
 }
 
-/** Short model name for display: drop provider + `claude-` + any `:thinking`. */
+/** Short model name for display: drop provider + `claude-`; model ids remain opaque. */
 export function shortModel(ref: string | undefined): string {
 	if (!ref) return "";
-	const base = ref.split(":")[0]?.split("/").pop() ?? ref;
+	const base = ref.split("/").pop() ?? ref;
 	return base.replace(/^claude-/, "");
 }
 
@@ -321,6 +327,7 @@ export function specOf(t: DelegateTask, index = 0): AgentRunSpec {
 	};
 	if (t.skills && t.skills.length > 0) spec.skills = t.skills;
 	if (t.model) spec.model = t.model;
+	if (t.thinking !== undefined) spec.thinking = t.thinking;
 	if (t.tools !== undefined) spec.tools = t.tools;
 	if (t.role?.trim()) spec.role = t.role.trim();
 	if (t.outputContract?.trim()) spec.outputContract = t.outputContract.trim();

package/src/tools/exocom-collaboration-input.ts

@@ -0,0 +1,168 @@
+/** Runtime validation and TypeBox schemas for the Exocom collaboration tools. */
+import { type Static, Type } from "typebox";
+
+import { writeSetPathError } from "../core/ownership.ts";
+
+const TOKEN = { minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" } as const;
+export const TaskParams = Type.Object({
+	action: Type.Union([Type.Literal("create"), Type.Literal("take"), Type.Literal("progress"), Type.Literal("finish"), Type.Literal("list"), Type.Literal("get")], {
+		description: "Choose list to discover tasks (do not pass work_key or task_id); use get with both identifiers returned by create/list to inspect one exact task generation.",
+	}),
+	work_key: Type.Optional(Type.String({ ...TOKEN, description: "Required for create, take, progress, finish, and get. Omit for list. Pair with task_id for an existing task." })),
+	task_id: Type.Optional(Type.String({ ...TOKEN, description: "Generation id returned by create or list. Required with work_key for take, progress, finish, and get; omit for create and list." })),
+	description: Type.Optional(Type.String({ minLength: 1, maxLength: 2_048 })),
+	write_set: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 64 })),
+	note: Type.Optional(Type.String({ minLength: 1, maxLength: 4_096 })),
+	outcome: Type.Optional(Type.Union([Type.Literal("done"), Type.Literal("abandoned")])),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 64 })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Rows per page: defaults to 10 for summaries or 5 when detail=true. Detailed pages allow at most 5." })),
+	detail: Type.Optional(Type.Boolean({ description: "Include peer-authored task/progress prose. Detailed lists default to 5 rows and reject an explicit limit above 5." })),
+});
+export const OfferParams = Type.Object({
+	work_key: Type.String({ ...TOKEN }),
+	task_id: Type.String({ ...TOKEN }),
+	target: Type.Optional(Type.String({ minLength: 1, maxLength: 80 })),
+	expiresInMinutes: Type.Optional(Type.Integer({ minimum: 1, maximum: 1_440 })),
+});
+export const PublishParams = Type.Object({
+	action: Type.Union([Type.Literal("publish"), Type.Literal("read")]),
+	work_key: Type.Optional(Type.String({ ...TOKEN })),
+	task_id: Type.Optional(Type.String({ ...TOKEN })),
+	title: Type.Optional(Type.String({ minLength: 1, maxLength: 160 })),
+	excerpt: Type.Optional(Type.String({ minLength: 1, maxLength: 4_096 })),
+	msg_id: Type.Optional(Type.String({ ...TOKEN })),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 64 })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+});
+
+type RecordValue = Record<string, unknown>;
+const isRecord = (value: unknown): value is RecordValue => !!value && typeof value === "object" && !Array.isArray(value);
+const isToken = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(value);
+function invalid(tool: string, field: string, expected: string): never {
+	throw new Error(`${tool}: ${field} ${expected}`);
+}
+function exactKeys(tool: string, value: RecordValue, allowed: readonly string[]): void {
+	const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+	if (unexpected) invalid(tool, unexpected, "is not a supported parameter");
+}
+function boundedString(tool: string, field: string, value: unknown, max: number): string {
+	if (typeof value !== "string" || value.length < 1 || value.length > max) invalid(tool, field, `must be 1–${max} characters`);
+	return value;
+}
+function tokenField(tool: string, field: string, value: unknown): string {
+	if (!isToken(value)) invalid(tool, field, "must be 1–128 token characters matching [A-Za-z0-9._:-]");
+	return value;
+}
+function objectInput(tool: string, input: unknown): RecordValue {
+	if (!isRecord(input)) invalid(tool, "parameters", "must be an object");
+	return input;
+}
+
+export type TaskInput =
+	| { action: "list"; offset: number; limit: number; detail: boolean }
+	| { action: "get"; work_key: string; task_id: string }
+	| { action: "create"; work_key: string; description: string; write_set: string[] }
+	| { action: "take"; work_key: string; task_id: string }
+	| { action: "progress"; work_key: string; task_id: string; note: string }
+	| { action: "finish"; work_key: string; task_id: string; note: string; outcome: "done" | "abandoned" };
+
+export function parseTaskInput(input: unknown): TaskInput {
+	const tool = "exocom_task";
+	const value = objectInput(tool, input);
+	if (typeof value.action !== "string" || !["create", "take", "progress", "finish", "list", "get"].includes(value.action)) invalid(tool, "action", "must be create, take, progress, finish, list, or get");
+	const action = value.action as "create" | "take" | "progress" | "finish" | "list" | "get";
+	if (action === "list") {
+		exactKeys(tool, value, ["action", "offset", "limit", "detail"]);
+		const offset = value.offset === undefined ? 0 : value.offset;
+		const detail = value.detail === undefined ? false : value.detail;
+		const limit = value.limit === undefined ? (detail ? 5 : 10) : value.limit;
+		if (!Number.isInteger(offset) || (offset as number) < 0 || (offset as number) > 64) invalid(tool, "offset", "must be an integer from 0 to 64");
+		if (!Number.isInteger(limit) || (limit as number) < 1 || (limit as number) > 20) invalid(tool, "limit", "must be an integer from 1 to 20");
+		if (typeof detail !== "boolean") invalid(tool, "detail", "must be a boolean");
+		return { action, offset: offset as number, limit: limit as number, detail };
+	}
+	if (action === "get") {
+		exactKeys(tool, value, ["action", "work_key", "task_id"]);
+		return { action, work_key: tokenField(tool, "work_key", value.work_key), task_id: tokenField(tool, "task_id", value.task_id) };
+	}
+	if (action === "create") {
+		exactKeys(tool, value, ["action", "work_key", "description", "write_set"]);
+		const work_key = tokenField(tool, "work_key", value.work_key);
+		const description = boundedString(tool, "description", value.description, 2_048);
+		const write_set = value.write_set === undefined ? [] : value.write_set;
+		if (!Array.isArray(write_set) || write_set.length > 64 || write_set.some((path) => typeof path !== "string" || path.length < 1 || path.length > 256)) {
+			invalid(tool, "write_set", "must contain at most 64 paths of 1–256 characters");
+		}
+		for (const path of write_set as string[]) {
+			const issue = writeSetPathError(path);
+			if (issue) invalid(tool, "write_set path", `is invalid (${issue})`);
+		}
+		return { action, work_key, description, write_set: write_set as string[] };
+	}
+	const work_key = tokenField(tool, "work_key", value.work_key);
+	if (action === "take") {
+		exactKeys(tool, value, ["action", "work_key", "task_id"]);
+		return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id) };
+	}
+	if (action === "progress") {
+		exactKeys(tool, value, ["action", "work_key", "task_id", "note"]);
+		return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id), note: boundedString(tool, "note", value.note, 4_096) };
+	}
+	exactKeys(tool, value, ["action", "work_key", "task_id", "note", "outcome"]);
+	if (value.outcome !== "done" && value.outcome !== "abandoned") invalid(tool, "outcome", "must be done or abandoned");
+	return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id), note: boundedString(tool, "note", value.note, 4_096), outcome: value.outcome };
+}
+
+export function parseOfferInput(input: unknown) {
+	const value = objectInput("exocom_offer", input);
+	exactKeys("exocom_offer", value, ["work_key", "task_id", "target", "expiresInMinutes"]);
+	const work_key = tokenField("exocom_offer", "work_key", value.work_key);
+	const task_id = tokenField("exocom_offer", "task_id", value.task_id);
+	let target: string | undefined;
+	if (value.target !== undefined) {
+		const raw = boundedString("exocom_offer", "target", value.target, 80);
+		if (raw === "*") invalid("exocom_offer", "target", "must name one peer, never *");
+		if (!/^[^\p{Cc}\p{Zl}\p{Zp}<>]+$/u.test(raw) || raw !== raw.trim()) invalid("exocom_offer", "target", "must exactly match a clean public target from exocom_list");
+		target = raw;
+	}
+	const expiresInMinutes = value.expiresInMinutes === undefined ? 60 : value.expiresInMinutes;
+	if (!Number.isInteger(expiresInMinutes) || (expiresInMinutes as number) < 1 || (expiresInMinutes as number) > 1_440) {
+		invalid("exocom_offer", "expiresInMinutes", "must be an integer from 1 to 1440");
+	}
+	return { work_key, task_id, target, expiresInMinutes: expiresInMinutes as number };
+}
+
+export type PublishInput =
+	| { action: "read"; msg_id: string }
+	| { action: "read"; work_key: string; task_id?: string; offset: number; limit: number }
+	| { action: "publish"; work_key: string; task_id: string; title: string; excerpt: string };
+
+export function parsePublishInput(input: unknown): PublishInput {
+	const value = objectInput("exocom_publish", input);
+	if (value.action === "read") {
+		if (value.msg_id !== undefined) {
+			exactKeys("exocom_publish", value, ["action", "msg_id"]);
+			return { action: "read", msg_id: tokenField("exocom_publish", "msg_id", value.msg_id) };
+		}
+		exactKeys("exocom_publish", value, ["action", "work_key", "task_id", "offset", "limit"]);
+		const work_key = tokenField("exocom_publish", "work_key", value.work_key);
+		const task_id = value.task_id === undefined ? undefined : tokenField("exocom_publish", "task_id", value.task_id);
+		const offset = value.offset === undefined ? 0 : value.offset;
+		const limit = value.limit === undefined ? 10 : value.limit;
+		if (!Number.isInteger(offset) || (offset as number) < 0 || (offset as number) > 64) invalid("exocom_publish", "offset", "must be an integer from 0 to 64");
+		if (!Number.isInteger(limit) || (limit as number) < 1 || (limit as number) > 20) invalid("exocom_publish", "limit", "must be an integer from 1 to 20");
+		return { action: "read", work_key, ...(task_id === undefined ? {} : { task_id }), offset: offset as number, limit: limit as number };
+	}
+	if (value.action !== "publish") invalid("exocom_publish", "action", "must be publish or read");
+	exactKeys("exocom_publish", value, ["action", "work_key", "task_id", "title", "excerpt"]);
+	const work_key = tokenField("exocom_publish", "work_key", value.work_key);
+	const task_id = tokenField("exocom_publish", "task_id", value.task_id);
+	const title = boundedString("exocom_publish", "title", value.title, 160);
+	const excerpt = boundedString("exocom_publish", "excerpt", value.excerpt, 4_096);
+	if (Buffer.byteLength(excerpt, "utf8") > 8_192) invalid("exocom_publish", "excerpt", "must be at most 8192 UTF-8 bytes");
+	return { action: "publish", work_key, task_id, title, excerpt };
+}
+
+export type TaskParamsType = Static<typeof TaskParams>;
+export type OfferParamsType = Static<typeof OfferParams>;
+export type PublishParamsType = Static<typeof PublishParams>;