@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -3,6 +3,8 @@
  */
 
 import { Type } from "typebox";
+import type { DisabledFeatureSurface } from "../shared/disabled-features.ts";
+import { MAX_ARGS_BYTES, MAX_ARGS_DEPTH, MAX_ARGS_FIELDS, MAX_ARGS_ITEMS } from "../workflows/workflow-resources.ts";
 
 function keepTopLevelParameterDescriptions<T>(schema: T): T {
 	return pruneNestedDescriptions(schema, []) as T;
@@ -35,47 +37,24 @@ const SkillOverride = Type.Unsafe({
 		{ type: "boolean" },
 		{ type: "string" },
 	],
-	description: "Skill name(s) to make available (comma-separated), array of strings, or boolean (false disables, true uses default)",
-});
-
-const OutputOverride = Type.Unsafe({
-	anyOf: [
-		{ type: "string" },
-		{ type: "boolean" },
-	],
-	description: "Output filename/path (string), or false to disable file output",
+	description: "Skills: names/CSV/array; false disables, true uses default.",
 });
 
 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.",
-});
-
-const ReadsOverride = Type.Unsafe({
-	anyOf: [
-		{ type: "array", items: { type: "string" } },
-		{ type: "boolean" },
-	],
-	description: "Files to read before running (array of filenames), or false to disable",
+	description: "Default inline; file-only requires output path.",
 });
 
 const JsonSchemaObject = Type.Unsafe({
 	type: "object",
 	additionalProperties: true,
-	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
+	description: "Strict structured output; object-root JSON Schema only.",
 });
 
-const AcceptanceEvidenceKinds = [
-	"changed-files",
-	"tests-added",
-	"commands-run",
-	"validation-output",
-	"residual-risks",
-	"no-staged-files",
-	"diff-summary",
-	"review-findings",
-	"manual-notes",
-];
+const OutputSchemaOverride = Type.Unsafe({
+	anyOf: [JsonSchemaObject, { type: "boolean" }],
+	description: "Structured output schema override; false disables an agent default.",
+});
 
 // Provider boolean branches intentionally overapproximate false-only runtime inputs.
 // Restricted function-declaration converters only support string enum members.
@@ -90,22 +69,18 @@ const AcceptanceOverride = Type.Unsafe({
 		},
 		{
 			type: "string",
+			pattern: "^\\s*\\{[\\s\\S]*$",
 		},
 		{ type: "boolean" },
 		{ type: "object", additionalProperties: true },
 	],
-	description: `Optional acceptance policy. false disables acceptance; true is invalid. Prefer an inline JSON object. JSON-encoded object strings are tolerated only during input normalization; invalid strings fail closed. Reviewer/read-only calls, omit acceptance. { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(",")}. acceptance.review.required.`,
+	description: "Evidence policy; omit for read-only/review. false disables; true invalid. Prefer object; see guide tool-reference for levels, evidence and review.required.",
 });
 
 const AgentContractOverride = Type.Object({
 	version: Type.Integer({ minimum: 1, maximum: 1, description: "Enable compatibility behavior for this run/child." }),
 }, { additionalProperties: false, description: "Compatibility behavior. Omit for the default behavior." });
 
-const ChainGateOverride = Type.String({
-	enum: ["execution", "acceptance"],
-	description: "For chain steps with agentContract, choose whether the chain advances on execution success or acceptance success. Defaults to execution.",
-});
-
 const WorkflowLaneMetadata = Type.Object({
 	version: Type.Integer({ minimum: 1, maximum: 1 }),
 	key: Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }),
@@ -113,7 +88,7 @@ const WorkflowLaneMetadata = Type.Object({
 	sourceRef: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
 	claims: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 160 }), { maxItems: 20 })),
 	outputPaths: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 10 })),
