@narumitw/pi-subagents 0.53.0 → 1.0.0

package/README.md

@@ -299,8 +299,8 @@ No benchmark result in this release changes the default delegation policy or mak
 | --- | --- | --- |
 | `list_agents` | Optional `agentScope` (default `user`) and `limit` (default 32, maximum 100) | Bounded agent metadata and omission counts |
 | `get_agent` | Required `agent`; optional `agentScope` | One resolved definition, safe source path, configured tools, and consultation-effective tools; never the system prompt |
-| `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries and unread counts |
-| `get_run` | Required `agentId` | Safe `cwd`, current-task/error summaries, thinking level, context footprint, protocol, effective transport, bounded timing/usage telemetry, structured result when valid, policy, history count, and unread count |
+| `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries, turn generation, pending-completion count, and unread counts |
+| `get_run` | Required `agentId` | Safe `cwd`, current run and turn generation, current-task/error summaries, thinking level, context footprint, protocol, effective transport, bounded timing/usage telemetry, structured result when valid, policy, history count, pending-completion count, and unread count |
 | `list_workflows` | Optional `limit` (default 50, maximum 100) | Metadata-only persisted blocking-workflow summaries for the current session |
 | `get_workflow` | Required `workflowId` | Bounded task states, generations, dependencies, plan identities, artifact metadata, verification state, and outcome reasons without artifact contents |
 | `list_models` | Optional `limit` (default 50, maximum 100) | Session-scoped models, or the already-loaded available snapshot |
@@ -310,7 +310,7 @@ No benchmark result in this release changes the default delegation policy or mak
 
 The schema rejects fields that do not belong to the selected action. Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project. Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages. Workflow inspection reads validated, redacted snapshots without quarantining or rewriting invalid files. Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
 
-Compatibility: `subagent_manage({ "action": "list" })` remains supported with its existing behavior. Prefer `subagent_inspect` when a whole tool must be safe to activate on a read-only surface.
+`subagent_manage` no longer accepts its former compatibility `list` action. Use `subagent_inspect({ "action": "list_runs", "includeClosed": true })` for metadata-only discovery and `get_run` for detail.
 
 ## 📖 Read-only consultation
 
@@ -480,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
 {
@@ -528,16 +576,32 @@ 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
 
-Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Completions that settle in the same dispatch window are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
+Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Every turn receives an executor-owned `runId`, monotonically increasing agent-local generation, and unique `completionId`. The terminal completion is persisted before delivery, simultaneous completions are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
 
-Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result. If it does, use blocking `subagent` when registered; in **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis turn is appropriate, or switch workflows. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_manage` with `action: "list"` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
+Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result. If it does, use blocking `subagent` when registered; in **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis turn is appropriate, or switch workflows. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_inspect` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
 
 A detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
 
@@ -546,7 +610,7 @@ A detached agent additionally needs a concrete isolation or specialization benef
 - `"next-turn"` (default) preserves the previous behavior: use `deliverAs: "steer"` with `triggerTurn: false`. An active root can consume completion naturally; an idle root is not awakened.
 - `"auto-resume"` holds completion while the root is active, then requests one synthesis turn after the parent settles when no user or extension messages are already pending. Simultaneous completions share that turn, active work is not interrupted, and pending input suppresses the autonomous wake.
 
-Auto-resume is best-effort because Pi's custom-message API is fire-and-forget. Session-generation checks, shutdown cleanup, batching, and the in-flight wake guard prevent stale or duplicate scheduling pressure, but they do not make completion delivery durable across process exit.
+The bounded persisted completion outbox provides ordered at-least-once delivery across process restart without replaying the child turn. When state must be reduced to its storage bound, persistence drops roots without pending completions first and trims old history rather than discarding an outbox-owned root. A completion is acknowledged only after parent context assembly observes its exact `completionId`; an injection that returns synchronously but never reaches context remains pending for retry. If the process exits after context assembly but before acknowledgement is persisted, the same ID can be delivered again and consumers must deduplicate it. Auto-resume wake admission remains best-effort because Pi's custom-message API is fire-and-forget, but an unacknowledged terminal completion itself remains available for redelivery on the next start of the owning session. Transient terminal-persistence failures retry with bounded exponential backoff and keep the run pending; shutdown cancels retry waits and reports a final persistence failure instead of silently resolving unsaved work.
 
 The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history.
 Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
@@ -623,7 +687,7 @@ This avoids lifecycle-driven tool-schema churn and preserves a stable provider p
 | --- | --- |
 | `subagent_spawn` | Start detached work with optional task-selected thinking and retained timeout, exact-retry `idempotencyKey`, and `text`, `structured-v1`, or `structured-v2` result format; return an opaque `agentId` immediately and deliver completion asynchronously. |
 | `subagent_send` | Send follow-up work with an optional one-turn timeout override and trigger a new turn on a reusable agent; semantic skew requires explicit `revalidate: true`, and shared-workspace write conflicts are guarded unless explicitly overridden. |
-| `subagent_manage` | Use `action: "list"` to inspect agents, `"interrupt"` to retain an agent after aborting active work, or `"close"` to release it; interrupt/close accept optional `subtree`. |
+| `subagent_manage` | Use `"interrupt"` to retain an agent after aborting active work or `"close"` to release it; both actions accept optional `subtree`. Use `subagent_inspect` for all list and detail operations. |
 | `subagent_mailbox` | Use `action: "send"` for queue-only messages that do not start a turn, or `"read"` to read and optionally acknowledge unread messages. |
 
 The action schemas are flat for provider compatibility and reject parameters that belong to another action. For example:
@@ -657,13 +721,14 @@ The five replaced names are intentionally not registered as aliases. Update expl
 
 | Previous call | Fixed-surface call |
 | --- | --- |
-| `subagent_list({ includeClosed })` | `subagent_manage({ action: "list", includeClosed })` |
+| `subagent_list({ includeClosed })` | `subagent_inspect({ action: "list_runs", includeClosed })` |
+| `subagent_manage({ action: "list", includeClosed })` | `subagent_inspect({ action: "list_runs", includeClosed })` |
 | `subagent_interrupt({ agentId, subtree })` | `subagent_manage({ action: "interrupt", agentId, subtree })` |
 | `subagent_close({ agentId, subtree })` | `subagent_manage({ action: "close", agentId, subtree })` |
 | `subagent_message({ agentId, message, ... })` | `subagent_mailbox({ action: "send", agentId, message, ... })` |
 | `subagent_messages({ agentId, acknowledge, limit })` | `subagent_mailbox({ action: "read", agentId, acknowledge, limit })` |
 
-Persisted agent and mailbox records require no migration. If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation. To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`. The previous release can read the same state directory.
+Persisted agent and mailbox records require no manual migration; older records load with an empty completion outbox and generation zero. If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation. To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`. The previous release can read the same state directory.
 
 A spawn can request a thinking level explicitly:
 
@@ -1010,7 +1075,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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.53.0",
+	"version": "1.0.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,
+	};
+}