@selesai/code 0.13.5 → 0.13.7

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

@@ -140,17 +140,46 @@ Async does not mean parallel writes. Do not edit the same active worktree while
 Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed. If no safe independent work remains, return control and let Pi wake the session; do not convert the child to foreground.
 
 In an ordinary interactive chat, normally return control after launching or
-triaging useful async work and let Pi wake the session on completion; do not
-call `subagent_wait()` merely to wait. A run-to-completion user request is not
-by itself a reason to use foreground children. Override the normal yield-and-
-wake flow only when this exact turn cannot safely end without the result, such
-as a headless provider flow or a skill contract that must produce a same-turn
-artifact. Use `subagent_wait()`, not `async:false`, for that current-turn
-dependency. Never substitute sleep or status-polling loops.
-
-`subagent_wait()` returns when the next initially active async run or registered provider item finishes or a subagent needs attention. Use `subagent_wait({ all: true })` for all work active at call time, `subagent_wait({ id: "..." })` for one async or remembered detached foreground run, and `subagent_wait({ timeoutMs })` to cap the block; active work keeps running if it elapses. `subagent_wait({ stopOnAttention: false })` keeps a blocking wait through idle or long-thinking attention, but supervisor/contact requests still stop it. In a long-lived interactive parent session, use `subagent_wait({ id: "...", nonBlocking: true })` to resolve the prefix to one exact run, persist an armed subscription, return immediately, and wake later on completion, failure, attention, reconciliation failure, or timeout. Ordinary status lists armed subscriptions separately from active children. This differs from disabling `waitTool`, which returns immediately without arming a future wake. If a foreground child detaches for supervisor coordination, reply first, then wait on its id; do not resume or launch a replacement while it remains detached. Headless sessions also auto-drain exact current-session work at `agent_end` as a final safeguard.
-
-Providers are discovered through the `pi-subagents/background-work` registry and must expose a stable item id and owning session id. Load a provider through the child’s `extensions` or `subagentOnlyExtensions` and allow `subagent_wait` in its tools. For non-interactive fleets, launch N workers, wait for the next completion, react, and replace as needed; use `all: true` only when intentionally draining the fleet. If `SELESAI_SUBAGENT_WAIT_TOOL_ENABLED` disables blocking, direct waits return immediately, but headless `agent_end` auto-drain still surfaces provider, reconciliation, or timeout failures.
+triaging useful async work and let Pi wake the session on completion; ordinary
+async subagents already have native completion notifications, so do not call
+`bg_wait()` merely to wait. A run-to-completion user request is not by itself a
+reason to use foreground children. Override the normal yield-and-wake flow
+only when this exact turn cannot safely end without the result of provider,
+detached, or other background work without a native notification, such as a
+headless provider flow or a skill contract that must produce a same-turn
+artifact. Use `bg_wait()`, not `async:false`, for that current-turn dependency.
+Never substitute sleep or status-polling loops.
+
+`bg_wait()` returns when the next initially active async run or registered
+provider item finishes or a subagent needs attention. Use it for background,
+provider, or detached work without native completion delivery; ordinary async
+subagent runs notify the parent automatically. Use `bg_wait({ all: true })` for
+all work active at call time, `bg_wait({ id: "..." })` for one async or
+remembered detached foreground run, and `bg_wait({ timeoutMs })` to cap the
+block; active work keeps running if it elapses. `bg_wait({ stopOnAttention:
+false })` keeps a blocking wait through idle or long-thinking attention, but
+supervisor/contact requests still stop it. In a long-lived interactive parent
+session, use `bg_wait({ id: "...", nonBlocking: true })` only for a known
+detached or otherwise non-notifying run to resolve the prefix to one exact run,
+persist an armed subscription, return immediately, and wake later on
+completion, failure, attention, reconciliation failure, or timeout. Ordinary
+status lists armed subscriptions separately from active children. This differs
+from disabling `waitTool`, which returns immediately without arming a future
+wake. If a foreground child detaches for supervisor coordination, reply first,
+then wait on its id; do not resume or launch a replacement while it remains
+detached. Headless sessions also auto-drain exact current-session work at
+`agent_end` as a final safeguard. `subagent_wait` remains available as a
+deprecated compatibility alias for `bg_wait`.
+
+Providers are discovered through the `pi-subagents/background-work` registry and
+must expose a stable item id and owning session id. Load a provider through the
+child’s `extensions` or `subagentOnlyExtensions` and allow `bg_wait` (or the
+deprecated `subagent_wait` compatibility alias) in its tools. For
+non-interactive fleets, launch N workers, wait for the next completion, react,
+and replace as needed; use `all: true` only when intentionally draining the
+fleet. If `SELESAI_SUBAGENT_WAIT_TOOL_ENABLED` disables blocking, direct waits return
+immediately, but headless `agent_end` auto-drain still surfaces provider,
+reconciliation, or timeout failures.
 
 ```typescript
 subagent({
@@ -455,6 +484,8 @@ history as a baseline contract.
 
 Use `oracle` as a smart-friend escalation when the parent needs help with trajectory rather than diff inspection: architectural boundaries, model capability routing, merge conflicts, reviewer disagreement, context drift after long work, a worker about to invent a pattern, or fixes that require product/scope tradeoffs. Ask broad questions when the right concern is unclear, and let `oracle` point out missing context or files the parent should inspect before asking again. Keep `oracle` advisory unless it has been explicitly assigned the single writer role.
 
+Do not use `oracle` or Sol-high models to satisfy routine fresh-review gates, ordinary follow-up reviews, or ordinary performance crit passes. Use the `reviewer` role for those reviews, then escalate only when normal review/bot/CI evidence exposes an unresolved invariant, root-cause, model-routing, or product-tradeoff question.
+
 ## Subagent + Intercom Coordination
 
 `pi-subagents` includes native supervisor coordination. Child agents can use `contact_supervisor` to ask the exact parent session that spawned them; messages are scoped by parent session id and should not appear in other Pi sessions. Parents inspect or reply with `subagent_supervisor`. This path does not require `pi-intercom`.
@@ -505,4 +536,4 @@ subagent_supervisor({ action: "pending" })
 
 Native supervisor coordination does not expose generic `intercom` as a fallback. Use `subagent_supervisor` for parent replies.
 
-If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
+If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.

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

@@ -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`, `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.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/multi-lane-orchestration.md

@@ -34,7 +34,7 @@ While one lane waits, run safe independent preparation, validation, or fresh rea
 
 In an ordinary interactive session, completion wakes the parent; after useful
 async lanes are launched or triaged, yield rather than use
-`subagent_wait({ all: true })` as a barrier. “Continue/orchestrate/work until
+`bg_wait({ all: true })` as a barrier. “Continue/orchestrate/work until
 done” means keep the board moving while safe immediate work remains. If only
 async lanes are running, record the revisit trigger and yield.
 
@@ -48,4 +48,4 @@ Use stable lane-qualified artifact paths for reports and review output. A handof
 
 Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
 
-Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.
+Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md

@@ -9,7 +9,7 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `pi
 ## When to Use
 
 - **Complex work orchestration**: keep the parent on its ordinary strong default model. Delegate only when another child materially improves evidence, independent review, or isolated execution; omission failures are cheaper than unnecessary commissions. For hard orchestration or root-cause questions, use a top-reasoning model only as a bounded read-only critic/oracle escalation, never as an autonomous root. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
-- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
+- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review; fork to `oracle` only for rare escalation where inherited decisions, drift, model routing, root cause, or hard tradeoffs matter
 - **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
 - **Recon and planning**: use `scout`, then write a plan when needed
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
@@ -178,8 +178,8 @@ and user/project agents override builtins with the same name.
 | `reviewer` | Review specialist | strong reviewer tier; high thinking for serious reviews | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
 | `researcher` | Web research brief generator | inherits configured default | Writes `research.md` |
 | `delegate` | Lightweight generic delegate | inherits configured default | No fixed output; generic delegated work |
-| `oracle` | Decision-consistency advisory review | top-reasoning critic tier, bounded read-only; high thinking escalation only | Advisory review, intercom coordination |
-| `advisor` | Compatibility alias for `oracle` | top-reasoning critic tier, bounded read-only; high thinking escalation only | Same advisory role as `oracle` |
+| `oracle` | Rare hard-decision/root-cause escalation | top-reasoning critic tier, bounded read-only; high thinking escalation only | Advisory trajectory review, not routine code review |
+| `advisor` | Compatibility alias for `oracle` | top-reasoning critic tier, bounded read-only; high thinking escalation only | Same advisory escalation role as `oracle` |
 
 Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
 
@@ -279,7 +279,7 @@ agent with the same name only when you want a substantially different agent.
 
 ### Recommended model tiering (optional)
 