-}, { additionalProperties: false, description: "Optional bounded child lane metadata. Display/triage only; sourceRef is opaque and never resolved during status rendering." });
+}, { additionalProperties: false, description: "Display/triage only; sourceRef is opaque, never resolved by status." });
 
 const ToolBudgetBlock = Type.Unsafe({
 	anyOf: [
@@ -126,7 +101,7 @@ const ToolBudgetOverride = Type.Object({
 	soft: Type.Optional(Type.Integer({ minimum: 1 })),
 	hard: Type.Integer({ minimum: 1 }),
 	block: Type.Optional(ToolBudgetBlock),
-}, { additionalProperties: false, description: "Optional child tool-call budget. soft nudges the child; after hard, block tools (default read/grep/find/ls, or '*' for all tools) are blocked so the child can finalize." });
+}, { additionalProperties: false, description: "soft <= hard; after hard block read/grep/find/ls or '*' for all." });
 
 const UsageBudgetLimitOverride = Type.Object({
 	soft: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
@@ -136,7 +111,7 @@ const UsageBudgetLimitOverride = Type.Object({
 const UsageBudgetOverride = Type.Object({
 	tokens: Type.Optional(UsageBudgetLimitOverride),
 	costUsd: Type.Optional(UsageBudgetLimitOverride),
-}, { additionalProperties: false, description: "Optional root-only reported-usage budget. Hard limits prevent future child launches; running children are not stopped." });
+}, { additionalProperties: false, minProperties: 1, description: "tokens or costUsd; soft <= hard. Root-only reported usage; blocks launches. Running children are not stopped." });
 
 const WorkflowPreflightLane = Type.Object({
 	key: Type.String({ minLength: 1, maxLength: 128 }),
@@ -151,107 +126,7 @@ const WorkflowPreflightOverride = Type.Object({
 	version: Type.Integer({ minimum: 1, maximum: 1 }),
 	coverage: Type.Optional(Type.String({ enum: ["complete", "partial"] })),
 	lanes: Type.Array(WorkflowPreflightLane, { maxItems: 64 }),
-}, { additionalProperties: false, description: "Bounded display-only lane hints for workflow launch/status. Coverage mismatches warn but never change launch authority or execution." });
-
-// Parallel task item (within a parallel step)
-export 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),
-	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" })),
-	fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-	toolBudget: Type.Optional(ToolBudgetOverride),
-	acceptance: Type.Optional(AcceptanceOverride),
-	agentContract: Type.Optional(AgentContractOverride),
-	gateOn: Type.Optional(ChainGateOverride),
-});
-
-export 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.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." })),
-}, { additionalProperties: false });
-
-export 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),
-	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" })),
-	fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-	toolBudget: Type.Optional(ToolBudgetOverride),
-	acceptance: Type.Optional(AcceptanceOverride),
-	agentContract: Type.Optional(AgentContractOverride),
-	gateOn: Type.Optional(ChainGateOverride),
-}, { additionalProperties: false });
-
-export 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 ChainItem = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
-	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."
-	})),
-	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." })),
-	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: Type.Optional(Type.String({ description: "Override model for this step" })),
-	fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-	toolBudget: Type.Optional(ToolBudgetOverride),
-	acceptance: Type.Optional(AcceptanceOverride),
-	agentContract: Type.Optional(AgentContractOverride),
-	gateOn: Type.Optional(ChainGateOverride),
-	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.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: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
-	additionalProperties: false,
-});
+}, { additionalProperties: false, description: "workflow: true or a script path only; display-only hints; coverage warns." });
 
 // Runtime mission handlers validate these untrusted nested objects loudly. Keeping
 // their provider schema shallow avoids repeating a full durable-record schema in
@@ -280,58 +155,60 @@ const ControlOverrides = Type.Object({
 });
 
 const SubagentParamProperties = {
-	agent: Type.Optional(Type.String({ description: "Agent for one-child execution, or target for agent management actions." })),
-	task: Type.Optional(Type.String({ description: "Optional one-child task. Requires agent unless Jev subagent routing is enabled, in which case agent may be omitted to let Jev choose by function; cannot combine with action, workflowScript, or workflowScriptPath." })),
-	extensionBindings: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Namespaced, bounded plain-JSON metadata delivered only to the child runtime. Namespace keys use package.name/1 syntax." })),
+	agent: Type.Optional(Type.String({ description: "One-child agent or management target." })),
+	task: Type.Optional(Type.String({ description: "One-child task; requires agent unless Jev picks one." })),
+	extensionBindings: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Child-only plain JSON; package.name/1; depth 16, 256 props, 16 KiB." })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({ minLength: 1,
-		description: "Optional management/control action. Use action='validate' with workflowScript or workflowScriptPath for offline checks. Omit this field for structured single-child or workflow execution; otherwise, use it only for management/control actions."
+		description: "Management/control only; omit for execution. validate accepts workflow: true or a script path. Discover actions with guide topic tool-reference."
 	})),
