pi-subagents 0.70.1 → 0.72.0

package/prompts/council.md

@@ -8,8 +8,11 @@ session, are the supervisor. You select the roster, curate cross-advisor packets
 decide which feedback is valid, and write the final memo. Advisors do not talk
 directly or see peer transcripts by default. This is not free-form agent chat.
 
-Before you orchestrate, read `skills/council-mode/SKILL.md` and
-`skills/pi-subagents/references/execution-controls.md`.
+Before you orchestrate, load the council protocol with
+`subagent({ action: "guide", topic: "council" })`. If only `subagents_enable`
+is available, call it first; `subagent` is available on the next request. The
+guide returns the packaged council-mode skill and the references it asks you to
+read, so it also works when Pi runs with `--no-skills`.
 
 Parse the invocation yourself. The flags below are conventions, not runtime
 options. Record a brief with the question, scope, non-goals, evidence targets,
@@ -48,7 +51,7 @@ path if the run is not resumable.
 ## Run the protocol
 
 Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
-and memo requirements in `skills/council-mode/SKILL.md`. Keep the parent as the
+and memo requirements from the council guide. Keep the parent as the
 only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
 or transcript sharing.
 

package/skills/pi-subagents/references/constraints-and-recipes.md

@@ -6,10 +6,13 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
 
 - **Explicit forking requires a persisted parent session.** If the current session
   does not have a persisted session file or current leaf, explicit `context: "fork"`
-  fails. An agent-level `defaultContext: fork` is a preference: packaged `worker`,
-  `oracle`, and `advisor` fall back to `fresh` when those fork preconditions are not
+  fails. An agent-level `defaultContext: fork` is a preference: packaged `oracle`
+  and `advisor` fall back to `fresh` when those fork preconditions are not
   met yet. Use `context: "fresh"` when you do not want a fork even after the parent
   session exists.
+- **Packaged workers start fresh.** `worker` defaults to fresh context so its brief,
+  not the parent's unfinished agenda, controls the implementation. Pass explicit
+  `context: "fork"` when inherited conversation history is required.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
   filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked

package/skills/pi-subagents/references/execution-controls.md

@@ -32,7 +32,7 @@ An agent may set `runner.type: external-job` with a non-empty `provider` and opt
 
 External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
 
-External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
+External job profiles do not support foreground/clarify, live steer or native session resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Completed external-job runs can use `action: "resume"` for provider follow-up when the registered provider exposes `followUp(input)`; running jobs must finish first, and providers without follow-up support fail closed with an update/reload message. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
 
 ### Single agent
 
@@ -103,7 +103,7 @@ For a typed post-run check, pass the object form `gate: { command, output: "json
 
 If omitted, acceptance is inferred from role, mode, and risk. Use `level: "checked"` for ordinary writer evidence and `level: "verified"` when the runtime should run explicit validation commands. Independent review is orthogonal: use `review: { required: true, agent: "reviewer" }`; reviewer/read-only calls omit `acceptance`. `review-required` means evidence passed but review is pending; `reviewed` means an independent review found no blockers. Never request `level: "reviewed"`; it is recognized only so preflight can return an actionable correction. Disable gates with `{ level: "none", reason: "..." }`; bare `"none"` is rejected and `false` is only a deprecated shorthand. Child-reported command success is evidence, not runtime verification.
 
-Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. Resume only rows reported `resumable`. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. If no retained child is resumable, launch a same-role fallback challenge and label it as fallback. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. Pass explicit follow-up task text. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
+Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. This workflow-only roster is not an exhaustive list of direct native children. Resume only rows reported `resumable`. When the exact run id of an intended direct child is known, inspect it with `subagent({ action: "status", id: "<run-id>" })`; if status identifies the candidate, attempt `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Resume performs the authoritative eligibility check and may reject the attempt. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. Launch a same-role fallback challenge, labeled as fallback, only when no known candidate exists or resume rejects eligibility. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. Pass explicit follow-up task text. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
 
 Each workflow key identifies one result lane: use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.
 
@@ -493,7 +493,7 @@ subagent({
   workflowScript: `return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction, challenge assumptions, and propose the best next move." })`
 })
 