-Keep the parent/orchestrator on the ordinary strong default model because omission failures are cheaper than unnecessary commissions. Route workers and scouts to a fast, capable worker tier, and keep serious reviews on the strong tier at high thinking. Use a top-reasoning model only for bounded, read-only critic/oracle/root-cause audits; critic-tier high thinking is escalation-only and never an autonomous root. Explicit parent/user model policy wins over these recommendations.
+Keep the parent/orchestrator on the ordinary strong default model because omission failures are cheaper than unnecessary commissions. Route workers and scouts to a fast, capable worker tier, and keep serious reviews on the strong reviewer tier at high thinking. Do not use `oracle` or a top-reasoning model as the routine fresh-review default. Use that tier only for bounded, read-only critic/oracle/root-cause audits after ordinary review, CI, bot, or source evidence is insufficient; critic-tier high thinking is escalation-only and never an autonomous root. Explicit parent/user model policy wins over these recommendations.
 
 Examples are illustrative, not requirements. Map these tiers to concrete models in user/project settings or a profile. A non-OpenAI setup should choose comparable available models by capability.
 
@@ -292,4 +292,4 @@ override can opt one builtin back in. Existing custom-agent frontmatter remains
 
 Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Explicit custom-agent frontmatter still wins.
 
-Tool description modes live in `~/.selesai/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
+Tool description modes live in `~/.selesai/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/review-and-validation.md

@@ -25,7 +25,7 @@ Skip review ceremony for trivial wording, renames, or local-only probes when dir
 | Possible over-scope or needless complexity | same-writer challenge before fresh review |
 | Material design tradeoff | council mode |
 
-Reviewers are fresh-context by default. Forked reviewers are for parent-history, drift, or prior-decision evidence.
+Reviewers are fresh-context by default. Use the ordinary `reviewer` role for routine code review. Forked oracle/advisor runs are escalation-only for parent-history, drift, root-cause, model-routing, or hard tradeoff evidence.
 
 ## Finding disposition
 
@@ -70,4 +70,4 @@ Before reporting delegated work as done, verify the relevant subset:
 
 ## Public/private boundary
 
-For issue/PR backlogs, releases, merge queues, contributor credit, or repo-specific policy, load the matching user/project skill when available. Keep those rules out of this public package until intentionally released.
+For issue/PR backlogs, releases, merge queues, contributor credit, or repo-specific policy, load the matching user/project skill when available. Keep those rules out of this public package until intentionally released.

package/dist/extensions/pi-subagents/src/agents/agent-management.ts