-	capabilities: Type.Optional(Type.Boolean({ description: "For action='list', return compact capability rows and structured details without system prompts." })),
-	name: Type.Optional(Type.String({ description: "Human-readable name for action='schedule.create'." })),
+	capabilities: Type.Optional(Type.Boolean({ description: "list: compact capability rows/details without system prompts." })),
+	name: Type.Optional(Type.String({ description: "schedule.create name." })),
 	id: Type.Optional(Type.String({
-		description: "Run id/prefix for status/debug.run, interrupt, steer, or mission.attach-run."
+		description: "Run id/prefix for status/control."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for debug.run, interrupt, steer, or mission.attach-run. Prefer id."
+		description: "Target run ID; prefer id."
 	})),
 	dir: Type.Optional(Type.String({
-		description: "Async run directory for status/debug.run, stop, resume, or steer."
+		description: "Async directory for status/control."
 	})),
-	handoffPath: Type.Optional(Type.String({ description: "Existing parallel handoff manifest for worktree.discard, worktree.cleanup metadata, or lane evidence actions." })),
-	repo: Type.Optional(Type.String({ description: "Repository path for action='worktree.cleanup'; defaults to cwd." })),
-	planId: Type.Optional(Type.String({ description: "Cleanup plan id reserved for a future worktree.cleanup apply action." })),
-	laneId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Exact manifest run id for lane.status, lane.recordMerge, or lane.recordSupersession." })),
-	merge: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "Attested merge evidence for lane.recordMerge: prNumber, reviewedHead, mergeCommit, treeEquivalent, postMergeChecks, attestedBy, and attestedAt." })),
-	supersession: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "Attested replacement-lane evidence for lane.recordSupersession: supersededBy, attestedBy, and attestedAt." })),
-	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child or transcript." })),
-	childId: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Stable child identity for child-scoped stop requests." })),
+	handoffPath: Type.Optional(Type.String({ description: "Existing manifest for worktree/lane actions." })),
+	repo: Type.Optional(Type.String({ description: "Cleanup repo; apply requires it." })),
+	planId: Type.Optional(Type.String({ description: "Reviewed cleanup plan for apply." })),
+	laneId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Exact manifest run id for lane actions." })),
+	merge: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "lane.recordMerge evidence; read guide tool-reference." })),
+	supersession: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "lane.recordSupersession evidence; read guide tool-reference." })),
+	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child/transcript index." })),
+	childId: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Child-scoped stop identity." })),
+	toolCallId: Type.Optional(Type.String({ description: "Command tool-call id." })),
 	view: Type.Optional(Type.String({
 		enum: ["fleet", "transcript"],
-		description: "Optional status view. Use view='fleet' for a read-only active foreground/async fleet surface, or view='transcript' with id/dir (and optional index) to tail a run transcript.",
+		description: "status view: fleet overview or transcript tail with id/dir and optional index.",
 	})),
-	lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Maximum transcript lines for action='status', view='transcript'. Defaults to 80." })),
+	lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Transcript tail lines; default 80." })),
 	topic: Type.Optional(Type.String()),
