pi-cohort 5.0.1 → 5.1.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [5.1.1] - 2026-08-07
+
+### Changed
+
+- subagent tool schema shrunk from 12,374 to 9,483 bytes serialized, plus ~600
+  chars off the tool description: the chain parallel-item schemas (both the
+  static array items and the dynamic fanout template) and `control` are now
+  permissive stubs (`additionalProperties: true`) keeping only structural keys
+  explicit (parallel: agent/task/count/as; control: enabled); the
+  MANAGEMENT/CONTROL description blocks compressed to one line each. Widening
+  only - every previously valid call stays valid; dynamic-template unknown
+  keys are still rejected at runtime (assertOnlyKeys), and the control field
+  table moved to the pi-cohort skill reference/config-fields.md.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "5.0.1",
+  "version": "5.1.1",
   "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

@@ -115,7 +115,7 @@ Use this when a broad diff has known reviewer findings across several items and
 
 Prefer `async: true`, `context: "fresh"` for planners/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
 
-When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
+When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. The template's `label` also supports item templates. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
 
 Example shape:
 

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

@@ -1,8 +1,8 @@
-# subagent `config` field reference
+# subagent field reference: `config` and call-time `control`
 
-Fields accepted by `subagent({ action: "create" | "update", config: {...} })`.
+Fields accepted by `subagent({ action: "create" | "update", config: {...} })`, plus the call-time `control` overrides (last section).
 `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.
+Scope (for `config`): 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
 
@@ -49,3 +49,20 @@ Per 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. |
+
+## Call-time `control` overrides
+
+Per-call attention-tracking overrides: `subagent({ ..., control: {...} })`. Run-level field - sits beside `tasks`/`chain`, not inside task items. The tool schema declares only `enabled`; all fields below are accepted (`additionalProperties: true`) and re-parsed defensively at runtime (`resolveControlConfig`, `src/runs/shared/subagent-control.ts`) - invalid values fall back to the defaults.
+
+| Field | Type | Meaning | Default |
+|---|---|---|---|
+| `enabled` | boolean | Toggle attention tracking. | `true` |
+| `needsAttentionAfterMs` | integer >= 1 | No-activity window before `needs_attention`. | `60000` |
+| `activeNoticeAfterMs` | integer >= 1 | Elapsed-ms threshold for the long-running notice. | `240000` |
+| `inFlightSilenceCeilingMs` | integer >= 1 | Silent ms in-flight before escalation. | `600000` |
+| `inFlightSilenceKillMs` | integer >= 1 | SIGTERM the child after this silent span (clamped above the needs-attention window). | `1800000` |
+| `activeNoticeAfterTurns` | integer >= 1 | Notice by assistant turns. | off |
+| `activeNoticeAfterTokens` | integer >= 1 | Notice by total tokens. | off |
+| `failedToolAttemptsBeforeAttention` | integer >= 1 | Mutating-tool failures before `needs_attention`. | `3` |
+| `notifyOn` | array of `"active_long_running"` \| `"needs_attention"` | Which events notify the parent. | both |
+| `notifyChannels` | array of `"event"` \| `"async"` \| `"intercom"` | Delivery channels. | all three |

package/src/extension/index.ts

@@ -439,18 +439,9 @@ CHAIN TEMPLATE VARIABLES (use in task strings):
 
 Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
 
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
-• { action: "list" } - discover executable agents/chains
-• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
-• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
-• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
-• { action: "delete", agent: "code-analysis.custom-agent" }
-• Use chainName for chain operations; packaged chains also use dotted runtime names
-
-CONTROL:
-• { action: "status", id: "..." } - inspect an async/background run by id or prefix
-• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
+MANAGEMENT: action=list/get/create/update/delete (chainName for chains; packaged agents use dotted names); config fields: pi-cohort skill reference/config-fields.md.
+
+CONTROL: action=status/interrupt/resume (id/runId, message, index); details: pi-cohort skill.
 
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,

package/src/extension/schemas.ts

@@ -65,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(),
@@ -121,6 +122,21 @@ const AcceptanceOverride = Type.Unsafe({
 	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(), 
@@ -132,26 +148,26 @@ const TaskItem = Type.Object({
 	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(brief(AcceptanceOverride, "Acceptance 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},{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 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(brief(AcceptanceOverride, "Acceptance override.")),
+// Parallel-item stubs (round two): structural/wiring keys stay explicit (agent/task,
+// count/as = arity + {outputs.name} routing); every per-task override (model, label,
+// phase, output, outputMode, reads, skill, cwd, progress, outputSchema, acceptance)
+// passes through additionalProperties and is documented in the pi-cohort skill.
+// Widening-only: dynamic-arm unknown keys are still rejected at runtime by
+// assertOnlyKeys (dynamic-fanout.ts); static-arm unknown keys were always ignored.
+const ParallelTaskSchema = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	required: ["agent"],
+	properties: {
+		agent: { type: "string" },
+		task: { type: "string", description: "{task},{previous},{chain_dir} template; defaults to {previous}." },
+		count: { type: "integer", minimum: 1, description: "Repeat N times." },
+		as: { type: "string", description: "Identifier for {outputs.name}." },
+	},
+	description: "Per-task overrides (model, label, output, skill, ...): pi-cohort skill.",
 });
 
 const DynamicExpandSchema = Type.Object({
@@ -165,21 +181,16 @@ const DynamicExpandSchema = Type.Object({
 	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: "{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(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(brief(AcceptanceOverride, "Acceptance override.")),
-}, { additionalProperties: false });
+const DynamicParallelTemplateSchema = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	required: ["agent"],
+	properties: {
+		agent: { type: "string" },
+		task: { type: "string", description: "{item},{item.path},{task},{previous},{chain_dir},{outputs.name} template." },
+	},
+	description: "Per-task overrides (model, label, output, skill, ...): pi-cohort skill.",
+});
 
 const DynamicCollectSchema = Type.Object({
 	as: Type.String({ description: "Collected result array name." }),
@@ -203,7 +214,7 @@ const ChainItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	model: Type.Optional(Type.String()),
 	skill: Type.Optional(brief(SkillOverride, "Skill override.")),
-	acceptance: Type.Optional(brief(AcceptanceOverride, "Acceptance override.")),
+	acceptance: Type.Optional(AcceptanceOverrideStub),
 	parallel: Type.Optional(Type.Unsafe({
 		anyOf: [
 			Type.Array(ParallelTaskSchema, { minItems: 1 }),
@@ -228,21 +239,14 @@ const ChainItem = Type.Object({
 	],
 });
 
-const ControlOverrides = Type.Object({
-	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: "To parent (default: active_long_running, needs_attention).",
-	})),
-	notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
-		description: "Default: event, async, intercom.",
-	})),
+// Control stub (round two): 10 fields collapsed; the full table lives in the pi-cohort
+// skill reference/config-fields.md. resolveControlConfig (subagent-control.ts) re-parses
+// every field defensively at runtime, so mistyped values degrade to defaults.
+const ControlOverrides = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	properties: { enabled: { type: "boolean" } },
+	description: "Attention-tracking overrides (needsAttentionAfterMs, notifyOn, ...); fields: pi-cohort skill reference/config-fields.md.",
 });
 
 export const SubagentParams = Type.Object({

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