@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/extension/schemas.ts

@@ -0,0 +1,444 @@
+/**
+ * TypeBox schemas for subagent tool parameters
+ */
+
+import { Type } from "../shared/native-typebox.ts";
+import { SUBAGENT_ACTIONS } from "../shared/types.ts";
+
+const requiredObject = (...required: string[]) => ({ type: "object" as const, required });
+
+const SkillOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string", minLength: 1 } },
+		{ type: "boolean" },
+		{ type: "string" },
+	],
+	description: "Skill name(s): string, comma-separated string, array, or false to disable",
+});
+
+const OutputOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "string", minLength: 1 },
+		{ type: "boolean" },
+	],
+	description: "Output file path, or false to disable file output.",
+});
+
+const OutputModeOverride = Type.Enum(["inline", "file-only"] as const, {
+	type: "string",
+	description: "inline (default) or file-only; file-only requires output to be a path.",
+});
+
+const ReadsOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string", minLength: 1 } },
+		{ type: "boolean" },
+	],
+	description: "Files to read before running, or false to disable",
+});
+
+const MaxOutputOverride = Type.Object({
+	bytes: Type.Optional(Type.Integer({ minimum: 1, description: "Max output bytes before truncation." })),
+	lines: Type.Optional(Type.Integer({ minimum: 1, description: "Max output lines before truncation." })),
+}, {
+	additionalProperties: false,
+	description: "Final output truncation limits. Defaults: 200KB, 5000 lines.",
+});
+
+const JsonSchemaObject = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	description: "JSON Schema (object root) for strict structured output.",
+});
+
+const AcceptanceEvidenceKind = Type.Enum([
+	"changed-files",
+	"tests-added",
+	"commands-run",
+	"validation-output",
+	"residual-risks",
+	"no-staged-files",
+	"diff-summary",
+	"review-findings",
+	"manual-notes",
+] as const, { type: "string" });
+
+const AcceptanceGateSchema = Type.Object({
+	id: Type.String({ minLength: 1 }),
+	must: Type.String({ minLength: 1 }),
+	evidence: Type.Optional(Type.Array(AcceptanceEvidenceKind)),
+	severity: Type.Optional(Type.Enum(["required", "recommended"] as const, { type: "string" })),
+}, { additionalProperties: false });
+
+const AcceptanceVerifyCommandSchema = Type.Object({
+	id: Type.String({ minLength: 1 }),
+	command: Type.String({ minLength: 1 }),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+	cwd: Type.Optional(Type.String()),
+	env: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: { type: "string" } })),
+	allowFailure: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+export const AcceptanceOverride = Type.Unsafe({
+	type: "object",
+	properties: {
+		criteria: {
+			type: "array",
+			items: {
+				anyOf: [
+					{ type: "string", minLength: 1 },
+					AcceptanceGateSchema,
+				],
+			},
+		},
+		evidence: { type: "array", items: AcceptanceEvidenceKind },
+		verify: { type: "array", items: AcceptanceVerifyCommandSchema },
+		stopRules: { type: "array", items: { type: "string", minLength: 1 } },
+		maxFinalizationTurns: { type: "integer", minimum: 1, maximum: 10 },
+	},
+	additionalProperties: false,
+	description: "Optional acceptance contract. criteria=definition of done, evidence/verify=proof, stopRules=constraints, maxFinalizationTurns=self-review budget; at least one required. no-staged-files requires the entire Git index to be empty, including pre-existing staged paths. Continue/resume/answer overrides apply only to newly started continuations, never to a live child's acceptance. See the pi-subagents skill.",
+});
+
+// The everyday tools use closed acceptance shapes. Advanced callers retain the full contract below.
+export const DelegateAcceptance = Type.Object({
+	criteria: Type.Optional(Type.Array(AcceptanceGateSchema)),
+	evidence: Type.Optional(Type.Array(AcceptanceEvidenceKind)),
+	verify: Type.Optional(Type.Array(Type.Object({
+		...AcceptanceVerifyCommandSchema.properties,
+		env: Type.Optional(Type.Array(Type.Object({ name: Type.String({ minLength: 1 }), value: Type.String() }, { additionalProperties: false }))),
+	}, { additionalProperties: false }))),
+	stopRules: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+	maxFinalizationTurns: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+}, { additionalProperties: false, description: "Acceptance criteria, evidence, verification commands and stop rules. Criteria use objects; verification environment uses unique name/value pairs. Self-review budget: 1–10 turns." });
+
+const ModelOverride = Type.Optional(Type.String({
+	description: 'Profiles are defaults; warranted overrides are allowed subject to user instructions and provider authorization. Use model: "provider/model:high" to pin route/effort (no profile fallbacks; same-choice transport retries remain). Omit for profile fallbacks. No standalone thinking argument.',
+}));
+
+const TaskItem = Type.Object({
+	agent: Type.String({ minLength: 1 }),
+	task: Type.String({ minLength: 1 }),
+	label: Type.Optional(Type.String({ minLength: 1, description: "Short task label for the Agents strip and conversation." })),
+	cwd: Type.Optional(Type.String()),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
+	model: ModelOverride,
+	skill: Type.Optional(SkillOverride),
+	acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+
+// Parallel task item (within a parallel step)
+const ParallelTaskSchema = Type.Object({
+	agent: Type.String({ minLength: 1 }),
+	task: Type.Optional(Type.String({ minLength: 1, description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
+	phase: Type.Optional(Type.String({ description: "Phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "User-facing label for this parallel task." })),
+	as: Type.Optional(Type.String({ description: "Safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times." })),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: ModelOverride,
+	acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+
+const DynamicExpandSchema = Type.Object({
+	from: Type.Object({
+		output: Type.String({ description: "Prior named structured output to expand from." }),
+		path: Type.String({ description: "JSON Pointer into the structured output, e.g. /items." }),
+	}, { additionalProperties: false }),
+	item: Type.Optional(Type.String({ description: "Template variable name for each item. Defaults to item." })),
+	key: Type.Optional(Type.String({ description: "JSON Pointer relative to each item for stable child ids." })),
+	maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required fanout bound unless configured globally." })),
+	onEmpty: Type.Optional(Type.Enum(["skip", "fail"] as const, { type: "string", description: "Empty input behavior. Defaults to skip." })),
+}, { additionalProperties: false });
+
+const DynamicParallelTemplateSchema = Type.Object({
+	agent: Type.String({ minLength: 1 }),
+	task: Type.Optional(Type.String({ minLength: 1, description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, {outputs.name} variables." })),
+	phase: Type.Optional(Type.String({ description: "Phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "User-facing label; item templates supported." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: ModelOverride,
+	acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+
+const DynamicCollectSchema = Type.Object({
+	as: Type.String({ description: "Safe output name for the ordered collected result array." }),
+	outputSchema: Type.Optional(JsonSchemaObject),
+}, { additionalProperties: false });
+
+// Flattened so chain steps do not need an object-shape anyOf/oneOf union.
+export const ChainItemSchema = Type.Object({
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Sequential step agent name" })),
+	task: Type.Optional(Type.String({
+		minLength: 1,
+		description: "Task template: {task}=original request, {previous}=prior step response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step; defaults to '{previous}'."
+	})),
+	phase: Type.Optional(Type.String({ description: "Phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "User-facing label for this chain step." })),
+	as: Type.Optional(Type.String({ description: "Safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: ModelOverride,
+	acceptance: Type.Optional(AcceptanceOverride),
+	parallel: Type.Optional(Type.Unsafe({
+		anyOf: [
+			Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
+			DynamicParallelTemplateSchema,
+		],
+		description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
+	})),
+	expand: Type.Optional(DynamicExpandSchema),
+	collect: Type.Optional(DynamicCollectSchema),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Max concurrent tasks (default: 4)" })),
+	failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure (default: false)" })),
+	worktree: Type.Optional(Type.Boolean({
+		description: "Create isolated git worktrees for each parallel task."
+	})),
+}, {
+	description: "Chain step: {agent, task?} sequential, {parallel: [...]} concurrent, or {expand, parallel: {...}, collect} dynamic fanout.",
+	additionalProperties: false,
+	allOf: [
+		{ anyOf: [requiredObject("agent"), requiredObject("parallel")] },
+		{ not: { anyOf: [
+			requiredObject("agent", "parallel"),
+			{ ...requiredObject("expand"), properties: { parallel: { type: "array", items: {} } } },
+		] } },
+		{ if: requiredObject("expand"), then: { ...requiredObject("parallel", "collect"), properties: { parallel: { type: "object" } } } },
+		{ if: requiredObject("collect"), then: { ...requiredObject("expand", "parallel"), properties: { parallel: { type: "object" } } } },
+		{ if: { ...requiredObject("parallel"), properties: { parallel: { type: "object" } } }, then: requiredObject("expand", "collect") },
+		{ if: requiredObject("agent"), then: { not: { anyOf: [requiredObject("concurrency"), requiredObject("failFast"), requiredObject("worktree")] } } },
+		{ if: { ...requiredObject("parallel"), properties: { parallel: { type: "array", items: {} } } }, then: { not: { anyOf: [
+			requiredObject("task"), requiredObject("phase"), requiredObject("label"), requiredObject("as"), requiredObject("outputSchema"),
+			requiredObject("output"), requiredObject("outputMode"), requiredObject("reads"), requiredObject("progress"),
+			requiredObject("skill"), requiredObject("model"), requiredObject("acceptance"), requiredObject("expand"), requiredObject("collect"),
+		] } } },
+		{ if: { ...requiredObject("parallel"), properties: { parallel: { type: "object" } } }, then: { not: { anyOf: [
+			requiredObject("task"), requiredObject("as"), requiredObject("outputSchema"), requiredObject("cwd"), requiredObject("output"),
+			requiredObject("outputMode"), requiredObject("reads"), requiredObject("progress"), requiredObject("skill"),
+			requiredObject("model"), requiredObject("acceptance"), requiredObject("worktree"),
+		] } } },
+	],
+});
+
+const ControlOverrides = Type.Object({
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
+	needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-activity window (ms) before a run needs attention. Default 600000 (10 min)." })),
+	failedToolAttemptsBeforeAttention: Type.Optional(Type.Integer({ minimum: 1, description: "Consecutive mutating-tool failures before needs_attention (default: 3)" })),
+	notifyOn: Type.Optional(Type.Array(Type.Enum(["needs_attention"] as const, { type: "string" }), {
+		description: "Control event types that should notify the parent/orchestrator. Defaults to needs_attention.",
+	})),
+	notifyChannels: Type.Optional(Type.Array(Type.Enum(["event", "async", "intercom"] as const, { type: "string" }), {
+		description: "Notification channels to use when available. Defaults to event, async, and intercom.",
+	})),
+}, { additionalProperties: false });
+
+export const DelegateParams = Type.Object({
+	agent: TaskItem.properties.agent,
+	task: TaskItem.properties.task,
+	label: TaskItem.properties.label,
+	cwd: TaskItem.properties.cwd,
+	model: TaskItem.properties.model,
+	context: Type.Optional(Type.Enum(["fresh", "fork"] as const, { type: "string", description: "Override the profile's context policy." })),
+	async: Type.Optional(Type.Boolean({ description: "Background by default; false waits for the result." })),
+	worktree: Type.Optional(Type.Boolean({ description: "Isolate this writer in a Git worktree; return its patch. Requires a clean checkout." })),
+	output: TaskItem.properties.output,
+	acceptance: Type.Optional(DelegateAcceptance),
+}, { additionalProperties: false });
+
+const HistoryQueryFields = {
+	cursor: Type.Optional(Type.String({ minLength: 1, description: "Opaque page cursor returned by list/history/search; expires when the indexed snapshot changes." })),
+	sort: Type.Optional(Type.Enum(["attention", "newest", "oldest", "relevance"] as const, { type: "string", description: "List: attention (default), newest, oldest. Search: relevance (default), newest." })),
+	state: Type.Optional(Type.Enum(["live", "completed", "failed", "blocked", "paused", "unknown"] as const, { type: "string", description: "List only: execution-state filter, applied before paging." })),
+	text: Type.Optional(Type.String({ minLength: 1, description: "List only: filter saved task/assignment text before paging." })),
+	query: Type.Optional(Type.String({ minLength: 1, description: 'Search visible saved text using 1–12 lexical words (all must match) or one double-quoted phrase. Operators, punctuation and prefixes are rejected. Thinking, images, tool arguments and hidden data are excluded.' })),
+	before: Type.Optional(Type.Integer({ minimum: 1, description: "History only: exclusive native-entry position returned by the earlier page; omit for the latest page." })),
+};
+
+export const AgentRunsValidationParams = Type.Object({
+	action: Type.Enum(["list", "inspect", "history", "search", "nudge", "stop", "continue", "profiles", "questions", "answer", "review"] as const, { type: "string" }),
+	id: Type.Optional(Type.String({ minLength: 1, description: "Run ID or unambiguous prefix." })),
+	questionId: Type.Optional(Type.String({ minLength: 1, description: "Durable supervisor question ID for exact questions lookup or answer." })),
+	async: Type.Optional(Type.Boolean({ description: "Continue/answer: false waits for the actual continuation result." })),
+	index: Type.Optional(Type.Integer({ minimum: 0, description: "Child index for a multi-child run." })),
+	message: Type.Optional(Type.String({ minLength: 1, description: "Guidance, follow-up, answer, or optional parent-only review note. Review notes are not sent to the child; put actionable instructions in continue/nudge. Only continue/answer can start a saved child." })),
+	decision: Type.Optional(Type.Enum(["accepted", "needs_changes"] as const, { type: "string", description: "Parent-only review outcome; not sent to the child. Separate from execution and runtime acceptance checks." })),
+	offset: Type.Optional(Type.Integer({ minimum: 0, description: "List/questions offset; history is retained regardless of page size." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description: "Results per list/questions/search/history page (default 20; history 100)." })),
+	...HistoryQueryFields,
+	full: Type.Optional(Type.Boolean({ description: "Inspect only: include the full task and saved launch configuration. Default is a concise report; stored data is unchanged." })),
+	agent: Type.Optional(Type.String({ minLength: 1, description: "List/search: filter by child agent. Continue/answer: adopt this current profile, including model, thinking and fallbacks; a separate model override wins. Otherwise keep saved settings. Required for old runs without a saved profile." })),
+	model: TaskItem.properties.model,
+	cwd: TaskItem.properties.cwd,
+	output: TaskItem.properties.output,
+	acceptance: TaskItem.properties.acceptance,
+}, {
+	additionalProperties: false,
+	allOf: [
+		{ if: { properties: { action: { enum: ["inspect", "history", "nudge", "stop", "continue", "answer", "review"] } } }, then: requiredObject("id") },
+		{ if: { properties: { action: { enum: ["search"] } } }, then: requiredObject("query") },
+		{ if: { properties: { action: { enum: ["nudge", "continue", "answer"] } } }, then: requiredObject("message") },
+		{ if: { properties: { action: { enum: ["answer"] } } }, then: requiredObject("questionId") },
+		{ if: { properties: { action: { enum: ["review"] } } }, then: requiredObject("decision") },
+		{ if: { anyOf: [requiredObject("async"), requiredObject("model"), requiredObject("cwd"), requiredObject("output"), requiredObject("acceptance")] }, then: { properties: { action: { enum: ["continue", "answer"] } } } },
+		{ if: requiredObject("agent"), then: { properties: { action: { enum: ["list", "search", "continue", "answer"] } } } },
+		{ if: requiredObject("offset"), then: { properties: { action: { enum: ["list", "questions"] } } } },
+		{ if: requiredObject("limit"), then: { properties: { action: { enum: ["list", "questions", "history", "search"] } } } },
+		{ if: requiredObject("cursor"), then: { properties: { action: { enum: ["list", "history", "search"] } } } },
+		{ if: requiredObject("sort"), then: { properties: { action: { enum: ["list", "search"] } } } },
+		{ not: { anyOf: [requiredObject("cursor", "offset"), requiredObject("cursor", "before")] } },
+		{ if: { allOf: [{ properties: { action: { enum: ["search"] } } }, requiredObject("index")] }, then: requiredObject("id") },
+		{ if: { anyOf: [requiredObject("state"), requiredObject("text")] }, then: { properties: { action: { enum: ["list"] } } } },
+		{ if: requiredObject("query"), then: { properties: { action: { enum: ["search"] } } } },
+		{ if: requiredObject("before"), then: { properties: { action: { enum: ["history"] } } } },
+		{ if: { properties: { action: { enum: ["list"] } } }, then: { properties: { sort: { enum: ["attention", "newest", "oldest"] } } } },
+		{ if: { properties: { action: { enum: ["search"] } } }, then: { properties: { sort: { enum: ["relevance", "newest"] } } } },
+		{ if: requiredObject("decision"), then: { properties: { action: { enum: ["review"] } } } },
+		{ if: requiredObject("full"), then: { properties: { action: { enum: ["inspect"] } } } },
+	],
+});
+
+export const AgentRunsParams = Type.Object({
+	...AgentRunsValidationParams.properties,
+	acceptance: Type.Optional(DelegateAcceptance),
+}, { additionalProperties: false });
+
+export const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Agent name; on resume/answer, adopt the current profile including model, thinking and fallbacks; a separate model override wins. Otherwise keep saved settings." })),
+	task: Type.Optional(Type.String({ minLength: 1, description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	label: TaskItem.properties.label,
+	// Management action (when present, tool operates in management mode)
+	action: Type.Optional(Type.Enum([...SUBAGENT_ACTIONS] as const, {
+		type: "string",
+		description: "Management/control action. Omit for execution mode. nudge sends a live intercom nudge to a running child."
+	})),
+	id: Type.Optional(Type.String({
+		description: "Run id or prefix for status/interrupt/extend/resume/nudge/questions/answer/review actions."
+	})),
+	runId: Type.Optional(Type.String({
+		description: "Target run ID; prefer id. Defaults to the most recently active controllable run for interrupt/extend/nudge."
+	})),
+	questionId: AgentRunsValidationParams.properties.questionId,
+	decision: Type.Optional(Type.Enum(["accepted", "needs_changes"] as const, { type: "string", description: "Parent-only review decision; not sent to the child. Put actionable instructions in resume/nudge. Does not launch work or change runtime acceptance." })),
+	offset: Type.Optional(Type.Integer({ minimum: 0, description: "Status list/questions offset." })),
+	limit: AgentRunsValidationParams.properties.limit,
+	...HistoryQueryFields,
+	full: Type.Optional(Type.Boolean({ description: "Exact status only: include the full task and saved launch configuration; default is concise." })),
+	dir: Type.Optional(Type.String({
+		description: "Async run directory for status/resume."
+	})),
+	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child." })),
+	message: Type.Optional(Type.String({ description: "Follow-up for resume, nudge text, answer, or parent-only review note. Review notes are not sent to the child; put actionable instructions in resume/nudge. Use index for multi-child runs." })),
+	extendMs: Type.Optional(Type.Integer({ minimum: 1, description: "Additional ms for extend; defaults to timeoutMs/maxRuntimeMs." })),
+	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
+	chainName: Type.Optional(Type.String({
+		description: "Chain name for get/update/delete management actions"
+	})),
+	// Agent/chain configuration for create/update (nested to avoid conflicts with execution fields)
+	config: Type.Optional(Type.Unsafe({
+		anyOf: [
+			{ type: "object", additionalProperties: true },
+			{ type: "string" },
+		],
+		description: "Agent or chain config for create/update (object or JSON string). Agent keys: name, package, description, scope ('user'|'project'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, model, tools, allowSubagents, extensions, skills, thinking, output, reads, progress, maxSubagentDepth, maxExecutionTimeMs, maxTokens. Chain keys: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skills?, progress?}). Presence of 'steps' creates a chain."
+	})),
+	tasks: Type.Optional(Type.Array(TaskItem, { minItems: 1, description: "PARALLEL mode: concurrent [{agent, task, ...}] tasks." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "PARALLEL mode: max concurrent parallel tasks (default 4)." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Foreground wall-clock timeout (ms); on expiry children are soft-interrupted. When async is omitted, a timeout implies foreground execution; explicit async runs reject it. Short reviewer budgets are raised to a floor; planner/researcher budgets only from run-history data." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias for timeoutMs; same foreground-only policy." })),
+	maxOutput: Type.Optional(MaxOutputOverride),
+	worktree: Type.Optional(Type.Boolean({
+		description: "Isolated git worktrees per parallel task; requires clean git state; per-worktree diffs included."
+	})),
+	chain: Type.Optional(Type.Array(ChainItemSchema, { minItems: 1, description: "CHAIN mode: sequential pipeline; each step's response becomes {previous} for the next." })),
+	context: Type.Optional(Type.Enum(["fresh", "fork"] as const, {
+		type: "string",
+		description: "'fresh' or 'fork' (branch from parent session); overrides each agent's defaultContext. Fork is rejected for agents whose effective model uses the anthropic/ provider.",
+	})),
+	chainDir: Type.Optional(Type.String({ description: "Directory for chain artifacts (default: temp, auto-cleaned after 24h)" })),
+	async: Type.Optional(Type.Boolean({ description: "Run in background. Stock top-level default: true; set false for foreground execution." })),
+	agentScope: Type.Optional(Type.Enum(["user", "project", "both"] as const, { type: "string", description: "Agent discovery scope: 'user', 'project', or 'both' (default; project wins collisions)" })),
+	cwd: Type.Optional(Type.String()),
+	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
+	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for a single agent run" })),
+	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
+	sessionDir: Type.Optional(
+		Type.String({ description: "Directory for session logs (default: temp)" }),
+	),
+	// Clarification TUI
+	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution; explicit true forces foreground." })),
+	control: Type.Optional(ControlOverrides),
+	// Solo agent overrides
+	output: Type.Optional(Type.Unsafe({
+		anyOf: [
+			{ type: "string" },
+			{ type: "boolean" },
+		],
+		description: "Output file for single agent, or false to disable. Relative paths resolve against cwd.",
+	})),
+	outputMode: Type.Optional(OutputModeOverride),
+	skill: Type.Optional(SkillOverride),
+	model: ModelOverride,
+	outputSchema: Type.Optional(JsonSchemaObject),
+	acceptance: Type.Optional(AcceptanceOverride),
+}, {
+	additionalProperties: false,
+	allOf: [
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["answer"] } } }, then: { allOf: [requiredObject("questionId", "message"), { anyOf: [requiredObject("id"), requiredObject("runId")] }] } },
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["review"] } } }, then: { allOf: [requiredObject("decision"), { anyOf: [requiredObject("id"), requiredObject("runId")] }] } },
+		{ not: { anyOf: [
+			requiredObject("agent", "tasks"),
+			requiredObject("agent", "chain"),
+			requiredObject("tasks", "chain"),
+			requiredObject("cursor", "offset"),
+			requiredObject("cursor", "before"),
+		] } },
+		{ if: requiredObject("decision"), then: { ...requiredObject("action"), properties: { action: { enum: ["review"] } } } },
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["history"] } } }, then: { anyOf: [requiredObject("id"), requiredObject("runId")] } },
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["search"] } } }, then: requiredObject("query") },
+		{ if: requiredObject("offset"), then: { ...requiredObject("action"), properties: { action: { enum: ["status", "questions"] } } } },
+		{ if: requiredObject("limit"), then: { ...requiredObject("action"), properties: { action: { enum: ["status", "questions", "history", "search"] } } } },
+		{ if: requiredObject("cursor"), then: { ...requiredObject("action"), properties: { action: { enum: ["status", "history", "search"] } } } },
+		{ if: requiredObject("sort"), then: { ...requiredObject("action"), properties: { action: { enum: ["status", "search"] } } } },
+		{ if: { allOf: [{ ...requiredObject("action"), properties: { action: { enum: ["search"] } } }, requiredObject("index")] }, then: { anyOf: [requiredObject("id"), requiredObject("runId")] } },
+		{ if: { anyOf: [requiredObject("state"), requiredObject("text")] }, then: { ...requiredObject("action"), properties: { action: { enum: ["status"] } } } },
+		{ if: requiredObject("query"), then: { ...requiredObject("action"), properties: { action: { enum: ["search"] } } } },
+		{ if: requiredObject("before"), then: { ...requiredObject("action"), properties: { action: { enum: ["history"] } } } },
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["status"] } } }, then: { properties: { sort: { enum: ["attention", "newest", "oldest"] } } } },
+		{ if: { ...requiredObject("action"), properties: { action: { enum: ["search"] } } }, then: { properties: { sort: { enum: ["relevance", "newest"] } } } },
+		{ if: requiredObject("full"), then: { allOf: [{ ...requiredObject("action"), properties: { action: { enum: ["status"] } } }, { anyOf: [requiredObject("id"), requiredObject("runId"), requiredObject("dir")] }] } },
+		{ if: requiredObject("worktree"), then: requiredObject("tasks") },
+		{ if: requiredObject("concurrency"), then: requiredObject("tasks") },
+		{ if: requiredObject("chainDir"), then: requiredObject("chain") },
+		{ if: { anyOf: [
+			requiredObject("output"), requiredObject("outputMode"), requiredObject("skill"), requiredObject("model"),
+			requiredObject("outputSchema"), requiredObject("progress"),
+		] }, then: { anyOf: [requiredObject("agent"), { ...requiredObject("action"), properties: { action: { enum: ["resume", "answer"] } } }] } },
+		{ if: requiredObject("acceptance"), then: { anyOf: [
+			requiredObject("agent"),
+			{ ...requiredObject("action"), properties: { action: { enum: ["resume", "answer"] } } },
+		] } },
+	],
+});

package/src/extension/tool-input.ts

@@ -0,0 +1,19 @@
+import { Compile } from "../shared/native-typebox.ts";
+import { AgentRunsValidationParams } from "./schemas.ts";
+
+const runArguments = Compile(AgentRunsValidationParams);
+
+export function normalizeEverydayParams(params: Record<string, unknown>, control = false): Record<string, unknown> {
+	const acceptance = params.acceptance as { verify?: Array<{ env?: Array<{ name: string; value: string }> }> } | undefined;
+	const normalized = acceptance?.verify ? {
+		...params,
+		acceptance: { ...acceptance, verify: acceptance.verify.map((verify) => {
+			if (!Array.isArray(verify.env)) return verify;
+			const names = verify.env.map(({ name }) => name);
+			if (new Set(names).size !== names.length) throw new Error("Verification environment contains duplicate names.");
+			return { ...verify, env: Object.fromEntries(verify.env.map(({ name, value }) => [name, value])) };
+		}) },
+	} : params;
+	if (control && !runArguments.Check(normalized)) throw new Error(`Invalid agent_runs arguments: ${[...runArguments.Errors(normalized)].map((error) => error.message).join("; ")}`);
+	return normalized;
+}

package/src/extension/tool-result.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Details, SubagentExecutionResult } from "../shared/types.ts";
+
+export function registerToolResultAdapter(pi: ExtensionAPI, toolNames: readonly string[]) {
+	pi.on("tool_result", (event) => {
+		const details = event.details as (Details & { isError?: boolean }) | undefined;
+		if (!toolNames.includes(event.toolName) || details?.isError !== true) return;
+		const { isError, ...originalDetails } = details;
+		return { isError, details: originalDetails };
+	});
+	// Native execute ignores returned isError; throwing discards content/details.
+	// Carry the flag to its native result hook, which restores the original details.
+	return (result: SubagentExecutionResult) => result.isError
+		? { ...result, details: { ...result.details, isError: true } }
+		: result;
+}

package/src/history/canonical-result.ts

@@ -0,0 +1,62 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { JsonProjection, readJsonProjection } from "../shared/journal-reader.ts";
+import { HistoryIndexError } from "./types.ts";
+
+const budget = 16 * 1024 * 1024;
+export function readSavedOutput(file: string): string {
+	const fd = fs.openSync(file, "r");
+	try {
+		const before = fs.fstatSync(fd, { bigint: true });
+		if (!before.isFile() || before.size > BigInt(budget)) throw new HistoryIndexError("RECORD_TOO_LARGE", "Selected saved output exceeds the 16 MiB detail budget.");
+		const bytes = Buffer.alloc(Number(before.size));
+		for (let offset = 0; offset < bytes.length;) {
+			const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+			if (!count) throw new HistoryIndexError("SOURCE_CHANGED", "Selected saved output was truncated.");
+			offset += count;
+		}
+		const after = fs.fstatSync(fd, { bigint: true }), current = fs.statSync(file, { bigint: true });
+		if (before.size !== after.size || before.ctimeNs !== after.ctimeNs || before.dev !== current.dev || before.ino !== current.ino) throw new HistoryIndexError("SOURCE_CHANGED", "Selected saved output changed; retry details.");
+		return new TextDecoder("utf8", { fatal: true }).decode(bytes);
+	} finally { fs.closeSync(fd); }
+}
+
+/** Explicit legacy/compact owner detail: retain only this child's output, never transcript arrays. */
+export function readCanonicalOutput(file: string, index: number): string | undefined {
+	let prefix: Array<string | number>;
+	if (path.basename(file) === "foreground.json") {
+		const metadata = readJsonProjection(file, (keys) => !keys.length || keys[0] === "children" && (keys.length <= 2 || keys.length === 3 && keys[2] === "index"));
+		const position = metadata.children?.findIndex((child: { index: number } | null) => child?.index === index);
+		if (position === undefined || position < 0) return;
+		prefix = ["children", position, "result"];
+	} else prefix = path.basename(file) === "result.json" ? ["results", index] : ["result"];
+	let length = 0;
+	const projection = new JsonProjection((keys) => {
+		if (prefix[0] === "children" && keys.length === 3 && keys[0] === "children" && keys[1] === prefix[1] && keys[2] === "index") return true;
+		if (keys.length <= prefix.length) return keys.every((key, position) => key === prefix[position]);
+		return keys.length === prefix.length + 1 && prefix.every((key, position) => key === keys[position]) && ["finalOutput", "output"].includes(String(keys.at(-1))) ? budget : false;
+	}, (keys, text) => {
+		if (keys.length === prefix.length + 1 && prefix.every((key, position) => key === keys[position]) && ["finalOutput", "output"].includes(String(keys.at(-1)))) {
+			length += Buffer.byteLength(text);
+			if (length > budget) throw new HistoryIndexError("RECORD_TOO_LARGE", "Selected canonical output exceeds the 16 MiB detail budget.");
+		}
+	});
+	const fd = fs.openSync(file, "r"), decoder = new TextDecoder("utf8", { fatal: true });
+	try {
+		const before = fs.fstatSync(fd, { bigint: true }), bytes = Buffer.allocUnsafe(64 * 1024);
+		for (let offset = 0; offset < Number(before.size);) {
+			const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, Number(before.size) - offset), offset);
+			if (!count) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical output was truncated.");
+			projection.write(decoder.decode(bytes.subarray(0, count), { stream: true })); offset += count;
+		}
+		projection.write(decoder.decode());
+		const value = projection.finish(), after = fs.fstatSync(fd, { bigint: true }), current = fs.statSync(file, { bigint: true });
+		if (prefix[0] === "children" && value?.children?.[prefix[1]]?.index !== index) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical child changed; retry details.");
+		if (before.size !== after.size || before.ctimeNs !== after.ctimeNs || before.dev !== current.dev || before.ino !== current.ino) throw new HistoryIndexError("SOURCE_CHANGED", "Selected canonical output changed; retry details.");
+		let child: unknown = value;
+		for (const key of prefix) child = child && typeof child === "object" ? (child as Record<string | number, unknown>)[key] : undefined;
+		if (!child || typeof child !== "object") return;
+		const result = child as Record<string, unknown>;
+		return typeof result.finalOutput === "string" ? result.finalOutput : typeof result.output === "string" ? result.output : undefined;
+	} finally { fs.closeSync(fd); }
+}

package/src/history/database.ts

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { HistoryIndexError } from "./types.ts";
+
+export function historyDirectory(agentDir: string, create = true): string {
+	const directory = path.join(fs.realpathSync(agentDir), "history-index");
+	if (create) fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+	if (fs.lstatSync(directory).isSymbolicLink()) throw new HistoryIndexError("UNSAFE_PATH", "History directory must not be a symbolic link.");
+	if (create) fs.chmodSync(directory, 0o700);
+	const filesystem = fs.statfsSync(directory).type;
+	if ([0x6969, 0x517b, 0xff534d42].includes(filesystem)) throw new HistoryIndexError("UNSAFE_PATH", "SQLite history requires a local filesystem.");
+	return directory;
+}
+
+export function openHistoryDatabase(file: string, readOnly = false): DatabaseSync {
+	if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new HistoryIndexError("UNSAFE_PATH", "History database must not be a symbolic link.");
+	for (let attempt = 0; ; attempt++) {
+		const db = new DatabaseSync(file, { timeout: 100, defensive: true, allowExtension: false, readOnly });
+		try {
+			const version = String(db.prepare("SELECT sqlite_version() AS version").get()!.version);
+			if (version !== "3.53.4") throw new HistoryIndexError("UNSUPPORTED_SQLITE", `History requires qualified SQLite 3.53.4; found ${version}.`);
+			db.exec("PRAGMA foreign_keys=ON; PRAGMA trusted_schema=OFF");
+			if (!readOnly) {
+				if (db.prepare("PRAGMA journal_mode").get()?.journal_mode !== "wal") {
+					// WAL conversion upgrades a read lock without waiting for an existing writer.
+					// Wait for that writer through native transaction admission before converting.
+					db.exec("BEGIN IMMEDIATE; COMMIT; PRAGMA journal_mode=WAL");
+				}
+				db.exec("PRAGMA synchronous=FULL");
+				for (const suffix of ["", "-wal", "-shm"]) {
+					try { fs.chmodSync(file + suffix, 0o600); }
+					catch (error) {
+						// SQLite can remove its sidecars when the last attached connection closes.
+						if (!suffix || !(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
+					}
+				}
+			}
+			return db;
+		} catch (error) {
+			db.close();
+			if (readOnly || attempt >= 2 || !/locked|busy/i.test(String((error as Error).message))) throw error;
+			// Concurrent first-open WAL conversion can return BUSY without honoring the native timeout.
+			Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+		}
+	}
+}
+
+export function historyTransaction<T>(db: DatabaseSync, work: () => T): T {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			db.exec("BEGIN IMMEDIATE");
+			const result = work(); db.exec("COMMIT"); return result;
+		} catch (error) {
+			if (db.isTransaction) db.exec("ROLLBACK");
+			if (attempt >= 2 || !/locked|busy/i.test(String((error as Error).message))) throw error;
+		}
+	}
+}