-	message: Type.Optional(Type.String({ description: "Follow-up message for resume, live guidance for steer, or optional startup prompt for project.open." })),
-	mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto", "plan", "apply"], description: "Delivery mode for action='steer', or plan/apply mode for worktree.cleanup. worktree.cleanup currently supports plan only; apply/removal is not available yet." })),
-	steeringRecovery: Type.Optional(Type.Boolean({ description: "For action='steer', allow pause-and-revive recovery after a missed acknowledgment. Defaults true for direct tool calls in steer mode; extension RPC steering forces false so callers retain exact child ownership." })),
-	additional: Type.Optional(Type.Integer({ minimum: 1, description: "Positive launches to add with action='grant-spawn-budget'. Root interactive parent with native user confirmation only; total grants cannot exceed the original configured cap." })),
-	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session to avoid persistent settings writes unless user/project is explicit." })),
-	target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Target for watchdog actions." })),
-	focus: Type.Optional(Type.Boolean({ description: "Focus the new Herdr pane for inspector.open or project.open." })),
-	thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean" }], description: "Thinking level for action='watchdog.configure' only (off/minimal/low/medium/high/xhigh/max, inherit, or false for off; true is invalid). Ignored on dispatch; set per-run child thinking with a suffix on the model string, e.g. model: 'provider/id:high'." })),
-	at: Type.Optional(Type.String({ description: "One-shot trigger for action='schedule.create': a relative delay such as '+10m' or an ISO timestamp with timezone." })),
-	every: Type.Optional(Type.String({ description: "Fixed recurring interval for action='schedule.create', such as '30m', '6h', '2d', or '2w'." })),
+	message: Type.Optional(Type.String({ description: "resume/steer guidance or project.open prompt." })),
+	mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto", "plan", "apply"], description: "steer delivery; worktree.cleanup plan/apply (reviewed planId)." })),
+	steeringRecovery: Type.Optional(Type.Boolean({ description: "steer: pause/revive after missed acknowledgment; default true in direct steer mode, forced false by extension RPC for exact ownership." })),
+	additional: Type.Optional(Type.Integer({ minimum: 1, description: "grant-spawn-budget: root interactive parent + native user confirmation only; total grants capped at original configured cap." })),
+	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "watchdog.configure scope; default session, persistent only if explicit." })),
+	target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Watchdog target." })),
+	focus: Type.Optional(Type.Boolean({ description: "Focus inspector.open/project.open pane." })),
+	thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean" }], description: "watchdog.configure only: off/minimal/low/medium/high/xhigh/max, inherit, false=off; true invalid. Dispatch ignores this; use model suffix." })),
+	at: Type.Optional(Type.String({ description: "Delay/ISO or local HH:mm." })),
+	every: Type.Optional(Type.String({ description: "Duration or day/week." })),
 	sessionOnly: Type.Optional(Type.Boolean()),
-	on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Calendar selector reserved for a later schedule slice." })),
-	timezone: Type.Optional(Type.String()),
-	overlap: Type.Optional(Type.String({ enum: ["skip"], description: "Overlap policy. This slice supports skip only." })),
-	catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed occurrence policy for recurring schedules. Defaults to latest." })),
-	missionId: Type.Optional(Type.String({ description: "Mission id." })),
-	mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "Mission object, or false for no mission; true is invalid. Set exactly one non-empty title or summary; objective and labels are optional. goal may only be true and then requires budget.tokens." })),
-	missionUpdate: Type.Optional(Type.Unsafe({ ...MissionUpdateOverride, description: "Mission update: objective, goal false or {paused:boolean}, budget, summary, labels, decisions, artifacts, or delivery receipts." })),
-	missionStatus: Type.Optional(Type.String({ description: "Mission status." })),
-	missionScope: Type.Optional(Type.String({ description: "Mission list scope: project (default) or global pointer index." })),
+	quiet: Type.Optional(Type.Boolean()),
+	on: Type.Optional(Type.Array(Type.String({ enum: ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] }), { minItems: 1, description: "Weekly." })),
+	timezone: Type.Optional(Type.String({ description: "IANA/UTC." })),
+	overlap: Type.Optional(Type.String({ enum: ["skip"] })),
+	catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed; default latest." })),
+	missionId: Type.Optional(Type.String({ description: "Existing mission to attach to a workflow or schedule.create; read guide missions for lifecycle and retention." })),
+	mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "false disables; true invalid. Object: exactly one non-empty title or summary; objective/labels optional; goal only true, requires budget.tokens." })),
+	missionUpdate: Type.Optional(Type.Unsafe({ ...MissionUpdateOverride, description: "Mission patch; read guide missions." })),
+	missionStatus: Type.Optional(Type.String()),
+	missionScope: Type.Optional(Type.String({ description: "project (default) or global pointer index." })),
 	runMode: Type.Optional(Type.String({ description: "Attached run mode." })),
 	runStatus: Type.Optional(Type.String({ description: "Attached run status." })),
 	summary: Type.Optional(Type.String({ description: "Mission close summary." })),
@@ -341,37 +218,40 @@ const SubagentParamProperties = {
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent config for create/update. Object or JSON string."
+		description: "create/update agent config; object or JSON string."
+	})),
+	workflow: Type.Optional(Type.Unsafe<string | true>({
+		anyOf: [{ type: "boolean" }, { type: "string", minLength: 1 }],
+		description: "true: run the one ```js workflow block written in this same reply (false invalid). String with '/': script file read from request cwd. Other string: named workflow resource. Raw scripts (true or path) have no runs.host.",
 	})),
