pi-ui-extend 1.0.41 → 1.0.42

package/external/pi-tools-suite/docs/subagent-model-pools.md

@@ -6,12 +6,15 @@ integration, decisions and the final answer. Actual savings depend on worker
 quality, retries and how much work the parent repeats; the configuration is
 not a price oracle.
 
-## Five execution modes
+## Six execution modes
 
-- `research`: read-only evidence gathering, searches and independent diff review.
+- `research`: read-only evidence gathering, searches and focused review questions.
 - `implement`: bounded code, documentation, test and frontend changes.
 - `verify`: run checks and interpret logs, without fixing source or tests.
 - `browser-qa`: isolated browser workflow with assertions and visual artifacts.
+- `frontier-review`: independent post-implementation code review on a strong
+  model; hidden when the current parent model matches the role's availability
+  gate.
 - `oracle`: a deliberate strong second opinion, not automatic worker escalation.
 
 Task-specific discipline belongs in the brief or `promptAppend`. A new project
@@ -35,29 +38,27 @@ thinking: medium
 ---
 ```
 
-A preset contains a set of available models, not a per-agent matrix:
+A preset contains a set of available models, not a per-agent matrix. Project
+pools live in `.pi/agents/presets.jsonc`:
 
 ```jsonc
 {
-  "asyncSubagents": {
-    "presets": {
-      "gpt": {
-        "description": "Models available for this session",
-        "models": [
-          "openai-codex/gpt-5.6-luna",
-          "openai-codex/gpt-5.6-terra",
-          "openai-codex/gpt-5.6-sol"
-        ]
-      }
-    }
+  "gpt": {
+    "description": "Models available for this project",
+    "models": [
+      "openai-codex/gpt-5.6-luna",
+      "openai-codex/gpt-5.6-terra",
+      "openai-codex/gpt-5.6-sol"
+    ]
   }
 }
 ```
 
 The example agent selects Terra, not Luna: the agent's order wins. Sol is
 available in the pool but absent from this worker's chain, so it cannot become
-an automatic implementation fallback. The oracle can declare Sol in its own
-chain. Model references must be exact `provider/model` values, not wildcards.
+an automatic implementation fallback. The oracle and frontier-review can
+declare Sol in their own chains. Model references in `models` must be exact
+`provider/model` values, not wildcards.
 
 The resolver intersects the agent chain with the selected pool. Runtime
 selection then skips unregistered, unauthenticated or session-exhausted models.
@@ -83,22 +84,31 @@ Use `/subagent-preset <name>`, `AGENTS_PRESET=<name>` or
 without a pool filter. The shipped names remain compatible with saved choices:
 `cheap` is the GLM pool, `gpt` the GPT pool, and `deep` the mixed pool. The last
 name no longer means that ordinary workers should escalate to flagship models.
+Bundled definitions live beside the built-in agents in
+`src/async-subagents/agents/presets.jsonc`; a project file with the same preset
+name overrides that pool.
 
 Old role names are not implicit aliases. `quick`, `scan`, `review`, `deep`,
 `docs`, `frontend`, and `tests` work only when explicitly defined as ordinary
 custom/project types. This keeps the effective catalog and accepted names exact.
 
-Legacy `model` plus `fallbackModels` and `modelByParent` still load. New profile
-`models` replaces inherited legacy selection fields; an explicit legacy model
-override can still replace an inherited new list. Empty `models` means no
-candidates, not permission to inherit the parent model. Model-less project
-specialists must declare candidates or receive an explicit model override.
+Agent frontmatter can gate whether a role exists for the current parent model:
+`forParentModels` is an optional allow-list and `notForParentModels` is an
+optional deny-list; deny wins when both match. These fields accept model
+patterns such as `zai/*` and affect the parent catalog, explicit role
+validation, and automatic routing. They do not change which model the child
+runs on; `models` / legacy model selectors still own child model selection.
 
-Legacy preset role matrices remain readable. A preset with `models` uses only
-the pool contract, dropping stale legacy model/thinking/type overrides. Switching
-a higher-priority config layer back to a legacy preset removes the inherited
-pool. Configuration loading never rewrites user files; review old overrides
-when migrating, since explicitly saved profiles can retain expensive models.
+Legacy `model` plus `fallbackModels` and `modelByParent` still load when they are
+declared in an agent Markdown file. New profile `models` replaces inherited
+legacy selection fields. Empty `models` means no candidates, not permission to
+inherit the parent model. Model-less project specialists must declare candidates
+or receive an explicit model override.
+
+The removed `asyncSubagents` section is no longer part of the public config
+schema and is not read at runtime. Existing legacy files are left untouched but
+have no effect. Migrate role definitions to `.pi/agents/*.md` and custom pools to
+`.pi/agents/presets.jsonc`.
 
 ## Compact handoff
 
@@ -106,4 +116,5 @@ Give workers a scope, acceptance criteria and the evidence needed to start.
 Read compact results first and inspect raw artifacts selectively. One noisy
 sequential investigation can justify a worker; a command whose exit status is
 sufficient usually only needs a saved log, not another LLM. Independent review
-uses a fresh `research` invocation, not a separate built-in persona.
+of substantive code changes uses `frontier-review` when it is present in the
+current parent catalog; use `research` for focused evidence/review questions.

package/external/pi-tools-suite/src/async-subagents/agents/frontier-review.md

@@ -0,0 +1,23 @@
+---
+description: Independent frontier-model code review gate for substantive code changes made by a non-frontier parent. Use after implementation and targeted checks, before finalizing. Read-only review of the actual diff and surrounding code; use research for ordinary evidence gathering and oracle for architecture or high-stakes second opinions.
+icon: eye
+models: [openai-codex/gpt-5.6-sol, zai/glm-5.3]
+notForParentModels: [openai-codex/gpt-5.6-sol*, zai/glm-5.3]
+thinking: high
+tools: [read, grep, bash]
+---
+
+# Frontier code review
+
+Review the implementation independently. Inspect the actual diff and the
+surrounding contracts; do not accept the implementer's summary as evidence.
+
+Look for correctness bugs, regressions, broken invariants, unsafe edge cases,
+missing error handling, concurrency/state mistakes, security issues, and tests
+that fail to cover a material behavior change. Prefer a small number of
+actionable findings over stylistic commentary or speculative rewrites.
+
+Do not edit source or tests. Run narrow read-only checks when they materially
+increase confidence. For each finding, give severity, rationale, and precise
+file/line evidence. If there are no findings, say so explicitly and name any
+important residual risk or verification gap.

package/external/pi-tools-suite/src/async-subagents/agents/presets.jsonc

@@ -0,0 +1,16 @@
+{
+  // Presets are available-model pools. Agent candidate order still comes from
+  // each agent's Markdown frontmatter; pool order never reorders candidates.
+  "cheap": {
+    "description": "GLM pool: economical workers plus GLM-5.3 for frontier-review/oracle.",
+    "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
+  },
+  "gpt": {
+    "description": "GPT pool: Luna/Terra workers; Sol is available to frontier-review/oracle.",
+    "models": ["openai-codex/gpt-5.6-luna", "openai-codex/gpt-5.6-terra", "openai-codex/gpt-5.6-sol"]
+  },
+  "deep": {
+    "description": "Mixed pool; workers retain economical candidate order and frontier-review/oracle use strong models.",
+    "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "openai-codex/gpt-5.6-luna", "openai-codex/gpt-5.6-terra", "openai-codex/gpt-5.6-sol", "zai/glm-5.3"]
+  }
+}

package/external/pi-tools-suite/src/async-subagents/agents/research.md

@@ -1,5 +1,5 @@
 ---
-description: Read-only evidence gathering - search files, trace behavior, investigate hypotheses, or independently review a diff. Return findings with paths, not raw source. Use verify for running checks and implement for changes.
+description: Read-only evidence gathering - search files, trace behavior, investigate hypotheses, or analyze a focused review question. Return findings with paths, not raw source. Use frontier-review for the post-implementation code-review gate when available, verify for running checks, and implement for changes.
 icon: search
 models: [zai/glm-5-turbo, openai-codex/gpt-5.6-luna]
 thinking: low
@@ -9,8 +9,10 @@ tools: [read, grep]
 # Research
 
 Investigate the assigned question within scope. Read and compare evidence; do
-not edit files or invent missing facts. A review is a fresh investigation of
-the supplied diff, not approval based on the implementer's summary.
+not edit files or invent missing facts. When assigned a review question, make
+it a fresh investigation of the relevant code, not approval based on another
+agent's summary. The broad post-implementation review gate belongs to
+frontier-review when that role is available.
 
 Return the answer and supporting file:line references, distinguishing confirmed
 findings from hypotheses. Report gaps or a concrete blocker when the available

package/external/pi-tools-suite/src/async-subagents/commands.ts

@@ -3,15 +3,12 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { ignoreStaleExtensionContextError } from "../context-usage.js";
 import {
-	copySubagentConfigSample,
 	ensureSessionFileLink,
-	existingSubagentConfigFiles,
 	findSubagentSessionByFile,
 	getActiveSubagentPresetName,
-	getDefaultSubagentConfigPath,
+	getBuiltinSubagentPresetsPath,
+	getProjectSubagentPresetsPath,
 	getSessionSubagentPresetOverride,
-	getSubagentConfigInitTargetPath,
-	getSubagentConfigSamplePath,
 	getSubagentPresetSelectionPath,
 	getRunState,
 	listRunDirs,
@@ -49,7 +46,6 @@ type MessageSender = ExtensionAPI & {
 };
 
 const CLEAR_ACTIVE_PRESET_LABEL = "Use no active preset";
-const COPY_SAMPLE_CONFIG_LABEL = "Copy sample asyncSubagents config";
 
 export const ULTRAWORK_PROMPT = `Run ultrawork mode for the current objective.
 
@@ -192,12 +188,10 @@ async function triggerOrchestrationPrompt(
 
 function registerPresetCommands(pi: ExtensionAPI): void {
 	pi.registerCommand("subagent-preset", {
-		description: "Select a sub-agent preset defined in asyncSubagents config, run session <name> for a process override, or init to copy the sample config",
+		description: "Select a sub-agent model-pool preset, or run session <name> for a process-only override",
 		getArgumentCompletions: (prefix: string) => {
-			const names = existingSubagentConfigFiles(process.cwd()).length > 0
-				? sortedPresetNames(loadSubagentConfig(process.cwd()).presets ?? {}, getActiveSubagentPresetName())
-				: [];
-			return [...names, ...names.map((name) => `session ${name}`), "list", "path", "config", "init", "clear", "session", "session-clear"]
+			const names = sortedPresetNames(loadSubagentConfig(process.cwd()).presets ?? {}, getActiveSubagentPresetName());
+			return [...names, ...names.map((name) => `session ${name}`), "list", "path", "clear", "session", "session-clear"]
 				.filter((name) => name.startsWith(prefix))
 				.map((name) => ({ value: name, label: name }));
 		},
@@ -209,28 +203,19 @@ function registerPresetCommands(pi: ExtensionAPI): void {
 			if (name === "session-clear") return clearSessionActiveSubagentPreset(ctx);
 			if (name === "list") return listSubagentPresets(ctx);
 			if (name === "path") return showSubagentPresetPaths(ctx);
-			if (name === "config") return showSubagentPresetConfigurator(ctx);
-			if (name === "init") return initSubagentConfigSample(ctx);
 			if (name === "clear") return clearActiveSubagentPreset(ctx);
-			if (existingSubagentConfigFiles(ctx.cwd).length === 0) return ctx.ui.notify(missingSubagentConfigMessage(ctx), "warning");
 
 			const config = loadSubagentConfig(ctx.cwd);
 			const preset = config.presets?.[name];
-			if (!preset) return ctx.ui.notify(`Unknown sub-agent preset "${name}". Define it in asyncSubagents config or run /subagent-preset list.`, "error");
+			if (!preset) return ctx.ui.notify(`Unknown sub-agent preset "${name}". Run /subagent-preset list to see available pools.`, "error");
 			setActiveSubagentPreset(name);
 			notifyActiveSubagentPreset(ctx, name, preset);
 		},
 	});
-
-	pi.registerCommand("subagent-preset-config", {
-		description: "Select sub-agent presets defined in asyncSubagents config",
-		handler: async (_args: string, ctx: CommandContext) => showSubagentPresetConfigurator(ctx),
-	});
 }
 
 async function showSubagentPresetSelector(ctx: CommandContext): Promise<void> {
 	if (!ctx.hasUI) return ctx.ui.notify("Sub-agent preset selector requires interactive UI. Use /subagent-preset <name>.", "warning");
-	if (existingSubagentConfigFiles(ctx.cwd).length === 0) return showMissingSubagentConfigSelector(ctx);
 
 	const config = loadSubagentConfig(ctx.cwd);
 	const activePreset = getActiveSubagentPresetName();
@@ -240,12 +225,12 @@ async function showSubagentPresetSelector(ctx: CommandContext): Promise<void> {
 	const labels = [...presetLabels];
 	if (activePreset) labels.push(CLEAR_ACTIVE_PRESET_LABEL);
 	if (labels.length === 0) {
-		ctx.ui.notify("No sub-agent presets are defined in asyncSubagents config.", "warning");
+		ctx.ui.notify("No sub-agent model-pool presets are available.", "warning");
 		showSubagentPresetPaths(ctx);
 		return;
 	}
 	const labelToName = new Map(presetLabels.map((label, index) => [label, names[index]]));
-	const selected = await ctx.ui.select(names.length > 0 ? "Select active sub-agent preset" : "No sub-agent presets in asyncSubagents config", labels);
+	const selected = await ctx.ui.select("Select active sub-agent preset", labels);
 	if (!selected) return;
 	if (selected === CLEAR_ACTIVE_PRESET_LABEL) return clearActiveSubagentPreset(ctx);
 
@@ -254,69 +239,29 @@ async function showSubagentPresetSelector(ctx: CommandContext): Promise<void> {
 	setActiveSubagentPreset(name);
 	notifyActiveSubagentPreset(ctx, name, presets[name]);
 }
-
-async function showSubagentPresetConfigurator(ctx: CommandContext): Promise<void> {
-	if (!ctx.hasUI) return ctx.ui.notify("Sub-agent preset selector requires interactive UI.", "warning");
-	return showSubagentPresetSelector(ctx);
-}
-
-async function showMissingSubagentConfigSelector(ctx: CommandContext): Promise<void> {
-	const selected = await ctx.ui.select("No asyncSubagents config found", [COPY_SAMPLE_CONFIG_LABEL]);
-	if (selected === COPY_SAMPLE_CONFIG_LABEL) initSubagentConfigSample(ctx);
-}
-
 function listSubagentPresets(ctx: CommandContext): void {
-	if (existingSubagentConfigFiles(ctx.cwd).length === 0) {
-		ctx.ui.notify(missingSubagentConfigMessage(ctx), "warning");
-		return;
-	}
 	const config = loadSubagentConfig(ctx.cwd);
 	const activePreset = getActiveSubagentPresetName();
 	const presets = config.presets ?? {};
 	const names = sortedPresetNames(presets, activePreset);
-	if (names.length === 0) return ctx.ui.notify("No sub-agent presets are defined in asyncSubagents config.", "warning");
+	if (names.length === 0) return ctx.ui.notify("No sub-agent model-pool presets are available.", "warning");
 	ctx.ui.notify([
-		"Sub-agent presets from asyncSubagents config:",
+		"Sub-agent model-pool presets:",
 		...names.map((name) => `- ${subagentPresetLabel(name, presets[name], activePreset)}`),
 	].join("\n"), "info");
 }
 
 function showSubagentPresetPaths(ctx: CommandContext): void {
 	ctx.ui.notify([
-		"Preset definitions: asyncSubagents in ~/.config/pi/pi-tools-suite.jsonc, $PI_CONFIG_DIR/pi-tools-suite.jsonc, or project .pi/pi-tools-suite.jsonc",
-		"Explicit override files are still supported via ASYNC_SUBAGENTS_CONFIG / PI_SUBAGENTS_CONFIG.",
-		`Default config target: ${getDefaultSubagentConfigPath()}`,
-		`Sample config: ${getSubagentConfigSamplePath()}`,
-		`Copy sample target: ${getSubagentConfigInitTargetPath(ctx.cwd)}`,
+		`Bundled presets: ${getBuiltinSubagentPresetsPath()}`,
+		`Project preset override: ${getProjectSubagentPresetsPath(ctx.cwd)}`,
+		"Project presets are defined as model pools in .pi/agents/presets.jsonc; agent behavior stays in .pi/agents/*.md.",
 		`Active selection state: ${getSubagentPresetSelectionPath()}`,
 		`Session override: ${formatSessionPresetOverride()}`,
 		"Use /subagent-preset session <name> to override only the current Pi process; use /subagent-preset session-clear to clear that runtime override.",
-		"Run /subagent-preset init to copy the bundled sample only when no config exists.",
 	].join("\n"), "info");
 }
 
-function initSubagentConfigSample(ctx: CommandContext): void {
-	try {
-		const result = copySubagentConfigSample(ctx.cwd);
-		if (result.copied) {
-			ctx.ui.notify(`Copied sample asyncSubagents config:\n${result.samplePath}\n→ ${result.targetPath}`, "info");
-			return;
-		}
-		ctx.ui.notify(`AsyncSubagents config already exists; not overwriting:\n${result.existingFiles.join("\n") || result.targetPath}`, "warning");
-	} catch (error) {
-		ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-	}
-}
-
-function missingSubagentConfigMessage(ctx: CommandContext): string {
-	return [
-		"No asyncSubagents config found in pi-tools-suite config.",
-		`Sample config: ${getSubagentConfigSamplePath()}`,
-		`Copy target: ${getSubagentConfigInitTargetPath(ctx.cwd)}`,
-		"Run /subagent-preset init to copy the bundled sample into the shared config.",
-	].join("\n");
-}
-
 function clearActiveSubagentPreset(ctx: CommandContext): void {
 	setActiveSubagentPreset(undefined);
 	const override = getSessionSubagentPresetOverride();
@@ -327,10 +272,9 @@ function clearActiveSubagentPreset(ctx: CommandContext): void {
 
 function setSessionActiveSubagentPreset(ctx: CommandContext, name: string): void {
 	if (!name) return ctx.ui.notify("Usage: /subagent-preset session <name>", "warning");
-	if (existingSubagentConfigFiles(ctx.cwd).length === 0) return ctx.ui.notify(missingSubagentConfigMessage(ctx), "warning");
 	const config = loadSubagentConfig(ctx.cwd);
 	const preset = config.presets?.[name];
-	if (!preset) return ctx.ui.notify(`Unknown sub-agent preset "${name}". Define it in asyncSubagents config or run /subagent-preset list.`, "error");
+	if (!preset) return ctx.ui.notify(`Unknown sub-agent preset "${name}". Run /subagent-preset list to see available pools.`, "error");
 	setSessionSubagentPresetOverride(name);
 	ctx.ui.notify(`Session-only sub-agent preset "${name}": ${subagentPresetDescription(preset)}\nApplies to future sub-agent spawns only until this Pi process exits or /subagent-preset session-clear is run. Saved preset selection is unchanged.`, "info");
 }

package/external/pi-tools-suite/src/async-subagents/core/activity.ts

@@ -0,0 +1,33 @@
+import type { AgentActivity, RpcEventRecord } from "./types.js";
+import { isRecord, isoNow } from "./utils.js";
+
+export function activityFromRpcEvent(event: RpcEventRecord, at = isoNow()): AgentActivity | undefined {
+	if (event.type === "tool_execution_start") {
+		const toolName = nonEmptyString(event.toolName);
+		return toolName ? { label: toolName, at } : undefined;
+	}
+	if ((event.type === "message_start" || event.type === "message_end") && rpcMessageRole(event) === "assistant") {
+		return { label: "Thinking", at };
+	}
+	return undefined;
+}
+
+export function activityFromProgressRecord(value: unknown): AgentActivity | undefined {
+	if (!isRecord(value) || value.stage !== "rpc_event") return undefined;
+	const at = nonEmptyString(value.at);
+	if (!at) return undefined;
+	const toolName = nonEmptyString(value.toolName);
+	if (toolName) return { label: toolName, at };
+	if (value.type === "message_start" || value.type === "message_end") return { label: "Thinking", at };
+	return undefined;
+}
+
+function rpcMessageRole(event: RpcEventRecord): string | undefined {
+	const directRole = nonEmptyString(event.role);
+	if (directRole) return directRole;
+	return isRecord(event.message) ? nonEmptyString(event.message.role) : undefined;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/external/pi-tools-suite/src/async-subagents/core/agent-catalog.ts

@@ -1,7 +1,7 @@
-import type { SubagentConfig } from "./config.js";
+import { filterSubagentConfigForParentModel, type SubagentConfig } from "./config.js";
 import { SUBAGENT_DELEGATION_GUIDANCE } from "./agent-strategy.js";
 
-export const SUBAGENT_TYPE_SELECTION_GUIDANCE = "Choose and set subagentType from the available catalog when a role clearly matches, preferring a matching project-local specialist. Preserve a user-requested role. Omit subagentType only when unsure or when the user explicitly requests automatic routing; the LLM router handles omissions only. Model/thinking overrides are not substitutes for choosing a role.";
+export const SUBAGENT_TYPE_SELECTION_GUIDANCE = "Choose and set subagentType from the available catalog when a role clearly matches, preferring a matching project-local specialist. Preserve a user-requested role when it is available in the current catalog. Omit subagentType only when unsure or when the user explicitly requests automatic routing; the LLM router handles omissions only. Model/thinking overrides are not substitutes for choosing a role.";
 
 const MAX_DESCRIPTION_CHARS = 500;
 
@@ -10,8 +10,9 @@ const MAX_DESCRIPTION_CHARS = 500;
  * The config has already merged built-ins, config files, and project-local
  * `.pi/agents/*.md`, so this stays aligned with what spawn/routing can use.
  */
-export function buildSubagentCatalogPrompt(config: SubagentConfig): string | undefined {
-	const entries = Object.entries(config.types).sort(([left], [right]) => left.localeCompare(right));
+export function buildSubagentCatalogPrompt(config: SubagentConfig, parentModelRef?: string): string | undefined {
+	const effectiveConfig = filterSubagentConfigForParentModel(config, parentModelRef);
+	const entries = Object.entries(effectiveConfig.types).sort(([left], [right]) => left.localeCompare(right));
 	if (entries.length === 0) return undefined;
 
 	return [

package/external/pi-tools-suite/src/async-subagents/core/agent-strategy.ts

@@ -7,7 +7,7 @@ export interface AgentStrategyOptions {
 }
 
 /** Shared by the strategy, tool description and role catalog. */
-export const SUBAGENT_DELEGATION_GUIDANCE = "Delegate bounded work when a lower-cost worker can do it or noisy intermediate evidence should stay out of the parent context; one sequential task can qualify. Keep planning, decisions, integration and the final answer in the parent. Use research for evidence/review, implement for code/docs/tests/UI changes, verify for running checks, browser-qa for browser testing. Reserve oracle for a deliberate strong independent opinion, not automatic escalation. Do trivial lookups/edits directly; redirect a noisy command to a log instead of spawning an LLM when no interpretation is needed.";
+export const SUBAGENT_DELEGATION_GUIDANCE = "Delegate bounded work when a lower-cost worker can do it or noisy intermediate evidence should stay out of the parent context; one sequential task can qualify. Keep planning, decisions, integration and the final answer in the parent. Use research for evidence/focused review questions, implement for code/docs/tests/UI changes, verify for running checks, browser-qa for browser testing. When frontier-review is present in the current role catalog and substantive code changed, use it as the independent post-implementation review gate before finalizing; it is intentionally hidden for parent models excluded by its profile. Reserve oracle for a deliberate strong independent opinion, not routine code review. Do trivial lookups/edits directly; redirect a noisy command to a log instead of spawning an LLM when no interpretation is needed.";
 
 export function agentStrategyPrompt(options: AgentStrategyOptions = {}): string | undefined {
 	const env = options.env ?? process.env;

package/external/pi-tools-suite/src/async-subagents/core/agents-dir.ts

@@ -46,6 +46,8 @@ const KNOWN_FRONTMATTER_KEYS = new Set([
 	"model",
 	"fallbackModels",
 	"modelByParent",
+	"forParentModels",
+	"notForParentModels",
 	"thinking",
 	"tools",
 	"isolatedSkills",
@@ -62,6 +64,8 @@ const COMMA_SEPARATED_ARRAY_KEYS = new Set([
 	"tools",
 	"models",
 	"fallbackModels",
+	"forParentModels",
+	"notForParentModels",
 	"isolatedSkills",
 	"extraArgs",
 	"retryableExitCodes",
@@ -72,7 +76,7 @@ const NUMERIC_PATTERN = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
 
 /** Discover and parse `.pi/agents/*.md` for the project containing `cwd`. */
 export function readProjectAgentDefinitions(cwd: string): Record<string, ProjectAgentDefinition> {
-	const dir = findProjectAgentsDir(cwd);
+	const dir = projectAgentsDir(cwd);
 	return dir ? readAgentDefinitionsFromDir(dir) : {};
 }
 
@@ -94,7 +98,7 @@ export function readAgentDefinitionsFromDir(dir: string): Record<string, AgentDe
  * deterministic merge order.
  */
 export function projectAgentDefinitionFiles(cwd: string): string[] {
-	const dir = findProjectAgentsDir(cwd);
+	const dir = projectAgentsDir(cwd);
 	return dir ? agentDefinitionFiles(dir) : [];
 }
 
@@ -108,7 +112,8 @@ export function agentDefinitionFiles(dir: string): string[] {
 		.sort();
 }
 
-function findProjectAgentsDir(startDir: string): string | undefined {
+/** First project `.pi/agents` directory found walking up from cwd. */
+export function projectAgentsDir(startDir: string): string | undefined {
 	let dir = path.resolve(startDir);
 	const root = path.parse(dir).root;
 	while (true) {