-// Implementation only after explicit approval. Worker defaults to forked context.
+// Implementation only after explicit approval. Worker defaults to fresh context.
 subagent({
   workflowScript: `return runs.run("implementation", { agent: "worker", task: "Implement the approved approach: ..." })`
 })

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -18,7 +18,7 @@ subagent({ action: "list" })
 subagent({ action: "children.list" })
 ```
 
-Lists up to the last 10 retained workflow children from this parent session with explicit `resumable` or `not resumable` rows. Resume only rows reported `resumable`. Send a simple follow-up or implementation challenge with `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Continue one inside a workflow with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`; each workflow key identifies one result lane, so use a new stable workflow key for every distinct retained resume pass. Same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected. The revived child keeps its stored agent, model, and tool contract. If no resumable child is listed, start a same-role fallback challenge and label it as fallback. `steer` with `mode: "follow_up"` only queues text for the next `resume` when the child has already completed.
+Lists up to the last 10 retained workflow children from this parent session with explicit `resumable` or `not resumable` rows. This workflow-only roster is not an exhaustive list of direct native children. Resume only rows reported `resumable`. When the exact run id of an intended direct child is known, inspect it with `subagent({ action: "status", id: "<run-id>" })`; if status identifies the candidate, attempt `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Resume performs the authoritative eligibility check and may reject the attempt. Continue one inside a workflow with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`; each workflow key identifies one result lane, so use a new stable workflow key for every distinct retained resume pass. Same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected. The revived child keeps its stored agent, model, and tool contract. Start a same-role fallback challenge, labeled as fallback, only when no known candidate exists or resume rejects eligibility. `steer` with `mode: "follow_up"` only queues text for the next `resume` when the child has already completed.
 
 ### Refinement overlays
 
@@ -158,4 +158,4 @@ Additional user prompt templates can delegate into `pi-subagents` through the na
 
 Other Pi extensions can call `pi-subagents` through the in-process event bus. The RPC channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
 
-Methods: `ping`, `status`, `spawn`, `steer`, `interrupt`, `resume`, and `stop`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` requires `workflowScript`, is async-only, and rejects management actions, `async: false`, or `clarify: true`; it reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. For retained-child workflows, list children first and resume only rows reported `resumable`; otherwise start a same-role fallback challenge and label it as fallback. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.
+Methods: `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `resume`, `stop`, and `cost`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`; `capabilities.cost: { version: 1 }` advertises parent-plus-child accounting as data. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` accepts either `{ agent, task? }`, an inline `workflowScript`, or `workflowScriptPath`; it is async-only and rejects management actions, `async: false`, or `clarify: true`. It reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `manage` accepts only the schedule actions advertised by `ping.capabilities.managementActions`. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. For retained-child workflows, resume only roster rows reported `resumable`; because that workflow-only roster is not exhaustive, inspect the exact status of a known direct-run candidate and attempt the authoritative resume when status identifies it. Start a labeled same-role fallback only when there is no known candidate or resume rejects eligibility. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.

package/src/agents/agent-management.d.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type AgentConfig } from "./agents.ts";
+import { type AgentConfig, discoverAgentsAll } from "./agents.ts";
 import type { Details, ExtensionConfig } from "../shared/types.ts";
 import { type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
 type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & {
@@ -9,6 +9,7 @@ type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & {
     currentSessionId?: string;
     runtimeAgentOwner?: RuntimeAgentOwner;
     onAgentsChanged?: () => void;
+    discoverAgentsAll?: typeof discoverAgentsAll;
 };
 interface ManagementParams {
     action?: string;

package/src/agents/agent-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-management.d.ts","sourceRoot":"","sources":["../../../src/agents/agent-management.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EACN,KAAK,WAAW,EAiBhB,MAAM,aAAa,CAAC;AAcrB,OAAO,KAAK,EAAkE,OAAO,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AAIrJ,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAKzF,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,eAAe,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAE3O,UAAU,gBAAgB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAoMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA8EnE;AAWD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAsD7G;AA8jBD,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAuCrG;AAmID,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAiDvG;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CA+DvG;AAoJD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAcjI"}
+{"version":3,"file":"agent-management.d.ts","sourceRoot":"","sources":["../../../src/agents/agent-management.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EACN,KAAK,WAAW,EAQhB,iBAAiB,EASjB,MAAM,aAAa,CAAC;AAcrB,OAAO,KAAK,EAAkE,OAAO,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AAIrJ,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAKzF,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,KAAK,GAAG,eAAe,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,iBAAiB,CAAA;CAAE,CAAC;AAMzR,UAAU,gBAAgB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAoMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA8EnE;AAWD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAsD7G;AA+jBD,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAuCrG;AAmID,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAiDvG;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CA+DvG;AAoJD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAAC,OAAO,CAAC,CAcjI"}

package/src/agents/agent-management.js

@@ -17,6 +17,9 @@ import { previewDisplayText } from "../shared/display-text.js";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.js";
 import { mergeRuntimeAgents } from "./runtime-agent-registry.js";
 import { listExternalJobProviders } from "../api/external-job-provider.js";
+function discoverCatalog(ctx, cwd = ctx.cwd, provider) {
+    return (ctx.discoverAgentsAll ?? discoverAgentsAll)(cwd, provider);
+}
 function result(text, isError = false, details) {
     return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...details } };
 }
@@ -97,8 +100,8 @@ function availableAgentNamesFromDiscovery(d, runtimeAgentOwner, preferredModelPr
     const agents = runtimeAgentOwner ? effectiveAgentsForScope("both", d, runtimeAgentOwner, preferredModelProvider) : allAgents(d);
     return [...new Set(agents.map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
 }
-function availableAgentNames(cwd) {
-    return availableAgentNamesFromDiscovery(discoverAgentsAll(cwd));
+function availableAgentNames(ctx, cwd = ctx.cwd) {
+    return availableAgentNamesFromDiscovery(discoverCatalog(ctx, cwd));
 }
 function findAgentsInDiscovery(name, d, scope = "both", runtimeAgentOwner, preferredModelProvider) {
     const raw = name.trim();
@@ -114,8 +117,8 @@ function findAgentsInDiscovery(name, d, scope = "both", runtimeAgentOwner, prefe
         || (sanitized !== raw && Boolean(resolveAgentName(sanitized, [agent]).agent)))
         .sort((a, b) => a.source.localeCompare(b.source));
 }
-function findAgents(name, cwd, scope = "both") {
-    return findAgentsInDiscovery(name, discoverAgentsAll(cwd), scope);
+function findAgents(name, ctx, scope = "both") {
+    return findAgentsInDiscovery(name, discoverCatalog(ctx), scope);
 }
 function diagnosticsForScope(diagnostics, scope) {
     if (scope === "both")
@@ -142,8 +145,8 @@ function resolveEffectiveAgent(d, name) {
     const matches = candidates.filter((agent) => agent.name === resolved.agent.name);
     return { agent: matches.reduce((best, agent) => (AGENT_SOURCE_PRECEDENCE[agent.source] > AGENT_SOURCE_PRECEDENCE[best.source] ? agent : best)) };
 }
-function nameExistsInScope(cwd, scope, name, excludePath) {
-    const d = discoverAgentsAll(cwd);
+function nameExistsInScope(ctx, scope, name, excludePath) {
+    const d = discoverCatalog(ctx);
     for (const a of scope === "user" ? d.user : d.project) {
         if (a.name === name && a.filePath !== excludePath)
             return true;
@@ -664,7 +667,7 @@ function applyAgentConfig(target, cfg) {
     }
     return undefined;
 }
-function resolveTarget(name, matches, cwd, scopeHint) {
+function resolveTarget(name, matches, cwd, ctx, scopeHint) {
     const distinctNames = [...new Set(matches.map((match) => match.name))];
     if (distinctNames.length > 1)
         return result(`Ambiguous agent alias or name '${name}': ${distinctNames.sort((a, b) => a.localeCompare(b)).join(", ")}`, true);
@@ -672,7 +675,7 @@ function resolveTarget(name, matches, cwd, scopeHint) {
     if (mutable.length === 0) {
         if (matches.length > 0)
             return result(`Agent '${name}' is read-only and cannot be modified. Create a same-named agent in user or project scope to override it.`, true);
-        return result(`Agent '${name}' not found. Available: ${availableAgentNames(cwd).join(", ") || "none"}.`, true);
+        return result(`Agent '${name}' not found. Available: ${availableAgentNames(ctx, cwd).join(", ") || "none"}.`, true);
     }
     if (mutable.length === 1)
         return mutable[0];
@@ -688,8 +691,8 @@ function resolveTarget(name, matches, cwd, scopeHint) {
         return result(`Multiple agents named '${name}' found in scope '${scope}': ${scoped.map((match) => match.filePath).join(", ")}`, true);
     return scoped[0];
 }
-function renamePath(currentPath, newName, scope, cwd) {
-    if (nameExistsInScope(cwd, scope, newName, currentPath))
+function renamePath(currentPath, newName, scope, ctx) {
+    if (nameExistsInScope(ctx, scope, newName, currentPath))
         return { error: `Name '${newName}' already exists in ${scope} scope.` };
     const filePath = path.join(path.dirname(currentPath), `${newName}.md`);
     if (fs.existsSync(filePath) && filePath !== currentPath)
@@ -1017,7 +1020,7 @@ function formatAgentDetail(agent) {
 }
 export function handleList(params, ctx) {
     const scope = normalizeListScope(params.agentScope) ?? "both";
-    const d = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
+    const d = discoverCatalog(ctx, ctx.cwd, ctx.model?.provider);
     let scopedAgents = effectiveAgentsForScope(scope, d, ctx.runtimeAgentOwner, ctx.model?.provider);
     scopedAgents = scopedAgents
         .sort((a, b) => a.name.localeCompare(b.name));
@@ -1074,7 +1077,7 @@ function handleModels(params, ctx) {
     const scope = normalizeListScope(params.agentScope);
     if (!scope)
         return result("agentScope must be 'user', 'project', or 'both' for models.", true);
-    const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
+    const discovered = discoverCatalog(ctx, ctx.cwd, ctx.model?.provider);
     const effectiveAgents = effectiveAgentsForScope(scope, discovered, ctx.runtimeAgentOwner, ctx.model?.provider)
         .sort((a, b) => a.name.localeCompare(b.name));
     const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
@@ -1174,7 +1177,7 @@ function handleGet(params, ctx) {
     const scope = normalizeListScope(params.agentScope);
     if (!scope)
         return result("agentScope must be 'user', 'project', or 'both' for get.", true);
-    const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
+    const discovered = discoverCatalog(ctx, ctx.cwd, ctx.model?.provider);
     const matches = findAgentsInDiscovery(params.agent, discovered, scope);
     const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
     const rawName = params.agent.trim();
@@ -1215,11 +1218,11 @@ export function handleCreate(params, ctx) {
     const scope = scopeRaw;
     if (hasKey(cfg, "steps"))
         return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
-    const d = discoverAgentsAll(ctx.cwd);
+    const d = discoverCatalog(ctx);
     const projectConfigDir = getProjectConfigDir(ctx.cwd);
     const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(projectConfigDir, "agents");
     fs.mkdirSync(targetDir, { recursive: true });
-    if (nameExistsInScope(ctx.cwd, scope, runtimeName))
+    if (nameExistsInScope(ctx, scope, runtimeName))
         return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
     const targetPath = path.join(targetDir, `${runtimeName}.md`);
     if (fs.existsSync(targetPath))
@@ -1269,7 +1272,7 @@ export function handleUpdate(params, ctx) {
         return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
     const warnings = [];
     const scopeHint = asDisambiguationScope(params.agentScope);
-    const targetOrError = resolveTarget(params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
+    const targetOrError = resolveTarget(params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx.cwd, ctx, scopeHint);
     if ("content" in targetOrError)
         return targetOrError;
     const target = targetOrError;
@@ -1327,7 +1330,7 @@ export function handleUpdate(params, ctx) {
             warnings.push(sw);
     }
     if (updated.name !== oldName) {
-        const renamed = renamePath(target.filePath, updated.name, target.source, ctx.cwd);
+        const renamed = renamePath(target.filePath, updated.name, target.source, ctx);
         if (renamed.error)
             return result(renamed.error, true);
         updated.filePath = renamed.filePath;
@@ -1343,7 +1346,7 @@ function handleDelete(params, ctx) {
     if (!params.agent)
         return result("Specify 'agent' for delete.", true);
     const scopeHint = asDisambiguationScope(params.agentScope);
-    const targetOrError = resolveTarget(params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
+    const targetOrError = resolveTarget(params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx.cwd, ctx, scopeHint);
     if ("content" in targetOrError)
         return targetOrError;
     const target = targetOrError;
@@ -1360,17 +1363,17 @@ function handleEject(params, ctx) {
     if (parsedScope.error)
         return parsedScope.error;
     const scope = parsedScope.scope;
-    const d = discoverAgentsAll(ctx.cwd);
+    const d = discoverCatalog(ctx);
     const source = [...d.package, ...d.builtin].find((a) => a.name === raw || a.name === sanitized);
     if (!source) {
-        return result(`Agent '${raw}' not found or is not a bundled/package agent. eject copies a builtin or package agent to ${scope} scope so it can be customized. Available: ${availableAgentNames(ctx.cwd).join(", ") || "none"}.`, true);
+        return result(`Agent '${raw}' not found or is not a bundled/package agent. eject copies a builtin or package agent to ${scope} scope so it can be customized. Available: ${availableAgentNames(ctx).join(", ") || "none"}.`, true);
     }
     const runtimeName = source.name;
     const existingCustom = (scope === "user" ? d.user : d.project).find((a) => a.name === runtimeName);
     if (existingCustom) {
         return result(`Agent '${runtimeName}' is already a custom ${scope} agent at ${existingCustom.filePath}. Edit it with { action: "update", agent: "${runtimeName}" } or delete it first.`, true);
     }
-    if (nameExistsInScope(ctx.cwd, scope, runtimeName)) {
+    if (nameExistsInScope(ctx, scope, runtimeName)) {
         return result(`An agent named '${runtimeName}' already exists in ${scope} scope. Remove or rename it first.`, true);
     }
     const projectConfigDir = getProjectConfigDir(ctx.cwd);
@@ -1400,7 +1403,7 @@ function handleDisable(params, ctx) {
     if (parsedScope.error)
         return parsedScope.error;
     const scope = parsedScope.scope;
-    const d = discoverAgentsAll(ctx.cwd);
+    const d = discoverCatalog(ctx);
     if (scope === "project" && d.projectSettingsPath === null) {
         return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
     }
@@ -1408,11 +1411,11 @@ function handleDisable(params, ctx) {
     if (effective.error)
         return result(effective.error, true);
     if (!effective.agent) {
-        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx.cwd).join(", ") || "none"}.`, true);
+        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx).join(", ") || "none"}.`, true);
     }
     const runtimeName = effective.agent.name;
     const settingsPath = mergeBuiltinAgentOverride(ctx.cwd, runtimeName, scope, { disabled: true });
-    const after = resolveEffectiveAgent(discoverAgentsAll(ctx.cwd), raw).agent;
+    const after = resolveEffectiveAgent(discoverCatalog(ctx), raw).agent;
     if (after?.disabled === true) {
         ctx.onAgentsChanged?.();
         return result(`Disabled agent '${runtimeName}' via ${scope} settings override at ${settingsPath}. It is now hidden from runtime discovery and { action: "list" }.`);
@@ -1427,7 +1430,7 @@ function handleEnable(params, ctx) {
     if (parsedScope.error)
         return parsedScope.error;
     const scope = parsedScope.scope;
-    const d = discoverAgentsAll(ctx.cwd);
+    const d = discoverCatalog(ctx);
     if (scope === "project" && d.projectSettingsPath === null) {
         return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
     }
@@ -1435,11 +1438,11 @@ function handleEnable(params, ctx) {
     if (effective.error)
         return result(effective.error, true);
     if (!effective.agent) {
-        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx.cwd).join(", ") || "none"}.`, true);
+        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx).join(", ") || "none"}.`, true);
     }
     const runtimeName = effective.agent.name;
     const { path: settingsPath, removed } = removeBuiltinAgentOverrideFields(ctx.cwd, runtimeName, scope, ["disabled"]);
-    const after = resolveEffectiveAgent(discoverAgentsAll(ctx.cwd), raw).agent;
+    const after = resolveEffectiveAgent(discoverCatalog(ctx), raw).agent;
     if (after && after.disabled !== true) {
         if (removed)
             ctx.onAgentsChanged?.();
@@ -1461,7 +1464,7 @@ function handleReset(params, ctx) {
     if (parsedScope.error)
         return parsedScope.error;
     const scope = parsedScope.scope;
-    const d = discoverAgentsAll(ctx.cwd);
+    const d = discoverCatalog(ctx);
     if (scope === "project" && d.projectSettingsPath === null) {
         return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
     }
@@ -1471,7 +1474,7 @@ function handleReset(params, ctx) {
         if (custom) {
             return result(`Agent '${raw}' has no bundled default to reset to. Use { action: "delete", agent: "${custom.name}" } to remove the custom ${custom.source} agent.`, true);
         }
-        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx.cwd).join(", ") || "none"}.`, true);
+        return result(`Agent '${raw}' not found. Available: ${availableAgentNames(ctx).join(", ") || "none"}.`, true);
     }
     const runtimeName = bundled.name;
     const custom = (scope === "user" ? d.user : d.project).find((a) => a.name === raw || a.name === sanitized);