-	workflow: Type.Optional(Type.String({ minLength: 1, description: "Extension-owned workflow resource; resolves its script and authority internally." })),
-	args: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Bounded plain-JSON args for workflow; resource validation applies." })),
-	workflowScript: Type.Optional(Type.String({ minLength: 1, description: "Inline JavaScript statement body with unknown resource provenance. Normally async unless asyncByDefault:false; set async:true for async workflows and async:false only when the parent must block. Use explicit return, top-level await, plain helper functions, or explicit Promise chains. Nested async function, arrow, and method helpers are rejected. Globals: runs, emit, console, and mission state when enabled. No filesystem, shell, Pi tools, or host globals except through runs.host." })),
-	workflowScriptPath: Type.Optional(Type.String({ minLength: 1, description: "Path to a JavaScript workflow file with unknown resource provenance. Mutually exclusive with workflowScript and workflow. Relative paths resolve against the request cwd. The host reads the file before the filesystem-free workflow sandbox starts." })),
+	args: Type.Optional(Type.Unsafe({ type: "object", maxProperties: MAX_ARGS_FIELDS, additionalProperties: true, description: `Plain-JSON args for workflow; ${MAX_ARGS_FIELDS} fields/object, ${MAX_ARGS_ITEMS} items/array, depth ${MAX_ARGS_DEPTH}, ${MAX_ARGS_BYTES / 1024} KiB total; raw-script args are exposed deeply frozen and persisted, so do not include secrets.` })),
 	globalConcurrencyLimit: Type.Optional(Type.Integer({ minimum: 1 })),
 	maxSubagentSpawnsPerRun: Type.Optional(Type.Integer({ minimum: 1 })),
 	preflight: Type.Optional(WorkflowPreflightOverride),
-	chatProgress: Type.Optional(Type.String({ enum: ["auto", "off", "live-card"], description: "WorkflowScript chat progress projection. auto shows a live in-chat card only for watched foreground workflows in the same Git repository; it is off otherwise. Explicit live-card requires same-repository async:false; async workflows should omit chatProgress or use auto/off." })),
-	isolation: Type.Optional(Type.String({ enum: ["none", "worktree"], description: "Workflow child isolation. none runs in the shared cwd; worktree requires managed git worktree isolation." })),
-	worktree: Type.Optional(Type.Boolean({ description: "Managed child isolation. true gives each workflow child a separate git worktree; an individual runs.run/runs.all item can override a workflow default with worktree:false." })),
+	chatProgress: Type.Optional(Type.String({ enum: ["auto", "off", "live-card"], description: "auto: live card only for watched foreground in same Git repository. live-card requires same-repo async:false; async: omit or auto/off." })),
+	isolation: Type.Optional(Type.String({ enum: ["none", "worktree"], description: "Shared cwd or managed git worktrees." })),
+	worktree: Type.Optional(Type.Boolean({ description: "Isolate each workflow child in a managed git worktree; child worktree:false overrides default." })),
 	baseRef: Type.Optional(Type.String()),
 	lane: Type.Optional(WorkflowLaneMetadata),
 	context: Type.Optional(Type.String({
 		enum: ["fresh", "fork", "profile"],
-		description: "'fresh' or 'fork' to branch from parent session, or 'profile' to require the selected agent's declared defaultContext. Explicit fresh/fork overrides every child; profile ignores config defaultSubagentContext and fails when an agent has no defaultContext. If omitted, config defaultSubagentContext wins over each agent defaultContext; implicit fork needs a persisted parent session and leaf, else fresh. Config forkContext may prune resolved forks before spawn without adding another context value.",
+		description: "fresh/fork overrides every child; profile requires agent's declared defaultContext, ignoring config. Omitted: defaultSubagentContext wins over each agent defaultContext; implicit fork needs persisted parent + leaf, else fresh. forkContext may prune forks before spawn.",
 	})),