@@ -7,7 +7,6 @@ import {
 	type AgentDiscoveryDiagnostic,
 	type AgentScope,
 	type AgentSource,
-	BUILTIN_AGENT_NAMES,
 	defaultInheritProjectContext,
 	defaultInheritSkills,
 	defaultSystemPromptMode,
@@ -28,7 +27,7 @@ import {
 	buildProactiveSkillSubagentRecommendationLines,
 } from "./proactive-skills.ts";
 import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.ts";
-import { toModelInfo } from "../shared/model-info.ts";
+import { resolveEffectiveThinking, toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
@@ -37,7 +36,7 @@ import type { AcceptanceInput, AgentCapabilitiesSnapshot, AgentCapabilityRow, De
 import { getProjectConfigDir } from "../shared/utils.ts";
 import { previewDisplayText } from "../shared/display-text.ts";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
-import { listRuntimeAgentConfigs, mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
+import { mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
 import { listExternalJobProviders } from "../api/external-job-provider.ts";
 
 type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
@@ -129,18 +128,39 @@ function allAgents(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: Ag
 	return [...d.builtin, ...d.package, ...d.user, ...d.project];
 }
 
-function availableAgentNamesFromDiscovery(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): string[] {
-	return [...new Set(allAgents(d).map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
+function effectiveAgentsForScope(
+	scope: AgentScope,
+	d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
+	runtimeAgentOwner?: RuntimeAgentOwner,
+): AgentConfig[] {
+	let agents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
+	if (runtimeAgentOwner) {
+		agents = mergeRuntimeAgents(runtimeAgentOwner, { agents }, allAgents(d)).agents;
+	}
+	return agents;
+}
+
+function availableAgentNamesFromDiscovery(
+	d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
+	runtimeAgentOwner?: RuntimeAgentOwner,
+): string[] {
+	const agents = runtimeAgentOwner ? effectiveAgentsForScope("both", d, runtimeAgentOwner) : allAgents(d);
+	return [...new Set(agents.map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
 }
 
 function availableAgentNames(cwd: string): string[] {
 	return availableAgentNamesFromDiscovery(discoverAgentsAll(cwd));
 }
 
-function findAgentsInDiscovery(name: string, d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }, scope: AgentScope = "both"): AgentConfig[] {
+function findAgentsInDiscovery(
+	name: string,
+	d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
+	scope: AgentScope = "both",
+	runtimeAgentOwner?: RuntimeAgentOwner,
+): AgentConfig[] {
 	const raw = name.trim();
 	const sanitized = sanitizeName(raw);
-	const scoped = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
+	const scoped = effectiveAgentsForScope(scope, d, runtimeAgentOwner);
 	let resolved = resolveAgentName(raw, scoped);
 	if (!resolved.agent && !resolved.error && sanitized !== raw) resolved = resolveAgentName(sanitized, scoped);
 	if (resolved.agent) return scoped.filter((agent) => agent.name === resolved.agent!.name).sort((a, b) => a.source.localeCompare(b.source));
@@ -863,16 +883,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
-	let scopedAgents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
-	if (ctx.runtimeAgentOwner && listRuntimeAgentConfigs(ctx.runtimeAgentOwner).length > 0) {
-		const configuredAgents: AgentConfig[] = [
-			...d.builtin,
-			...d.package,
-			...d.user,
-			...d.project,
-		];
-		scopedAgents = mergeRuntimeAgents(ctx.runtimeAgentOwner, { agents: scopedAgents }, configuredAgents).agents;
-	}
+	let scopedAgents = effectiveAgentsForScope(scope, d, ctx.runtimeAgentOwner);
 	scopedAgents = scopedAgents
 		.sort((a, b) => a.name.localeCompare(b.name));
 	const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
@@ -913,80 +924,108 @@ function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undef
 	if (agent.modelSource?.type === "subagents.defaultModel" && agent.model === agent.modelSource.model) {
 		return `${agent.modelSource.scope} defaultModel`;
 	}
-	if (agent.model) return "builtin agent config";
+	if (agent.model) return `${agent.source} agent config`;
 	if (currentModel) return "inherits current session model";
 	return "inherit requested, but no current session model is available";
 }
 
 function handleModels(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const requestedAgent = params.agent?.trim();
-	if (requestedAgent && !(BUILTIN_AGENT_NAMES as readonly string[]).includes(requestedAgent)) {
-		return result(`Builtin agent '${requestedAgent}' not found. Available: ${BUILTIN_AGENT_NAMES.join(", ")}.`, true);
-	}
+	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 builtinByName = new Map(discovered.builtin.map((agent) => [agent.name, agent]));
-	const resolveBuiltinModelAgent = (name: string): AgentConfig | undefined => builtinByName.get(name) ?? resolveAgentName(name, discovered.builtin).agent;
+	const effectiveAgents = effectiveAgentsForScope(scope, discovered, ctx.runtimeAgentOwner)
+		.sort((a, b) => a.name.localeCompare(b.name));
 	const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const currentModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
 	const preferredProvider = ctx.model?.provider;
-	const names = requestedAgent ? [requestedAgent] : [...BUILTIN_AGENT_NAMES];
+	const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
 
+	let selectedAgents = effectiveAgents;
 	if (requestedAgent) {
-		const agent = resolveBuiltinModelAgent(requestedAgent);
-		if (!agent) return result(`Builtin agent '${requestedAgent}' not found.`, true);
-		const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
-		const lines = [
-			"Builtin subagent model",
-			"",
-			`Agent: ${requestedAgent}`,
-			"Effective model:",
-			`  ${resolvedModel ?? "(unresolved)"}`,
-			`Source: ${formatModelSource(agent, currentModel)}`,
-		];
-		if (agent.override) {
-			lines.push("Override file:");
-			lines.push(`  ${agent.override.path}`);
+		const matches = findAgentsInDiscovery(requestedAgent, discovered, scope, ctx.runtimeAgentOwner);
+		const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
+		const normalizedName = sanitizeName(requestedAgent);
+		const diagnostic = findBlockingAgentDiagnostic(requestedAgent, matches, diagnostics)
+			?? (normalizedName !== requestedAgent ? findBlockingAgentDiagnostic(normalizedName, matches, diagnostics) : undefined);
+		if (diagnostic) return result(`Agent '${params.agent}' has invalid configuration: ${diagnostic.error}`, true);
+		const distinctNames = [...new Set(matches.map((agent) => agent.name))];
+		if (distinctNames.length > 1) return result(`Ambiguous agent alias or name '${params.agent}': ${distinctNames.sort((a, b) => a.localeCompare(b)).join(", ")}`, true);
+		if (!matches.length) {
+			return result(`Agent '${params.agent}' not found. Available: ${availableAgentNamesFromDiscovery(discovered, ctx.runtimeAgentOwner).join(", ") || "none"}.`, true);
 		}
-		if (agent.model && resolvedModel && agent.model !== resolvedModel) {
-			lines.push("Requested model setting:");
-			lines.push(`  ${agent.model}`);
-		}
-		if (agent.disabled) lines.push("Disabled: true");
-		lines.push("Current session model:");
-		lines.push(`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
-		return result(lines.join("\n"));
+		selectedAgents = [matches[0]!];
 	}
 
 	const lines = [
-		"Builtin subagent models",
-		"",
-		"Current session model:",
-		`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
+		requestedAgent ? "Subagent model" : "Subagent models",
 		"",
+		...(requestedAgent ? [] : [
+			"Current session model:",
+			`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
+			"",
+		]),
 	];
 
-	for (const name of names) {
-		const agent = resolveBuiltinModelAgent(name);
-		if (!agent) {
-			lines.push(name);
-			lines.push("  model:");
-			lines.push("    (builtin definition not found)");
-			lines.push("  source: missing");
-			lines.push("");
-			continue;
+	const modelEntries = selectedAgents.flatMap((agent) => requestedAgent
+		? [{ agent, name: requestedAgent }]
+		: [{ agent, name: agent.name }, ...(agent.aliases ?? []).map((name) => ({ agent, name }))]);
+	for (const { agent, name } of modelEntries) {
+		const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, agent.modelProvider ?? preferredProvider);
+		const effectiveThinking = resolveEffectiveThinking(resolvedModel, agent.thinking)
+			?? (agent.thinking === false ? "off" : undefined);
+		const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}${isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling) ? "" : "; restricted"}`;
+		if (requestedAgent) {
+			lines.push(`Agent: ${requestedAgent}`);
+			lines.push("Effective model:");
+			lines.push(`  ${resolvedModel ?? "(unresolved)"}`);
+			lines.push(`Source: ${source}`);
+			lines.push(`Thinking: ${effectiveThinking ?? "default"}`);
+			if (agent.fallbackModels?.length) {
+				lines.push("Fallback models:");
+				for (const fallback of agent.fallbackModels) {
+					lines.push(`  ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
+				}
+			}
+			if (agent.override) {
+				lines.push("Override file:");
+				lines.push(`  ${agent.override.path}`);
+			}
+			if (agent.model && resolvedModel && agent.model !== resolvedModel) {
+				lines.push("Requested model setting:");
+				lines.push(`  ${agent.model}`);
+			}
+			if (agent.disabled) lines.push("Disabled: true");
+			if (!isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling)) lines.push("Restricted: true");
+			lines.push("Current session model:");
+			lines.push(`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
+			break;
 		}
-		const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
-		const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}`;
 		lines.push(name);
 		lines.push("  model:");
 		lines.push(`    ${resolvedModel ?? "(unresolved)"}`);
 		lines.push(`  source: ${source}`);
+		lines.push(`  thinking: ${effectiveThinking ?? "default"}`);
+		if (agent.fallbackModels?.length) {
+			lines.push("  fallback models:");
+			for (const fallback of agent.fallbackModels) {
+				lines.push(`    ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
+			}
+		}
+		if (agent.override) {
+			lines.push("  override file:");
+			lines.push(`    ${agent.override.path}`);
+		}
+		if (agent.model && resolvedModel && agent.model !== resolvedModel) {
+			lines.push("  requested model setting:");
+			lines.push(`    ${agent.model}`);
+		}
 		lines.push("");
 	}
 
 	const availableFullIds = availableModels.map((m) => m.fullId).sort();
-	if (availableFullIds.length > 0) {
+	if (!requestedAgent && availableFullIds.length > 0) {
 		lines.push("Available models in this session's registry (copy an exact provider/id when passing model):");
 		lines.push("");
 		const shown = availableFullIds.slice(0, 80);
@@ -995,7 +1034,7 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
 		lines.push("");
 		lines.push("Use an exact provider/id from this list when you pass model; bare ids resolve only when unique in the registry.");
 	}
-
+	if (!requestedAgent) appendAgentDiagnosticLines(lines, diagnosticsForScope(discovered.agentDiagnostics, scope));
 	return result(lines.join("\n"));
 }
 
@@ -1294,4 +1333,4 @@ export function handleManagementAction(action: string, params: ManagementParams,
 		case "reset": return handleReset(params, ctx);
 		default: return result(`Unknown action: ${action}`, true);
 	}
-}
+}

package/dist/extensions/pi-subagents/src/agents/agent-memory.ts

@@ -251,4 +251,4 @@ export function buildAgentMemoryInjection(agent: AgentConfig, cwd: string): stri
 		result.contents,
 		"---",
 	].join("\n");
-}
+}

package/dist/extensions/pi-subagents/src/agents/agent-refinements.ts

@@ -621,4 +621,4 @@ export async function handleRefinementAction(action: RefinementAction, params: {
 		`Evidence items: ${evidence.length}`,
 		`Edits: ${validation.proposal.edits.length}`,
 	].join("\n"));
-}
+}

package/dist/extensions/pi-subagents/src/agents/agent-scope.ts

@@ -3,4 +3,4 @@ import type { AgentScope } from "./agents.ts";
 export function resolveExecutionAgentScope(scope: unknown): AgentScope {
 	if (scope === "user" || scope === "project" || scope === "both") return scope;
 	return "both";
-}
+}

package/dist/extensions/pi-subagents/src/agents/agent-selection.ts

@@ -22,4 +22,4 @@ export function mergeAgentsForScope(
 	}
 
 	return Array.from(agentMap.values());
-}
+}

package/dist/extensions/pi-subagents/src/agents/agent-serializer.ts

@@ -173,4 +173,4 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 
 	const body = config.systemPrompt ?? "";
 	return `${lines.join("\n")}\n\n${body}\n`;
-}
+}