pi-cohort 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [5.1.0] - 2026-08-06
+
+### Changed
+
+- subagent tool schema shrunk from 18.0KB to 12.4KB serialized: the acceptance
+  override shape (previously inlined 5x, 44% of the schema) now appears in full
+  only at top-level `acceptance`; the 4 nested sites (tasks items, chain steps,
+  parallel members, dynamic fanout template) carry a compact stub. Gate-level
+  `evidence`/`severity` dropped from the schema (still accepted at runtime).
+  Deep acceptance validation moved to the executor boundary with per-site path
+  labels. Nested `acceptance: false` is no longer schema-accepted - use
+  `level: "none"`. Unknown acceptance keys are now rejected everywhere,
+  including saved `.chain.json` chains that previously loaded with the key
+  silently ignored. ([#6](https://github.com/jjuraszek/pi-cohort/issues/6))
+
+## [5.0.1] - 2026-08-06
+
+### Changed
+
+- subagent tool schema dieted from 23.2KB to <=18KB serialized (description
+  trimming only; all accepted input shapes unchanged, guarded by a baseline
+  shape fixture). `config` field reference moved to the pi-cohort skill's
+  `reference/config-fields.md`. Schema size-budget test added.
+
 ## [5.0.0] - 2026-08-06
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/skills/pi-cohort/SKILL.md

@@ -503,6 +503,8 @@ If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/c
 
 The `subagent(...)` tool also supports management actions.
 
+Full config field reference: `reference/config-fields.md` (sibling of this file).
+
 ### List available agents and chains
 
 ```typescript

package/skills/pi-cohort/reference/config-fields.md

@@ -0,0 +1,51 @@
+# subagent `config` field reference
+
+Fields accepted by `subagent({ action: "create" | "update", config: {...} })`.
+`config` may be an object or a JSON string. Presence of `steps` makes it a chain.
+Scope: this is the management create/update path (`parseStepList`), which accepts exactly the step fields below and requires `outputSchema` to be a file path; file-authored `.chain.md` chains support additional step fields (parallel, expand, collect, concurrency, failFast, worktree, acceptance, inline outputSchema) - see SKILL.md chain authoring.
+
+## Agent config
+
+| Field | Type | Meaning | Default |
+|---|---|---|---|
+| `name` | string | Required (create). Letters, numbers, spaces, hyphens. | - |
+| `description` | string | Required (create). | - |
+| `package` | string | Optional namespace; runtime name becomes `package.name`. | none |
+| `scope` | `"user"` \| `"project"` | Where the definition file lands. | `"user"` |
+| `systemPrompt` | string \| false | Persona body; false or "" clears. | `""` |
+| `systemPromptMode` | `"append"` \| `"replace"` | How systemPrompt combines with the base prompt. | per-agent default |
+| `model` | string \| false | Model override; false/"" clears. | inherit |
+| `fallbackModels` | string (csv) \| string[] \| false | Models tried in order on failure; false/"" clears. | none |
+| `tools` | string (csv) \| false | Tool allowlist; false/"" clears. MCP-direct tools rejected. | all |
+| `skills` | string (csv) \| false | Skills injected into the agent; false/"" clears. | none |
+| `extensions` | string (csv) \| "" \| false | Extension list; "" means empty list, false clears. | inherit |
+| `thinking` | string \| false | Thinking level; false/"" clears. | inherit |
+| `inheritProjectContext` | boolean | Inject project AGENTS.md context. | per-agent default |
+| `inheritSkills` | boolean | Inherit parent-visible skills. | per-agent default |
+| `defaultContext` | `"fresh"` \| `"fork"` \| false | Default context mode; false/"" clears. | `"fresh"` |
+| `output` | string \| false | Default output filename; false/"" clears. | none |
+| `reads` | string (csv) \| false | Default files read before running; false/"" clears. | none |
+| `progress` | boolean | Default progress.md tracking. | off |
+| `maxSubagentDepth` | integer >= 0 \| false | Nested subagent depth cap; false/"" clears. | inherit |
+| `completionGuard` | boolean | Enable completion guard for this agent. | inherit |
+
+## Chain config
+
+Top-level: `name`, `description`, `package`, `scope` as above, plus required `steps` (non-empty array).
+
+Per step:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `agent` | string | Required, non-empty. |
+| `task` | string | Task template; defaults to `""`. |
+| `phase` | string | Phase/group label. |
+| `label` | string | User-facing label. |
+| `as` | string | Identifier for `{outputs.name}` in later steps. |
+| `outputSchema` | string | Schema FILE PATH (saved chains take a path, not an inline object). |
+| `output` | string \| false | Output file path, or false to disable. |
+| `outputMode` | `"inline"` \| `"file-only"` | Output return mode. |
+| `reads` | string[] \| false | Files to read before the step. |
+| `model` | string | Model override. |
+| `skills` | string[] \| false | Skills to inject (NOTE: plural `skills` here, unlike the execution-time `skill` param). |
+| `progress` | boolean | progress.md tracking. |

package/src/extension/schemas.ts

@@ -5,13 +5,23 @@
 import { Type } from "typebox";
 import { SUBAGENT_ACTIONS } from "../shared/types.ts";
 
+// Descriptor-preserving clone: typebox 1.3.11 metadata ("~kind", "~unsafe",
+// "~optional") lives in NON-ENUMERABLE string-keyed properties. Object spread
+// would drop them, and Type.Optional on a plain clone would re-add "~optional"
+// as an enumerable key, leaking "~optional":true into the serialized JSON.
+const brief = <T extends object>(schema: T, description: string): T =>
+	Object.defineProperties(
+		Object.defineProperties(Object.create(null), Object.getOwnPropertyDescriptors(schema)),
+		{ description: { value: description, enumerable: true, writable: true, configurable: true } },
+	) as T;
+
 const SkillOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "array", items: { type: "string" } },
 		{ type: "boolean" },
 		{ type: "string" },
 	],
-	description: "Skill name(s) to inject (comma-separated), array of strings, or boolean (false disables, true uses default)",
+	description: "CSV/array/boolean (false disables, true default).",
 });
 
 const OutputOverride = Type.Unsafe({
@@ -24,7 +34,7 @@ const OutputOverride = Type.Unsafe({
 
 const OutputModeOverride = Type.String({
 	enum: ["inline", "file-only"],
-	description: "Return saved output inline (default) or only a concise file reference. file-only requires output to be a path.",
+	description: "inline (default) or file-only (needs output path).",
 });
 
 const ReadsOverride = Type.Unsafe({
@@ -38,7 +48,7 @@ const ReadsOverride = Type.Unsafe({
 const JsonSchemaObject = Type.Unsafe({
 	type: "object",
 	additionalProperties: true,
-	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
+	description: "Structured output; non-object rejected.",
 });
 
 const AcceptanceEvidenceKind = Type.String({
@@ -55,12 +65,13 @@ const AcceptanceEvidenceKind = Type.String({
 	],
 });
 
+// Gate-level `evidence`/`severity` are accepted at runtime (normalizeCriteria) but omitted
+// from the schema: dead flexibility from a tool call, and the evidence enum is heavy.
+// additionalProperties stays open so inputs carrying them are not provider-rejected.
 const AcceptanceGateSchema = Type.Object({
 	id: Type.String(),
 	must: Type.String(),
-	evidence: Type.Optional(Type.Array(AcceptanceEvidenceKind)),
-	severity: Type.Optional(Type.String({ enum: ["required", "recommended"] })),
-}, { additionalProperties: false });
+}, { additionalProperties: true });
 
 const AcceptanceVerifyCommandSchema = Type.Object({
 	id: Type.String(),
@@ -108,108 +119,123 @@ const AcceptanceOverride = Type.Unsafe({
 			additionalProperties: false,
 		},
 	],
-	description: "Optional acceptance policy. Omitted means auto-inferred; verified requires configured runtime commands.",
+	description: "Acceptance: auto if omitted; verified needs cmds.",
+});
+
+// Nested acceptance sites carry a compact stub instead of the full AcceptanceOverride:
+// inlined 5x it was 44% of the serialized schema. The full shape is documented once at
+// top-level `acceptance`; deep validation happens at the executor boundary
+// (validateAcceptanceInput), not provider-side. The object branch keeps a non-empty
+// `properties` because some providers reject bare {type:"object"} in function
+// declarations - the same wall that rules out $defs/$ref (see issue #6).
+// {const:false} is intentionally absent: deprecated shorthand, use level:"none".
+const AcceptanceOverrideStub = Type.Unsafe({
+	anyOf: [
+		{ type: "string", enum: ["auto", "none", "attested", "checked", "verified", "reviewed"] },
+		{ type: "object", additionalProperties: true, properties: { level: { type: "string" } } },
+	],
+	description: "Acceptance override; same shape as top-level acceptance.",
 });
 
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
 	cwd: Type.Optional(Type.String()),
-	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
-	output: Type.Optional(OutputOverride),
-	outputMode: Type.Optional(OutputModeOverride),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat N times (same settings)." })),
+	output: Type.Optional(brief(OutputOverride, "Output file path, or false.")),
+	outputMode: Type.Optional(brief(OutputModeOverride, "Default: inline.")),
 	reads: Type.Optional(ReadsOverride),
-	progress: Type.Optional(Type.Boolean({ description: "Omit or set false to disable progress.md tracking for this task; true enables it." })),
-	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
-	skill: Type.Optional(SkillOverride),
-	acceptance: Type.Optional(AcceptanceOverride),
+	progress: Type.Optional(Type.Boolean({ description: "true enables progress.md tracking; omit or false disables." })),
+	model: Type.Optional(Type.String()),
+	skill: Type.Optional(brief(SkillOverride, "Skill override.")),
+	acceptance: Type.Optional(AcceptanceOverrideStub),
 });
 
 // Parallel task item (within a parallel step)
 const ParallelTaskSchema = Type.Object({
 	agent: Type.String(),
-	task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
-	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-	label: Type.Optional(Type.String({ description: "Optional user-facing label for this parallel task." })),
-	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
-	outputSchema: Type.Optional(JsonSchemaObject),
+	task: Type.Optional(Type.String({ description: "{task},{previous},{chain_dir} template; defaults to {previous}." })),
+	phase: Type.Optional(Type.String()),
+	label: Type.Optional(Type.String()),
+	as: Type.Optional(Type.String({ description: "Identifier for {outputs.name}." })),
+	outputSchema: Type.Optional(brief(JsonSchemaObject, "Output JSON Schema.")),
 	cwd: Type.Optional(Type.String()),
-	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
-	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: Type.Optional(Type.String({ description: "Override model for this task" })),
-	acceptance: Type.Optional(AcceptanceOverride),
+	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat N times." })),
+	output: Type.Optional(brief(OutputOverride, "Output file path, or false.")),
+	outputMode: Type.Optional(brief(OutputModeOverride, "Default: inline.")),
+	reads: Type.Optional(brief(ReadsOverride, "Reads first, or false.")),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking." })),
+	model: Type.Optional(Type.String()),
+	skill: Type.Optional(brief(SkillOverride, "Skill override.")),
+	acceptance: Type.Optional(AcceptanceOverrideStub),
 });
 
 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." }),
+		output: Type.String({ description: "Named prior output." }),
+		path: Type.String({ description: "JSON Pointer into it." }),
 	}, { 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.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." })),
+	item: Type.Optional(Type.String({ description: "Defaults to item." })),
+	key: Type.Optional(Type.String({ description: "Pointer per item; stable child id." })),
+	maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required unless chain.dynamicFanout.maxItems is configured." })),
+	onEmpty: Type.Optional(Type.String({ enum: ["skip", "fail"], description: "Defaults to skip." })),
 }, { additionalProperties: false });
 
 const DynamicParallelTemplateSchema = Type.Object({
 	agent: Type.String(),
-	task: Type.Optional(Type.String({ description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, and {outputs.name} variables." })),
-	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-	label: Type.Optional(Type.String({ description: "Optional user-facing label; item templates are supported." })),
-	outputSchema: Type.Optional(JsonSchemaObject),
+	task: Type.Optional(Type.String({ description: "{item},{item.path},{task},{previous},{chain_dir},{outputs.name} template." })),
+	phase: Type.Optional(Type.String()),
+	label: Type.Optional(Type.String({ description: "Label; item templates supported." })),
+	outputSchema: Type.Optional(brief(JsonSchemaObject, "Output JSON Schema.")),
 	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: Type.Optional(Type.String({ description: "Override model for this task" })),
-	acceptance: Type.Optional(AcceptanceOverride),
+	output: Type.Optional(brief(OutputOverride, "Output file path, or false.")),
+	outputMode: Type.Optional(brief(OutputModeOverride, "Default: inline.")),
+	reads: Type.Optional(brief(ReadsOverride, "Reads first, or false.")),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking." })),
+	model: Type.Optional(Type.String()),
+	skill: Type.Optional(brief(SkillOverride, "Skill override.")),
+	acceptance: Type.Optional(AcceptanceOverrideStub),
 }, { additionalProperties: false });
 
 const DynamicCollectSchema = Type.Object({
-	as: Type.String({ description: "Safe output name for the ordered collected result array." }),
-	outputSchema: Type.Optional(JsonSchemaObject),
+	as: Type.String({ description: "Collected result array name." }),
+	outputSchema: Type.Optional(brief(JsonSchemaObject, "Output JSON Schema.")),
 }, { additionalProperties: false });
 
 // Flattened so chain steps do not need an object-shape anyOf/oneOf union.
 const ChainItem = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
+	agent: Type.Optional(Type.String()),
 	task: Type.Optional(Type.String({
-		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
+		description: "{task},{previous},{chain_dir},{outputs.name}; required first else '{previous}'."
 	})),
-	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-	label: Type.Optional(Type.String({ description: "Optional user-facing label for this chain step." })),
-	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
+	phase: Type.Optional(Type.String({ description: "Phase/group label (status/graph)." })),
+	label: Type.Optional(Type.String({ description: "Chain step label." })),
+	as: Type.Optional(Type.String({ description: "Id for {outputs.name} in later steps." })),
 	outputSchema: Type.Optional(JsonSchemaObject),
 	cwd: Type.Optional(Type.String()),
-	output: Type.Optional(OutputOverride),
-	outputMode: Type.Optional(OutputModeOverride),
-	reads: Type.Optional(ReadsOverride),
+	output: Type.Optional(brief(OutputOverride, "Output file path, or false.")),
+	outputMode: Type.Optional(brief(OutputModeOverride, "Default: inline.")),
+	reads: Type.Optional(brief(ReadsOverride, "Reads first, or false.")),
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
-	skill: Type.Optional(SkillOverride),
-	model: Type.Optional(Type.String({ description: "Override model for this step" })),
-	acceptance: Type.Optional(AcceptanceOverride),
+	model: Type.Optional(Type.String()),
+	skill: Type.Optional(brief(SkillOverride, "Skill override.")),
+	acceptance: Type.Optional(AcceptanceOverrideStub),
 	parallel: Type.Optional(Type.Unsafe({
 		anyOf: [
-			Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
+			Type.Array(ParallelTaskSchema, { minItems: 1 }),
 			DynamicParallelTemplateSchema,
 		],
-		description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
+		description: "Static array, or dynamic fanout template (expand/collect).",
 	})),
 	expand: Type.Optional(DynamicExpandSchema),
 	collect: Type.Optional(DynamicCollectSchema),
 	concurrency: Type.Optional(Type.Number({ 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: "Isolated worktree per task."
 	})),
 }, {
-	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
+	description: "{agent,task?} seq; {parallel:[..]} concurrent; {expand,parallel,collect} fanout.",
 	additionalProperties: false,
 	allOf: [
 		{ if: { required: ["expand"] }, then: { required: ["parallel", "collect"], properties: { parallel: { type: "object" } } } },
@@ -219,44 +245,44 @@ const ChainItem = Type.Object({
 });
 
 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-observed-activity window before a run needs attention" })),
-	activeNoticeAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Active-long-running notice threshold by elapsed ms (default: 240000)" })),
-	inFlightSilenceCeilingMs: Type.Optional(Type.Integer({ minimum: 1, description: "How long a silent in-flight turn stays calm (active_long_running) before re-escalating to needs_attention (default: 600000)" })),
-	inFlightSilenceKillMs: Type.Optional(Type.Integer({ minimum: 1, description: "Hard cap: SIGTERM a child whose in-flight turn has been silent this long (default: 1800000; clamped to sit above the needs_attention escalation)" })),
-	activeNoticeAfterTurns: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by assistant turns (disabled by default)" })),
-	activeNoticeAfterTokens: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by total tokens (disabled by default)" })),
-	failedToolAttemptsBeforeAttention: Type.Optional(Type.Integer({ minimum: 1, description: "Consecutive mutating-tool failures before escalating to needs_attention (default: 3)" })),
+	enabled: Type.Optional(Type.Boolean({ description: "Toggle attention tracking." })),
+	needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-activity window before needs_attention." })),
+	activeNoticeAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Elapsed-ms notice threshold (default: 240000)." })),
+	inFlightSilenceCeilingMs: Type.Optional(Type.Integer({ minimum: 1, description: "Silent ms before escalation (default: 600000)." })),
+	inFlightSilenceKillMs: Type.Optional(Type.Integer({ minimum: 1, description: "SIGTERM child (default: 1800000, clamped above needs_attention)." })),
+	activeNoticeAfterTurns: Type.Optional(Type.Integer({ minimum: 1, description: "Notice by assistant turns (off by default)." })),
+	activeNoticeAfterTokens: Type.Optional(Type.Integer({ minimum: 1, description: "Notice by total tokens (off by default)." })),
+	failedToolAttemptsBeforeAttention: Type.Optional(Type.Integer({ minimum: 1, description: "Mutating-tool failures before needs_attention (default: 3)." })),
 	notifyOn: Type.Optional(Type.Array(Type.String({ enum: ["active_long_running", "needs_attention"] }), {
-		description: "Control event types that should notify the parent/orchestrator. Defaults to active_long_running and needs_attention.",
+		description: "To parent (default: active_long_running, needs_attention).",
 	})),
 	notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
-		description: "Notification channels to use when available. Defaults to event, async, and intercom.",
+		description: "Default: event, async, intercom.",
 	})),
 });
 
 export const SubagentParams = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
-	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	agent: Type.Optional(Type.String({ description: "SINGLE mode agent, or management target." })),
+	task: Type.Optional(Type.String({ description: "Task (SINGLE mode; optional if self-contained)." })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
 		enum: [...SUBAGENT_ACTIONS],
 		description: "Management/control action. Omit for execution mode."
 	})),
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for action='status', action='interrupt', or action='resume'."
+		description: "Run id/prefix for status/interrupt/resume."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for action='interrupt' or action='resume'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
+		description: "Run ID (interrupt/resume); defaults to latest. Prefer id."
 	})),
 	dir: Type.Optional(Type.String({
-		description: "Async run directory for action='status' or action='resume'."
+		description: "Async run dir 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 message for action='resume'. Use index to choose a child from multi-child runs." })),
+	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based index for per-child actions." })),
+	message: Type.Optional(Type.String({ description: "Follow-up message for resume." })),
 	// 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"
+		description: "Chain name."
 	})),
 	// Agent/chain configuration for create/update (nested to avoid conflicts with execution fields)
 	config: Type.Optional(Type.Unsafe({
@@ -264,32 +290,30 @@ export const SubagentParams = Type.Object({
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
+		description: "Create/update config; fields: pi-cohort skill reference/config-fields.md; string=JSON."
 	})),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
-	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode tasks: [{agent, task, ...}]." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Default: config.parallel.concurrency or 4." })),
 	worktree: Type.Optional(Type.Boolean({
-		description: "Create isolated git worktrees for each parallel task. " +
-			"Prevents filesystem conflicts. Requires clean git state. " +
-			"Per-worktree diffs included in output."
+		description: "Isolated worktree per task; clean git; diffs in output."
 	})),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. Use {task}, {previous}, {chain_dir} in task templates." })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN: sequential; step response becomes {previous}." })),
 	context: Type.Optional(Type.String({
 		enum: ["fresh", "fork"],
-		description: "'fresh' or 'fork' to branch from parent session. If omitted, any requested agent with defaultContext: 'fork' makes the whole invocation forked; otherwise the default is 'fresh'.",
+		description: "fresh (default) or fork; defaultContext:fork forces whole invocation.",
 	})),
-	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: a user-scoped temp directory under <tmpdir>/ (auto-cleaned after 24h)" })),
-	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
+	chainDir: Type.Optional(Type.String({ description: "Default temp <tmpdir>/, 24h clean." })),
+	async: Type.Optional(Type.Boolean({ description: "Background run (default: false, or per config)." })),
+	agentScope: Type.Optional(Type.String({ description: "user/project/both (default both, project wins)." })),
 	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)" })),
-	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
+	artifacts: Type.Optional(Type.Boolean({ description: "(default: true)." })),
+	includeProgress: Type.Optional(Type.Boolean({ description: "(default: false)." })),
+	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist (default: false)." })),
 	sessionDir: Type.Optional(
-		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
+		Type.String({ description: "Default temp; enables sessions even if share=false." }),
 	),
 	// Clarification TUI
-	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution. Omitted or false launches directly. Explicit clarify: true keeps the run foreground for the clarify UI when supported; chains containing parallel steps skip the UI." })),
+	clarify: Type.Optional(Type.Boolean({ description: "Preview/edit TUI; omitted/false runs directly; true=foreground (if supported); parallel-step chains skip it." })),
 	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Unsafe({
@@ -297,10 +321,10 @@ export const SubagentParams = Type.Object({
 			{ type: "string" },
 			{ type: "boolean" },
 		],
-		description: "Omit or set false to disable file output; true uses the agent-configured filename; a string sets the output path. Relative paths resolve against cwd.",
+		description: "Omit or false disables; true=agent-configured filename; string=path (rel. cwd).",
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
-	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
+	model: Type.Optional(Type.String({ description: "Model override, e.g. 'anthropic/claude-sonnet-4'." })),
 	acceptance: Type.Optional(AcceptanceOverride),
 });

package/src/runs/foreground/subagent-executor.ts

@@ -17,6 +17,7 @@ import { recordSyncCost, renderGrandTotal, sumNestedCost } from "../../extension
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
 import { aggregateParallelOutputs } from "../shared/parallel-utils.ts";
 import { recordRun } from "../shared/run-history.ts";
+import { validateAcceptanceInput } from "../shared/acceptance.ts";
 import {
 	buildChainInstructions,
 	writeInitialProgressFile,
@@ -858,6 +859,33 @@ function validateExecutionInput(
 		}
 	}
 
+	// Nested acceptance sites only carry a compact stub in the tool schema (see
+	// AcceptanceOverrideStub in extension/schemas.ts); this is the deep-validation boundary.
+	const acceptanceErrors: string[] = [
+		...validateAcceptanceInput(params.acceptance, "acceptance"),
+	];
+	for (const [i, task] of (params.tasks ?? []).entries()) {
+		acceptanceErrors.push(...validateAcceptanceInput(task.acceptance, `tasks[${i}].acceptance`));
+	}
+	for (const [i, rawStep] of (params.chain ?? []).entries()) {
+		const step = rawStep as ChainStep;
+		acceptanceErrors.push(...validateAcceptanceInput((rawStep as { acceptance?: unknown }).acceptance, `chain[${i}].acceptance`));
+		if (isParallelStep(step)) {
+			for (const [j, member] of step.parallel.entries()) {
+				acceptanceErrors.push(...validateAcceptanceInput(member.acceptance, `chain[${i}].parallel[${j}].acceptance`));
+			}
+		} else if (isDynamicParallelStep(step)) {
+			acceptanceErrors.push(...validateAcceptanceInput(step.parallel.acceptance, `chain[${i}].parallel.acceptance`));
+		}
+	}
+	if (acceptanceErrors.length > 0) {
+		return {
+			content: [{ type: "text", text: `Invalid acceptance input:\n${acceptanceErrors.map((error) => `- ${error}`).join("\n")}` }],
+			isError: true,
+			details: { mode: hasChain ? "chain" as const : hasTasks ? "parallel" as const : "single" as const, results: [] },
+		};
+	}
+
 	return null;
 }
 

package/src/runs/shared/acceptance.ts

@@ -131,6 +131,8 @@ function explicitAcceptanceCanDisable(explicit: AcceptanceConfig): boolean {
 	return explicit.level === "none" && typeof explicit.reason === "string" && explicit.reason.trim().length > 0;
 }
 
+const KNOWN_ACCEPTANCE_KEYS = new Set(["level", "criteria", "evidence", "verify", "review", "stopRules", "reason"]);
+
 export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"): string[] {
 	const errors: string[] = [];
 	if (input === undefined) return errors;
@@ -144,6 +146,11 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 		return errors;
 	}
 	const value = input as Record<string, unknown>;
+	for (const key of Object.keys(value)) {
+		if (!KNOWN_ACCEPTANCE_KEYS.has(key)) {
+			errors.push(`${pathLabel}.${key} is not a recognized acceptance field (known: level, criteria, evidence, verify, review, stopRules, reason).`);
+		}
+	}
 	if (value.level !== undefined && (typeof value.level !== "string" || !VALID_LEVELS.has(value.level as AcceptanceLevel))) {
 		errors.push(`${pathLabel}.level must be one of auto, none, attested, checked, verified, reviewed.`);
 	}