-	async: Type.Optional(Type.Boolean({ description: "Run in background unless asyncByDefault:false. Set false only when the parent must block until completion." })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout. Foreground and single async runs use config timeoutMs, else 30m; async composites have no default parent deadline. Alias maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs. Foreground and single async runs use config timeoutMs, else 30m; async composites have no default parent deadline." })),
-	toolTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional hard per-tool-call timeout in milliseconds; known-fast built-in tools have a five-minute default." })),
+	async: Type.Optional(Type.Boolean({ description: "Background; default asyncByDefault. false only to block parent." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Foreground and single async runs use config timeoutMs, else 30m; async composites have no default parent deadline. Alias maxRuntimeMs; must agree." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs (same defaults)." })),
+	checkpointBeforeDeadlineMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 2_147_483_647, description: "Async single-agent runs only: the runner requests that the child checkpoint and stop this many ms before the run deadline (best-effort; the deadline kill still applies)." })),
+	toolTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Per-tool deadline (ms); fast builtins default 5m." })),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	usageBudget: Type.Optional(UsageBudgetOverride),
-	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
-	cwd: Type.Optional(Type.String({ description: "Execution cwd, or target project directory for project.open/status/close." })),
-	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)" })),
+	agentScope: Type.Optional(Type.String({ description: "user/project/both (default); project wins collisions." })),
+	cwd: Type.Optional(Type.String({ description: "Execution/project-pane directory." })),
+	machine: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Herdr saved machine id or label; runs an external CLI agent there. cwd then means the directory on that machine." })),
+	artifacts: Type.Optional(Type.Boolean({ description: "Debug artifacts; default true." })),
+	includeProgress: Type.Optional(Type.Boolean({ description: "Full result progress; 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: "Session log directory; default temp, independent of share." }),
 	),
 	control: Type.Optional(ControlOverrides),
 	// Workflow defaults forwarded to each runs.run/runs.all child unless overridden there.
@@ -380,24 +260,55 @@ const SubagentParamProperties = {
 			{ type: "string" },
 			{ type: "boolean" },
 		],
-		description: "Default child output file (string), or false to disable. Relative workflow child paths use managed artifact routing. Task filename prose is not an output declaration; for durable workflow handoff, return the child's outputReference, outputPathMapping, or artifactPaths.",
+		description: "Child output path or false; relative workflow paths use managed artifact routing. Bind durable output here, not task prose; return outputReference/outputPathMapping/artifactPaths.",
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
-	model: Type.Optional(Type.String({ description: "Default child model override. Full provider/id values are accepted; bare ids resolve from the active registry. Append a thinking suffix (off/minimal/low/medium/high/xhigh/max, e.g. 'provider/id:low') to set the child's thinking level for the run; the suffix wins over the agent's thinking default." })),
-	fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. Default false. This can increase quota or cost." })),
-	outputSchema: Type.Optional(JsonSchemaObject),
+	model: Type.Optional(Type.String({ description: "Child model provider/id; bare id only if unique. Suffix :off/minimal/low/medium/high/xhigh/max overrides agent thinking default." })),
+	fast: Type.Optional(Type.Boolean({ description: "Native OpenAI-Codex priority tier; default false, may cost more/quota." })),
+	outputSchema: Type.Optional(OutputSchemaOverride),
 	agentContract: Type.Optional(AgentContractOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
-	gate: Type.Optional(Type.String({ minLength: 1, description: "Host gate command. Cannot be combined with acceptance; an explicit acceptance of false is treated as omitted." })),
+	gate: Type.Optional(Type.Unsafe({
+		anyOf: [
+			{ type: "string", minLength: 1 },
+			{ type: "object", properties: { command: { type: "string", minLength: 1 }, output: { type: "string", enum: ["json"] }, schema: { type: "object" }, timeoutMs: { type: "integer", minimum: 1 } }, required: ["command"], additionalProperties: false },
+		],
+		description: "Host gate command run after the child finishes: a string, or an object; with output \"json\", passing stdout becomes structuredOutput (not with outputSchema). Cannot be combined with acceptance except false (treated as omitted).",
+	})),
 };
 
 const SubagentParamsSchema = Type.Object(SubagentParamProperties);
 
 export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);
 
-export function createSubagentParamsSchema(): typeof SubagentParams {
-	return SubagentParams;
+// Replaces workflow scripts when disabledFeatures lists "workflow-scripts". Kept small because every
+// field is sent on every request; the executor validates step shapes and placeholders strictly.
+const StructuredTask = { type: "object", properties: { agent: { type: "string", minLength: 1 }, task: { type: "string" } }, required: ["agent", "task"], additionalProperties: false };
+const StructuredWorkflowProperties = {
+	action: Type.Optional(Type.String({ minLength: 1, description: "Management/control only; omit for execution. Discover actions with guide topic tool-reference." })),
+	task: Type.Optional(Type.String({ description: "One-child task with agent, or the original request ({task}) with chain/tasks." })),
+	tasks: Type.Optional(Type.Unsafe({ type: "array", minItems: 1, items: StructuredTask, description: "Parallel children; results in order." })),
+	// Flattened step: {agent, task?, as?} or {parallel}; no object-shape union for provider converters.
+	chain: Type.Optional(Type.Unsafe({
+		type: "array",
+		minItems: 1,
+		items: { type: "object", properties: { agent: { type: "string", minLength: 1 }, task: { type: "string" }, as: { type: "string" }, parallel: { type: "array", minItems: 1, items: StructuredTask } }, additionalProperties: false },
+		description: "Sequential steps: {agent,task?,as?} or {parallel:[{agent,task}]}.",
+	})),
+};
+
+export function createSubagentParamsSchema(disabled?: DisabledFeatureSurface): typeof SubagentParams {
+	if (!disabled || disabled.params.size === 0) return SubagentParams;
+	const structured = disabled.features.has("workflow-scripts");
+	const enabledProperties = Object.fromEntries(Object.entries(SubagentParamProperties).flatMap(([name, schema]) => {
+		if (disabled.params.has(name)) return [];
+		if (structured && name === "action") return [[name, StructuredWorkflowProperties.action]];
+		if (structured && name === "task") return [[name, StructuredWorkflowProperties.task], ["tasks", StructuredWorkflowProperties.tasks], ["chain", StructuredWorkflowProperties.chain]];
+		return [[name, schema]];
+	}));
+	// SAFETY: only optional properties are dropped or added; the executor rejects disabled options and admits chain/tasks at runtime.
+	return keepTopLevelParameterDescriptions(Type.Object(enabledProperties)) as typeof SubagentParams;
 }
 
 const SubagentWaitParamsSchema = Type.Object({
@@ -419,4 +330,4 @@ const SubagentWaitParamsSchema = Type.Object({
 	})),
 });
 
-export const SubagentWaitParams = keepTopLevelParameterDescriptions(SubagentWaitParamsSchema);
+export const SubagentWaitParams = keepTopLevelParameterDescriptions(SubagentWaitParamsSchema);

package/dist/extensions/pi-subagents/src/extension/subagent-guide.ts

@@ -13,12 +13,21 @@ export const SUBAGENT_GUIDE_TOPICS = [
 	"models",
 	"watchdog",
 	"extension-api",
+	"council",
 ] as const;
 
 export type SubagentGuideTopic = (typeof SUBAGENT_GUIDE_TOPICS)[number];
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
+// /council must work under `pi --no-skills`, which drops the package skills from context,
+// so this topic serves the council skill together with the references it tells the model to read.
+const COUNCIL_FILES = [
+	"skills/council-mode/SKILL.md",
+	"skills/council-mode/references/pass-contracts.md",
+	"skills/pi-subagents/references/execution-controls.md",
+];
+
 function isGuideTopic(value: string): value is SubagentGuideTopic {
 	return (SUBAGENT_GUIDE_TOPICS as readonly string[]).includes(value);
 }
@@ -27,13 +36,12 @@ export function readSubagentGuide(topic = "overview", root = packageRoot): strin
 	if (!isGuideTopic(topic)) {
 		return `Unknown subagents guide topic '${topic}'. Valid topics: ${SUBAGENT_GUIDE_TOPICS.join(", ")}. No files were changed.`;
 	}
-	const filePath = topic === "overview"
-		? path.join(root, "README.md")
-		: path.join(root, "docs", `${topic}.md`);
+	const files = topic === "overview" ? ["README.md"] : topic === "council" ? COUNCIL_FILES : [path.join("docs", `${topic}.md`)];
 	try {
-		return fs.readFileSync(filePath, "utf-8");
+		const contents = files.map((file) => fs.readFileSync(path.join(root, file), "utf-8"));
+		return files.length === 1 ? contents[0]! : contents.map((content, index) => `<!-- ${files[index]} -->\n\n${content}`).join("\n\n");
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Failed to read packaged subagents guide '${topic}': ${message}`, { cause: error instanceof Error ? error : undefined });
 	}
-}
+}