@narumitw/pi-subagents 0.52.0 → 0.54.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-subagents)](https://www.npmjs.com/package/@narumitw/pi-subagents) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. By default, it exposes seven capability-specific tools: blocking batches, four detached lifecycle tools, side-effect-free inspection, and synchronous read-only consultation. Users can keep every delegation method, choose async-only delegation, retain only blocking delegation, or disable delegation while keeping inspection available.
+`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. By default, it exposes eight capability-specific tools: blocking batches, explicit autonomous workflow planning, four detached lifecycle tools, side-effect-free inspection, and synchronous read-only consultation. Users can keep every delegation method, choose async-only delegation, retain only blocking delegation, or disable delegation while keeping inspection available.
 
 Use it to split independent research, planning, implementation, and review work across focused workers. Under the default next-turn delivery policy, background delegation is for work the current response does not depend on. Opt-in auto-resume also supports final-answer-dependent background work by requesting a synthesis turn after completion.
 
@@ -11,6 +11,7 @@ Use it to split independent research, planning, implementation, and review work
 - Offers all delegation methods by default, with goal-oriented presets for async-only, blocking-only, or disabled delegation.
 - Adds `subagent_inspect` for bounded metadata without child launch, mailbox-content access, acknowledgement, or mutation.
 - Adds `subagent_consult` for one synchronous ephemeral child constrained to built-in `read`, `grep`, `find`, and `ls` tools (or a narrower agent allow-list).
+- Adds explicit `subagent_auto` requests that use one bounded read-only planning turn and a deterministic compiler to select the smallest justified existing workflow without changing omitted-field behavior.
 - Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
 - Lets users set a blocking parallel call's maximum worker count from 1 through 64 while keeping four-at-a-time execution.
 - Registers detached stateful lifecycle tools by default; completion can stay queued for the next turn or opt into an idle root synthesis turn.
@@ -22,7 +23,7 @@ Use it to split independent research, planning, implementation, and review work
 - Optionally loads project agents from `.pi/agents/*.md` with confirmation.
 - Provides a current-session-first `/subagents` manager, direct `settings|status|help` routes, and compatibility aliases for agent tools and retained agents.
 - Supports trust-aware per-task `cwd` policies, task-selected work, workflow, idle, turn, and tool-call budgets, deterministic timeout checkpoints, bounded abort-then-summary recovery, progress telemetry, and explicit Fast, Balanced, or Deep thinking profiles.
-- Renders all seven tools with Pi-native compact/expanded transcript rows; long-running blocking and consultation calls show bounded live activity.
+- Uses Pi-native tool rows throughout; blocking and consultation calls add bounded custom live activity.
 - Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
 - Enforces a recursion-depth guard and deterministic process-group termination.
 - Provides addressable stateful agents with follow-up, consolidated mailbox/management actions, idempotent spawn retries, context selection and preview, versioned structured outcomes, and persistence.
@@ -54,13 +55,13 @@ pi -e ./packages/pi-subagents
 
 ## 🛠️ Pi tool
 
-`pi-subagents` registers seven tools by default. Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
+`pi-subagents` registers eight tools by default. Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
 
 | Workflow | Registered tools |
 | --- | --- |
-| **All delegation methods** (default) | Existing five delegation/lifecycle tools, `subagent_inspect`, and `subagent_consult` |
+| **All delegation methods** (default) | Existing five delegation/lifecycle tools, `subagent_auto`, `subagent_inspect`, and `subagent_consult` |
 | **Async only** | Four detached lifecycle tools plus `subagent_inspect`; blocking `subagent` and `subagent_consult` are omitted |
-| **Blocking only** | `subagent`, `subagent_consult`, and `subagent_inspect` |
+| **Blocking only** | `subagent`, `subagent_auto`, `subagent_consult`, and `subagent_inspect` |
 | **Disabled** | `subagent_inspect` only; delegation is disabled |
 
 The preview compares the selection with the tools registered in the current session, even when a manual settings edit is pending, and remains read-only until confirmation. Escape or **Cancel** leaves settings unchanged. Tool removal requires an extension reload because Pi does not expose extension tool unregistration. To avoid aborting work or removing isolated worktrees during `session_shutdown`, workflow changes are blocked while detached agents are retained; finish or clear them through **Current agents** first. Pi owns reload-error reporting and does not return a success result to extensions, so the save notification also tells users to run `/reload` if the tool surface does not refresh.
@@ -68,6 +69,7 @@ The preview compares the selection with the tools registered in the current sess
 The available tools are:
 
 - `subagent` — delegate blocking single, parallel, fan-in, chained, panel-review, or explicit dependency-workflow tasks. The main agent cannot process queued steering until the call returns.
+- `subagent_auto` — explicitly request one read-only planning turn followed by deterministic compilation and, only when admitted, execution through the existing blocking workflow engine.
 - `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
 - `subagent_inspect` — inspect agent/model/run/runtime metadata without launching work or changing state.
 - `subagent_consult` — run one ephemeral read-only consultation and wait for its answer.
@@ -96,6 +98,7 @@ Choose the API by lifecycle:
 
 | Need | Use |
 | --- | --- |
+| The caller explicitly wants a high-level objective decomposed under an authority ceiling and aggregate budget | `subagent_auto`, when blocking delegation is enabled |
 | A delegated result is required before the root's next action under default next-turn delivery | Use one blocking `subagent` call when registered. In **Async only**, complete the critical-path work directly or switch workflows before delegating it |
 | Broad research/review the current response does not depend on | Prefer one `subagent_spawn` covering related branches, when lifecycle tools are enabled |
 | Final-answer-dependent broad work with `completionDelivery: "auto-resume"` | Prefer one `subagent_spawn`; completion requests a synthesis turn |
@@ -224,6 +227,70 @@ A blocking fan-out is reserved for output that must be synthesized before the ro
 }
 ```
 
+## 🧠 Explicit autonomous workflow planning
+
+`subagent_auto` is an opt-in surface separate from the large multi-mode `subagent` schema.
+It never intercepts ordinary prompts and does not change existing calls when omitted.
+The caller supplies one versioned objective, non-goals, required inputs, acceptance criteria, required evidence, an authority ceiling, an aggregate budget, and deterministic constraints.
+
+```json
+{
+  "request": {
+    "version": "pi-subagents:automation-request:v1",
+    "objective": "Implement and verify the package change",
+    "nonGoals": ["Do not publish or release"],
+    "requiredInputs": ["current trusted repository"],
+    "acceptanceCriteria": ["Focused and root checks pass"],
+    "requiredEvidence": ["test output", "final diff review"],
+    "authorityCeiling": {
+      "capabilities": ["implementation", "code-review"],
+      "tools": ["read", "bash", "edit", "write"],
+      "readPaths": ["packages/pi-subagents"],
+      "writePaths": ["packages/pi-subagents"],
+      "network": "unspecified",
+      "secrets": "unspecified",
+      "sideEffectPolicy": "mutating"
+    },
+    "aggregateBudget": {
+      "timeoutMs": 180000,
+      "maxTurns": 30,
+      "maxToolCalls": 60,
+      "maxTasks": 4,
+      "maxRevisions": 1
+    },
+    "constraints": {
+      "contextPressure": "high",
+      "maxMutatingWidth": 2,
+      "requireVerification": true,
+      "workspaceMode": "shared"
+    }
+  }
+}
+```
+
+The planner always uses the built-in `planner` with only `read`, `grep`, `find`, and `ls`, disabled extensions and session persistence, trust-aware prompt resources, a maximum 60-second planning deadline, and bounded turn/tool-call counts.
+The planner returns only `pi-subagents:workflow-plan:v1` JSON and cannot choose agents, grant authority, create descendants, or forge executor identities.
+The executor reserves at most one quarter of the aggregate timeout, turns, and tool calls for planning before compiling execution work.
+It rejects before planning when that reservation leaves no positive execution budget, and it narrows the request task ceiling to the configured blocking-task limit before compilation or persistence.
+
+The compiler validates strict unknown-field and UTF-8 bounds, relative scopes, cycles, artifacts, ownership, capability routes, aggregate budgets, task generations, integration ownership, and the two-mutating-worker limit before execution.
+Caller-level acceptance criteria and required evidence are merged into the authoritative terminal, integration-owner, and verifier contracts without exceeding contract item limits.
+Path ceilings are compiler and conflict-scheduling constraints, not operating-system filesystem isolation; use a container or sandbox when host-level containment is required.
+Network and secrets guarantees other than `"unspecified"` fail closed because the current executor cannot enforce them.
+It can narrow or reject a proposal and can add one verifier only within the caller's remaining authority and budget.
+Parent-owned, needs-input, planner-failed, and compiler-rejected outcomes launch no execution workers.
+Every admitted mutating workflow has one authoritative integration owner and one distinct `structured-v2` verifier before any mutating worker starts.
+Project-local agents are not selected by this first surface, workflow grandchildren are rejected, and `workspaceMode: "worktree"` fails closed until blocking workflow worktree execution is supported.
+
+Pending, needs-input, verification-rework, stale, or invalidated work can be revised through the internal `pi-subagents:workflow-plan-patch:v1` contract.
+Each accepted patch must match the current plan identity and workflow generation, rotates both identity and task generations, preserves accepted history/artifacts/receipts, and stops after the caller's revision limit.
+The initial tool surface does not expose free-form public graph editing.
+
+For compatibility or exact task control, use caller-authored `subagent.workflow`.
+Before downgrading, use that explicit workflow fallback and let active automation calls finish.
+Older releases do not register `subagent_auto` and ignore the separate versioned automation records under `~/.pi/agent/pi-subagents-workflows/`; no settings migration is required.
+No benchmark result in this release changes the default delegation policy or makes a production-quality claim.
+
 ## 🔎 Read-only inspection
 
 `subagent_inspect` is registered in every workflow, including disabled delegation. It never starts a child, sends or acknowledges mailbox messages, interrupts or closes a run, changes settings, refreshes providers, resolves credentials, or modifies files.
@@ -413,7 +480,55 @@ Run an explicit dependency workflow:
 }
 ```
 
-A verification-gated implementation declares one distinct verifier:
+Managed verified execution is an explicit per-workflow contract.
+The executor infers the final mutating integration owner when none is declared, synthesizes one distinct read-only verifier, runs declared deterministic checks in a disposable Git worktree overlaid with the submitted state, and accepts only the exact unchanged submitted state.
+Every deterministic check has a stable evidence ID, a direct executable with argument-array invocation, and an optional relative `cwd` and timeout.
+Only `git`, `node`, `npm`, and `npx` are accepted; shell command strings fail before child allocation.
+The integration owner must request `structured-v2`, declare a non-empty `writePaths` scope, and name current required evidence through its delegation contract.
+Every required evidence ID must match a currently passed executor-owned check; worker-authored artifact metadata never satisfies that binding.
+
+```json
+{
+  "workflow": {
+    "verifiedExecution": {
+      "verifierAgent": "reviewer",
+      "maxReworkCycles": 1,
+      "checks": [
+        {
+          "id": "focused-test",
+          "command": "npm",
+          "args": ["test", "--", "feature"],
+          "timeoutMs": 120000
+        }
+      ]
+    },
+    "tasks": [
+      {
+        "id": "implementation",
+        "agent": "worker",
+        "task": "Implement the contracted change.",
+        "writePaths": ["src", "test"],
+        "acceptanceCriteria": ["The focused regression test passes"],
+        "resultFormat": "structured-v2",
+        "contract": {
+          "version": "pi-subagents:delegation:v2",
+          "level": "full",
+          "taskId": "implementation",
+          "objective": "Implement the contracted change",
+          "requiredEvidence": ["focused-test"],
+          "sideEffectPolicy": "mutating"
+        }
+      }
+    ]
+  }
+}
+```
+
+An advanced caller may provide the verifier task instead of letting the executor synthesize it.
+That task must directly and only depend on the integration owner, use `structured-v2`, select the configured distinct verifier agent, and declare an enforced read-only contract without shell or custom tools.
+The executor narrows accepted verifier authority to `read` even when the selected agent normally has broader tools, and disables verifier extensions, skills, prompt templates, and inherited context files.
+
+The older explicit verifier contract remains available as a compatibility gate without managed integration:
 
 ```json
 {
@@ -461,10 +576,26 @@ A task that explicitly requires independent verification must have exactly one d
 The producer stops in `awaiting-verification`, its own passing verification claims remain untrusted, and ordinary downstream tasks stay blocked until the executor records an accepted verifier receipt.
 The verifier runs alone in a fresh subprocess context against one bounded Git-visible tree identity and must encode `verification-accepted`, `verification-rework`, or `verification-rejected` through the documented `structured-v2` status and reason fields.
 Dirty-tree identity covers at most 1 MiB across separately framed staged and unstaged binary diffs plus bounded non-ignored untracked paths and bytes; submodules, unsupported states, and changing trees fail closed.
-A rework or rejection preserves bounded evidence but does not replay the producer automatically.
-This acceptance gate does not isolate operating-system effects and does not make shared-workspace mutation into manager-controlled patch integration.
-Explicit workflow transitions are also atomically persisted as mode-0600, private-text-redacted snapshots for current-session `list_workflows` and `get_workflow` inspection; running and awaiting-verification tasks inspect as `interrupted`, and no prior side effect is automatically resumed.
-When a v1 ledger is restored, legacy self-reported verification flags and artifact trust are cleared because they have no executor receipt.
+The compatibility gate preserves bounded rework or rejection evidence but does not replay the producer automatically.
+
+With `verifiedExecution`, execution completion and acceptance are separate `pi-subagents:work-acceptance:v1` states.
+A worker's own verification, confidence, prose, consensus, or exit status cannot move `pending` acceptance to `accepted`.
+The executor-owned `pi-subagents:verification-receipt:v1` binds both tree captures, patch digest, changed paths, accepted scope, target and verifier generations and `ExecutionPlan` IDs, verifier identity, acceptance criteria, required current evidence, and bounded deterministic check receipts.
+Each receipt is capped at 12 KiB, each stored check stream at 2 KiB, and oversized acceptance evidence fails closed rather than expanding tool details.
+The verifier receives the original objective, current artifact metadata, immutable tree identity, and executor-owned check output rather than the worker narrative.
+Verifier mutation, a stale or replaced generation, a failed or unsafe check, missing evidence, wrong scope, patch, plan, tree, or identity, cancellation, timeout, and unsupported Git state all produce non-success.
+One verifier `rework` decision may rotate the worker and verifier generations when `maxReworkCycles` is `1`; prior grants are revoked, prior evidence remains history, only current requirements and findings are added, and a second rejection is terminal.
+Crashes, timeouts, cancellation, ambiguous settlement, and drift are never replayed.
+The disposable check worktree includes bounded tracked and non-ignored untracked files and is removed after checks.
+When the repository has a local `node_modules` directory, the worktree is nested beneath it so normal Node and npm resolution can read the installed dependency tree without copying it.
+The worktree isolates repository build output, but it does not make the installed dependency tree read-only and is not an operating-system sandbox for processes, network, secrets, absolute paths, or host credentials.
+The accepted state remains the selected shared workspace; no general patch merge or conflict resolver is added.
+
+Omitting `verifiedExecution` preserves prior workflow behavior, including the older explicit verifier gate above.
+To downgrade, finish active workflows, remove `verifiedExecution`, and either use the explicit `verifierFor` compatibility form or perform verification in the parent.
+Older package versions reject the unknown managed contract rather than silently providing its guarantees.
+Explicit workflow transitions are atomically persisted as mode-0600, private-text-redacted snapshots for current-session `list_workflows` and `get_workflow` inspection; in-flight execution or acceptance restores as interrupted non-success, and no prior side effect is automatically resumed.
+Legacy v1 and v2 records without acceptance fields retain their prior completed terminal meaning, while v1 self-reported verification flags and artifact trust remain untrusted.
 
 ## 🔁 Stateful agents
 
@@ -918,6 +1049,12 @@ packages/pi-subagents/
 ├── src/
 │   ├── index.ts                  # Pi package entrypoint
 │   ├── subagents.ts              # Extension registration and blocking tool schema
+│   ├── automation.ts             # Explicit autonomous planning tool and lifecycle owner
+│   ├── automation-contract.ts    # Strict request, proposal, and graph-patch contracts
+│   ├── automation-planner.ts     # Bounded read-only planner prompt and resource policy
+│   ├── workflow-plan-compiler.ts # Deterministic admission, routing, and workflow compilation
+│   ├── workflow-plan-patch.ts    # Generation-safe revisions and atomic plan persistence
+│   ├── workflow-planning-benchmark.ts # Frozen matched offline evaluation protocol
 │   ├── inspect.ts                # Side-effect-free metadata inspection tool
 │   ├── consult.ts                # Synchronous read-only consultation tool
 │   ├── consult-policy.ts         # Enforced read-only tool intersection
@@ -937,7 +1074,12 @@ packages/pi-subagents/
 │   ├── execution-plan.ts         # Executor-owned authority and resource resolution
 │   ├── work-item-ledger.ts       # Persistent dependency and artifact state machine
 │   ├── work-item-persistence.ts  # Atomic redacted workflow state and inspection
-│   ├── workflow-verification.ts  # Executor-owned independent-verifier receipts
+│   ├── workflow-verification.ts  # Compatibility independent-verifier receipts
+│   ├── verified-execution-contract.ts # Explicit managed-verification request boundary
+│   ├── workflow-completion-controller.ts # Sole opted-in terminal acceptance owner
+│   ├── verification-harness.ts   # Disposable deterministic check execution
+│   ├── verification-receipt.ts   # Strict executor-owned managed receipts
+│   ├── verified-execution-benchmark.ts # Matched offline acceptance/cost fixture
 │   ├── workflow-tree-identity.ts # Bounded exact Git-visible tree identities
 │   ├── integration-controller.ts # Fail-closed canonical integration admission
 │   ├── adaptive-scheduler.ts     # Dependency, capacity, budget, and conflict scheduling
@@ -972,7 +1114,7 @@ packages/pi-subagents/
 ```
 
 `index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal.
-Workflow settings remain backward compatible: older files without `blocking.enabled` receive the seven-tool default, and an absent `blocking.maxParallelTasks` keeps the previous eight-worker limit.
+Workflow settings remain backward compatible: older files without `blocking.enabled` receive the eight-tool default, and an absent `blocking.maxParallelTasks` keeps the previous eight-worker limit.
 Existing `stateful.enabled: false` files expose blocking delegation plus inspection/consultation.
 Older package releases ignore and preserve the optional `blocking.maxParallelTasks`, `consult`, and `cwdPolicy` fields.
 The package exposes its Pi extension through `package.json`:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.52.0",
+	"version": "0.54.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents/built-ins.ts

@@ -0,0 +1,124 @@
+/**
+ * Built-in agent definitions and prompt construction.
+ */
+
+import { type AgentCapabilityManifest, CAPABILITY_MANIFEST_VERSION } from "../capabilities.js";
+import type { AgentConfig } from "./types.js";
+
+export const BUILT_IN_AGENTS: AgentConfig[] = [
+	{
+		name: "scout",
+		description:
+			"Read-only codebase reconnaissance; returns concise findings with paths and evidence.",
+		tools: ["read", "grep", "find", "ls", "bash"],
+		capabilityManifest: builtInManifest(["repository-search", "code-evidence"], "read", [
+			"evidence-gathering",
+		]),
+		source: "built-in",
+		filePath: "built-in:scout",
+		systemPrompt: [
+			"You are a scout subagent. Explore the codebase quickly and report grounded findings.",
+			"Do not edit files. Prefer read, grep, find, ls, and safe bash inspection commands.",
+			"Return concise bullets with exact file paths, symbols, and open questions.",
+		].join("\n"),
+	},
+	{
+		name: "planner",
+		description: "Turns reconnaissance into a lean implementation or migration plan.",
+		tools: ["read", "grep", "find", "ls"],
+		capabilityManifest: builtInManifest(
+			["task-decomposition", "implementation-planning", "migration-planning"],
+			"read",
+		),
+		source: "built-in",
+		filePath: "built-in:planner",
+		systemPrompt: [
+			"You are a planner subagent. Produce executable, verifiable plans only.",
+			"Do not modify files. Ground the plan in the repository's actual structure.",
+			"Call out assumptions, risks, sequencing, and verification commands.",
+		].join("\n"),
+	},
+	{
+		name: "reviewer",
+		description: "Independent code review agent that inspects existing verification evidence.",
+		tools: ["read", "grep", "find", "ls", "bash"],
+		capabilityManifest: builtInManifest(
+			["code-review", "evidence-review", "security-baseline"],
+			"read",
+			["independent-review"],
+		),
+		source: "built-in",
+		filePath: "built-in:reviewer",
+		systemPrompt: [
+			"You are a reviewer subagent. Review changes adversarially and assess claims against the code and existing evidence.",
+			"Do not edit files or run tests, builds, benchmarks, formatters, or other long-running verification commands.",
+			"Inspect code, diffs, test definitions, and existing verification evidence. Recommend any additional commands for the main agent to run.",
+			"Report PASS, FAIL, or PARTIAL with evidence, commands inspected, and specific follow-ups.",
+		].join("\n"),
+	},
+	{
+		name: "worker",
+		description: "General-purpose implementation worker with the default Pi tool set.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
+		source: "built-in",
+		filePath: "built-in:worker",
+		systemPrompt: workerSystemPrompt(),
+	},
+	{
+		name: "general",
+		description: "Alias for worker; kept for model-generated subagent names.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
+		source: "built-in",
+		filePath: "built-in:general",
+		systemPrompt: workerSystemPrompt(),
+	},
+	{
+		name: "general-purpose",
+		description: "Alias for worker; compatible with common subagent naming conventions.",
+		capabilityManifest: builtInManifest(
+			["implementation", "command-execution", "repository-modification"],
+			"write",
+		),
+		source: "built-in",
+		filePath: "built-in:general-purpose",
+		systemPrompt: workerSystemPrompt(),
+	},
+];
+
+export function getBuiltInAgent(name: string): AgentConfig | undefined {
+	const agent = BUILT_IN_AGENTS.find((candidate) => candidate.name === name);
+	return agent ? structuredClone(agent) : undefined;
+}
+
+function builtInManifest(
+	capabilities: string[],
+	filesystem: "read" | "write",
+	verificationRoles: string[] = [],
+): AgentCapabilityManifest {
+	return {
+		version: CAPABILITY_MANIFEST_VERSION,
+		capabilities,
+		modalities: ["text"],
+		resultFormats: ["text", "structured-v1", "structured-v2"],
+		authority: { filesystem },
+		verificationRoles,
+		contextStrengths: ["repository"],
+		costHint: filesystem === "read" ? "low" : "medium",
+		latencyHint: filesystem === "read" ? "low" : "medium",
+		limitations: [],
+	};
+}
+
+function workerSystemPrompt(): string {
+	return [
+		"You are a focused worker subagent running in an isolated Pi process.",
+		"Complete the delegated task directly. Keep scope tight and avoid unrelated changes.",
+		"When done, summarize files changed, commands run, and any remaining risks.",
+	].join("\n");
+}

package/src/agents/catalog.ts

@@ -0,0 +1,224 @@
+/**
+ * Bounded, sanitized model-facing agent catalog formatting.
+ */
+
+import { BUILT_IN_AGENTS } from "./built-ins.js";
+import {
+	type AgentDiscoveryOptions,
+	type AgentDiscoveryResult,
+	discoverAgents,
+} from "./discovery.js";
+import type { AgentConfig, SubagentSettings } from "./types.js";
+
+export function formatAgentList(
+	agents: AgentConfig[],
+	maxItems: number,
+): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}
+
+export interface AgentCatalog {
+	/** The effective catalog for the default invocation scope. */
+	user: AgentDiscoveryResult;
+	/** The project-scope catalog; custom project definitions are loaded only after project trust. */
+	project?: AgentDiscoveryResult;
+}
+
+export interface AgentCatalogFormatOptions {
+	maxItems?: number;
+	maxDescriptionLength?: number;
+	maxCharacters?: number;
+}
+
+export interface AgentCatalogFormatResult {
+	text: string;
+	omitted: number;
+}
+
+export const DEFAULT_AGENT_CATALOG_MAX_ITEMS = 32;
+export const DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH = 240;
+export const DEFAULT_AGENT_CATALOG_MAX_CHARACTERS = 6_000;
+export const DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE = 128;
+export const DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES = 64 * 1024;
+export const DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE = 2 * 1024 * 1024;
+
+const BUILT_IN_AGENT_ORDER = new Map(BUILT_IN_AGENTS.map((agent, index) => [agent.name, index]));
+
+function compareCatalogAgents(left: AgentConfig, right: AgentConfig): number {
+	const leftBuiltInOrder = BUILT_IN_AGENT_ORDER.get(left.name);
+	const rightBuiltInOrder = BUILT_IN_AGENT_ORDER.get(right.name);
+	if (leftBuiltInOrder !== undefined || rightBuiltInOrder !== undefined) {
+		if (leftBuiltInOrder === undefined) return 1;
+		if (rightBuiltInOrder === undefined) return -1;
+		return leftBuiltInOrder - rightBuiltInOrder;
+	}
+	return left.name.localeCompare(right.name);
+}
+
+function normalizeCatalogDescription(description: string, maxLength: number): string {
+	const normalized = description.replace(/\s+/gu, " ").trim();
+	if (normalized.length <= maxLength) return normalized;
+	const suffix = "…";
+	return `${normalized.slice(0, Math.max(0, maxLength - suffix.length)).trimEnd()}${suffix}`;
+}
+
+type CatalogScope = "user" | "project" | "project-fallback";
+
+function catalogAgentLine(
+	agent: AgentConfig,
+	scope: CatalogScope,
+	userNames: ReadonlySet<string>,
+	maxDescriptionLength: number,
+): string {
+	const scopeLabel =
+		scope === "user"
+			? 'agentScope: "user"'
+			: scope === "project"
+				? 'requires agentScope: "project" or "both"'
+				: 'requires agentScope: "project" ("both" selects the user definition)';
+	const collision =
+		scope !== "user" && userNames.has(agent.name)
+			? scope === "project"
+				? "; overrides the default user definition for project/both"
+				: "; scope-specific fallback for the default user override"
+			: "";
+	return `- ${agent.name} [source: ${agent.source}; ${scopeLabel}${collision}] — ${normalizeCatalogDescription(agent.description, maxDescriptionLength)}`;
+}
+
+/**
+ * Format the effective agent variants that the parent model can invoke.
+ *
+ * User-authored descriptions are prompt text, so this formatter deliberately normalizes and bounds
+ * them. Project definitions are supplied separately by the caller so an untrusted project is never
+ * read merely to build model-facing metadata.
+ */
+export function formatAgentCatalog(
+	catalog: AgentCatalog,
+	options: AgentCatalogFormatOptions = {},
+): AgentCatalogFormatResult {
+	const maxItems = Math.max(0, options.maxItems ?? DEFAULT_AGENT_CATALOG_MAX_ITEMS);
+	const maxDescriptionLength = Math.max(
+		1,
+		options.maxDescriptionLength ?? DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH,
+	);
+	const maxCharacters = Math.max(1, options.maxCharacters ?? DEFAULT_AGENT_CATALOG_MAX_CHARACTERS);
+	const userDiscoveryIncomplete =
+		(catalog.user.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.user.metadataDiscoveryIncomplete === true;
+	const projectDiscoveryIncomplete =
+		(catalog.project?.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+	const discoveredUserAgents = [...catalog.user.agents].sort(compareCatalogAgents);
+	const discoveredProjectScopeAgents = [...(catalog.project?.agents ?? [])].sort(
+		compareCatalogAgents,
+	);
+	const userAgents = userDiscoveryIncomplete ? [] : discoveredUserAgents;
+	const projectScopeAgents = projectDiscoveryIncomplete ? [] : discoveredProjectScopeAgents;
+	const projectAgents = projectScopeAgents.filter((agent) => agent.source === "project");
+	const discoveredUserByName = new Map(discoveredUserAgents.map((agent) => [agent.name, agent]));
+	const userByName = new Map(userAgents.map((agent) => [agent.name, agent]));
+	const userNames = new Set(userByName.keys());
+	const potentialProjectFallbackAgents = discoveredProjectScopeAgents.filter(
+		(agent) =>
+			agent.source === "built-in" && discoveredUserByName.get(agent.name)?.source === "user",
+	);
+	const projectFallbackAgents =
+		userDiscoveryIncomplete || projectDiscoveryIncomplete ? [] : potentialProjectFallbackAgents;
+	const allEntries = [
+		...userAgents.map((agent) => ({ agent, scope: "user" as const })),
+		...projectAgents.map((agent) => ({ agent, scope: "project" as const })),
+		...projectFallbackAgents.map((agent) => ({ agent, scope: "project-fallback" as const })),
+	];
+	const boundedEntries = allEntries.slice(0, maxItems);
+	const suppressedMetadataEntries =
+		(userDiscoveryIncomplete ? discoveredUserAgents.length : 0) +
+		(projectDiscoveryIncomplete
+			? discoveredProjectScopeAgents.filter((agent) => agent.source === "project").length +
+				potentialProjectFallbackAgents.length
+			: 0);
+	const discoveryOmissions =
+		(catalog.user.omittedAgentDefinitions ?? 0) +
+		(catalog.project?.omittedAgentDefinitions ?? 0) +
+		suppressedMetadataEntries;
+	const discoveryIncomplete =
+		catalog.user.metadataDiscoveryIncomplete === true ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+
+	const render = (entries: typeof allEntries, omitted: number): string => {
+		const lines = [
+			"Available agent definitions (metadata only; runtime validation and trust remain authoritative).",
+		];
+		const userLines = entries
+			.filter((entry) => entry.scope === "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (userLines.length > 0) {
+			lines.push('Default scope (agentScope: "user"):');
+			lines.push(...userLines);
+		}
+		const projectLines = entries
+			.filter((entry) => entry.scope !== "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (projectLines.length > 0) {
+			lines.push("Trusted project/scope variants (use the required agentScope shown):");
+			lines.push(...projectLines);
+		}
+		const collisionNames = entries
+			.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+			.map((entry) => entry.agent.name);
+		if (collisionNames.length > 0 && projectLines.length > 0) {
+			const precedence = entries
+				.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+				.map((entry) =>
+					entry.scope === "project"
+						? `${entry.agent.name}: user with "user", project with "project"/"both"`
+						: `${entry.agent.name}: user with "user"/"both", built-in with "project"`,
+				);
+			lines.push(`Same-name precedence: ${precedence.join("; ")}.`);
+		}
+		if (omitted > 0) {
+			lines.push(
+				`[${omitted} additional agent definition${omitted === 1 ? "" : "s"} omitted due to metadata bounds or incomplete discovery.]`,
+			);
+		}
+		if (discoveryIncomplete) {
+			lines.push("[Agent metadata discovery was incomplete; some definitions may be unavailable.]");
+		}
+		return lines.join("\n");
+	};
+
+	let listedCount = boundedEntries.length;
+	let text = render(
+		boundedEntries.slice(0, listedCount),
+		allEntries.length - listedCount + discoveryOmissions,
+	);
+	while (text.length > maxCharacters && listedCount > 0) {
+		listedCount -= 1;
+		text = render(
+			boundedEntries.slice(0, listedCount),
+			allEntries.length - listedCount + discoveryOmissions,
+		);
+	}
+	return { text, omitted: allEntries.length - listedCount + discoveryOmissions };
+}
+
+export function discoverAgentCatalog(
+	cwd: string,
+	projectTrusted: boolean,
+	config?: SubagentSettings,
+): AgentCatalog {
+	const options: AgentDiscoveryOptions = {
+		maxFiles: DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE,
+		maxFileBytes: DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES,
+		maxTotalBytes: DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE,
+	};
+	return {
+		user: discoverAgents(cwd, "user", config, options),
+		project: projectTrusted ? discoverAgents(cwd, "project", config, options) : undefined,
+	};
+}