pi-cohort 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [5.1.2] - 2026-08-07
+
+### Changed
+
+- Schema diet round three (subagent tool schema 9,483 -> 8,246 bytes serialized):
+  `tasks[]` items collapsed to the round-two stub form (overrides pass through,
+  documented in the pi-cohort skill), `ChainItem` allOf conditionals removed
+  (runtime-enforced at chain parse), and `runId` no longer advertised by the
+  tool schema - still accepted at runtime, `id` preferred.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "5.1.0",
+  "version": "5.1.2",
   "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, message, index); details: pi-cohort skill.
 
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,

package/src/extension/schemas.ts

@@ -137,37 +137,41 @@ const AcceptanceOverrideStub = Type.Unsafe({
 	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 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: "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),
+// tasks[] stub (round three): same treatment as ParallelTaskSchema below; structural keys
+// stay explicit (agent/task required, count = arity); every per-task override (model, output,
+// outputMode, reads, progress, skill, cwd, acceptance) passes through additionalProperties
+// and is documented in the pi-cohort skill. No `as` (no {outputs.name} wiring here) and no
+// `label` (TaskParam has no such field at this position). Widening-only: unknown keys were
+// already ignored at runtime.
+const TaskItem = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	required: ["agent", "task"],
+	properties: {
+		agent: { type: "string" },
+		task: { type: "string" },
+		count: { type: "integer", minimum: 1, description: "Repeat N times (same settings)." },
+	},
+	description: "Per-task overrides (model, output, reads, skill, ...): pi-cohort skill.",
 });
 
-// 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(AcceptanceOverrideStub),
+// 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({
@@ -181,21 +185,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(AcceptanceOverrideStub),
-}, { 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." }),
@@ -237,28 +236,16 @@ const ChainItem = Type.Object({
 }, {
 	description: "{agent,task?} seq; {parallel:[..]} concurrent; {expand,parallel,collect} fanout.",
 	additionalProperties: false,
-	allOf: [
-		{ if: { required: ["expand"] }, then: { required: ["parallel", "collect"], properties: { parallel: { type: "object" } } } },
-		{ if: { required: ["collect"] }, then: { required: ["expand", "parallel"], properties: { parallel: { type: "object" } } } },
-		{ not: { required: ["expand"], properties: { parallel: { type: "array", items: {} } } } },
-	],
 });
 
-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({
@@ -272,9 +259,6 @@ export const SubagentParams = Type.Object({
 	id: Type.Optional(Type.String({
 		description: "Run id/prefix for status/interrupt/resume."
 	})),
-	runId: Type.Optional(Type.String({
-		description: "Run ID (interrupt/resume); defaults to latest. Prefer id."
-	})),
 	dir: Type.Optional(Type.String({
 		description: "Async run dir for status/resume."
 	})),