pi-subagents 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-06-24
+
+### Added
+- Added `subagents.disableThinking` so bundled builtin agents can drop thinking suffix defaults for providers that do not accept them. Thanks to Joshua Harding (@jhstatewide) for #212.
+- Discover nested grouped skills such as `.pi/skills/group/name/SKILL.md` so subagents match the host runtime's recursive skill lookup. Thanks to Weaxs (@Weaxs) for #262.
+- Follow Pi's configured project config directory for project-local agents, chains, skills, packages, settings, direct MCP config, and intercom package discovery instead of hardcoding `.pi`, while retaining `.pi` as the fallback for older Pi versions.
+
+### Changed
+- Hardened npm installs by tracking `package-lock.json`, pinning direct dependencies, and using `npm ci --ignore-scripts` in CI and release workflows. Thanks to Modestas Vainius (@modax) for #234.
+- List configured subagent skills by name, description, and file path instead of inlining full skill bodies, and ensure tool-restricted children can read those skill files on demand. Thanks to Ruben Paz (@Istar-Eldritch) for #183.
+
+### Fixed
+- Resolve the async result watcher directory with `fs.realpathSync.native()` before `fs.watch()` so Windows profiles with 8.3 temp paths do not crash Pi when async subagent results arrive. Thanks to kerushidao (@kerushidao) for #254.
+- Accept structured acceptance reports emitted in JSON-family fences when the fenced body has the acceptance-report shape. Thanks to Suleiman Tawil (@stawils) for #253.
+- Report field-level acceptance-report validation errors instead of a generic parse failure, and clarify array element types in the acceptance prompt. Thanks to Whisperfall (@Whisperfall) for #264 and josephkEA (@josephkEA) for the follow-up reproduction.
+- Simplified the public `acceptance` and chain tool schemas so Kimi/Moonshot-style parsers can load `subagent`, while runtime validation still rejects malformed acceptance config and dynamic fanout steps. Thanks to Sergio Agosti (@sergio-agosti) for #249.
+- Reject duplicate concurrent `subagent` execution calls while a prior subagent dispatch is still in progress, keeping intentional parallel mode within a single call unchanged. Thanks to desideratum (@desideratum) for #247.
+- Bound async `events.jsonl` growth by dropping noisy child `message_update` snapshots, capping persisted child diagnostics, and scanning control events in chunks during status polling. Thanks to Tri Van Pham (@pvtri96) for #246.
+- Keep crowded async subagent widgets at a stable collapsed height in short terminals, reducing destructive full-screen TUI redraws and flicker. Thanks to ssyram (@ssyram) for #186.
+- Actually wire the previously documented foreground-only `timeoutMs`/`maxRuntimeMs` aliases through single, parallel, chain, and dynamic fanout runs, including stable `timedOut: true` results, preserved partial output, manual-interrupt precedence, and skipped acceptance verification after timeout.
+- Apply `subagents.agentOverrides.<name>` to matching user-scope and project-scope custom agents, while keeping explicit agent frontmatter authoritative per field. Thanks to Jacek Juraszek (@jjuraszek) for #218.
+- Preserve compact foreground `write`/`edit` tool-call evidence in prompt-template delegation responses so convergence checks do not stop loops early. Thanks to Hans Schnedlitz (@hschne) for #207.
+- Respect each agent's `defaultContext` in mixed parallel and chain subagent calls when no explicit `context` is provided, so fresh-default scouts no longer inherit forked parent transcripts just because another agent in the same invocation defaults to fork. Thanks to Mitch Fultz (@fitchmultz) for #228.
+- Make runtime `output` overrides authoritative in child task and system prompts, and remove stale static filenames from bundled output-format instructions. Thanks to youngshine (@smithyyang) for #223.
+- Keep top-level parallel `defaultProgress` files in run-scoped artifact storage instead of the parent working directory. Thanks to youngshine (@smithyyang) for #224.
+
 ## [0.30.0] - 2026-06-20
 
 ### Added

package/README.md

@@ -115,7 +115,7 @@ The extension ships with builtin agents you can use immediately.
 
 A simple rule of thumb: use `scout` before you understand the code, `researcher` before you trust external facts, `planner` before a bigger change, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
 
-## Changing a builtin agent's model
+## Changing an agent's model
 
 Builtin agents inherit your current Pi default model by default. This keeps new installs from depending on a provider you may not have configured. If you want a role to use a specific model, set an override instead of copying the bundled agent file.
 
@@ -141,7 +141,18 @@ For a persistent override, edit settings. This example pins the reviewer everywh
 }
 ```
 
-Use `~/.pi/agent/settings.json` for a user override or `.pi/settings.json` for a project override. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable a builtin. If you want a totally different agent, create a user or project agent with the same name; for normal tweaks, prefer overrides.
+Use `~/.pi/agent/settings.json` for a user override or the project config settings file (`.pi/settings.json` in standard Pi) for a project override. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable a builtin. Matching user and project agents also receive override fields that their frontmatter leaves unset, so a shared project config agent can keep the persona while local settings choose the model. Explicit frontmatter still wins.
+
+If your provider rejects model IDs with thinking suffixes, set `subagents.disableThinking: true` in user or project settings. That clears bundled builtin thinking defaults in one place; an explicit higher-precedence `agentOverrides.<name>.thinking` value can opt a role back in.
+
+To inspect what `pi-subagents` has actually loaded right now, use:
+
+```text
+/subagents-models
+/subagents-models reviewer
+```
+
+That reports the live runtime mapping, which can differ from settings on disk until you reload Pi.
 
 ## Where running subagents show up
 
@@ -237,6 +248,79 @@ For normal use, you do not need to configure anything. Advanced users can tune t
 
 At this point, you know enough to use the plugin. The rest of this README is reference material for exact command syntax, custom agents, saved chains, worktrees, and configuration.
 
+## Optional pi-permission-system integration
+
+[`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system)
+adds a second policy layer — `allow` / `ask` / `deny` — on top of
+pi-subagents' visibility-based tool restrictions.
+
+The two compose independently:
+
+| Layer | What it controls | Who provides it |
+|-------|-----------------|-----------------|
+| Visibility | Which tools are registered before the session starts | pi-subagents (`tools:` frontmatter key) |
+| Policy  | Runtime allow/ask/deny decisions on every tool call, bash command, MCP operation | pi-permission-system (`permission:` frontmatter key) |
+
+### Installing
+
+```bash
+pi install npm:@gotgenes/pi-permission-system
+```
+
+No configuration is required for the integration — it is automatic when both
+extensions are installed. pi-subagents passes the parent session identity
+to child processes via the `PI_SUBAGENT_PARENT_SESSION` environment variable,
+which the permission system uses to forward `ask` prompts from headless
+subagent processes back to the parent session's UI.
+
+### Per-agent permission frontmatter
+
+Agent files can include a `permission:` block alongside the standard `tools:`
+key. The permission system reads it independently:
+
+```yaml
+---
+name: worker
+tools: bash,read,write,edit
+permission:
+  "*": ask
+  read: allow
+  bash:
+    "*": ask
+    "git *": allow
+    "npm test": allow
+---
+```
+
+In this example the subagent extension restricts visibility to four tools,
+and the permission system then applies `ask`/`allow` policy within that
+visible set. Both keys coexist without collision.
+
+### Checking the integration
+
+Run `/subagents-doctor` to check the permission system status.
+If `ask` prompts from children are not reaching the parent UI, verify both
+extensions are installed:
+
+```bash
+pi list
+```
+
+### How it works
+
+At session start, the interactive (root) session records its own identity in
+`PI_SUBAGENT_PARENT_SESSION`. When pi-subagents launches a child, it passes the
+launching session's identity to that child explicitly, falling back to the
+inherited environment variable. When the permission system inside a child
+encounters an `ask` permission, it reads this variable to locate the parent
+session and forwards the confirmation request there.
+
+This resolves an interactive prompt only when the parent it points at is the
+interactive session — i.e. for the direct children of the root session. A
+nested child's parent is itself a headless subagent process with no UI to
+surface the prompt, so `ask` policies are best placed on agents that run as
+direct children of the interactive session.
+
 ## Direct commands
 
 Skip this section until you want exact syntax.
@@ -248,6 +332,7 @@ Skip this section until you want exact syntax.
 | `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel |
 | `/run-chain <chainName> -- <task>` | Launch a saved `.chain.md` or `.chain.json` workflow |
 | `/subagents-doctor` | Show read-only setup diagnostics |
+| `/subagents-models [agent]` | Show the runtime-loaded builtin model mapping, optionally filtered to one builtin |
 
 Commands validate agent names locally, support tab completion, and send results back into the conversation.
 
@@ -296,7 +381,7 @@ Append `[key=value,...]` to an agent name to override defaults for that step:
 | `outputMode` | `outputMode=file-only` | Return only a concise file reference for saved output instead of the full saved content. Requires `output`; default is `inline`. |
 | `reads` | `reads=a.md+b.md` | Read files before executing. `+` separates multiple paths. |
 | `model` | `model=anthropic/claude-sonnet-4` | Override model for this step. |
-| `skills` | `skills=planning+review` | Override injected skills. `+` separates multiple skills. |
+| `skills` | `skills=planning+review` | Override available skills. `+` separates multiple skills. |
 | `progress` | `progress` | Enable progress tracking. |
 
 Set `output=false`, `reads=false`, or `skills=false` to disable that behavior explicitly. Do not use `output=false` for file-only returns; use `outputMode=file-only` with an `output` path.
@@ -360,9 +445,9 @@ Agent locations, lowest to highest priority:
 | Builtin | `~/.pi/agent/extensions/subagent/agents/` |
 | Installed package | `package.json` `pi-subagents.agents` or `pi.subagents.agents` |
 | User | `~/.pi/agent/agents/**/*.md` |
-| Project | `.pi/agents/**/*.md` |
+| Project | Project config `agents/**/*.md` (`.pi/agents/**/*.md` in standard Pi) |
 
-Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. Installed Pi packages can expose agent directories from either `{"pi-subagents":{"agents":["./agents"]}}` or `{"pi":{"subagents":{"agents":["./agents"]}}}` in their package manifest. Package agents load above builtins and below user/project agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
+Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. Installed Pi packages can expose agent directories from either `{"pi-subagents":{"agents":["./agents"]}}` or `{"pi":{"subagents":{"agents":["./agents"]}}}` in their package manifest. Package agents load above builtins and below user/project agents. If both `.agents/` and the project config agents directory define the same parsed runtime agent name, the project config directory wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
 
 Builtin agents load at the lowest priority, so a user or project agent with the same name overrides them. They do not pin a provider model; they inherit your current Pi default model unless you set `subagents.agentOverrides.<name>.model`. `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `worker` is the implementation agent for normal tasks and approved oracle handoffs.
 
@@ -377,7 +462,7 @@ pi install npm:pi-web-access
 You can override selected builtin fields without copying the whole agent. Overrides live in settings:
 
 - User: `~/.pi/agent/settings.json`
-- Project: `.pi/settings.json`
+- Project: project config settings file (`.pi/settings.json` in standard Pi)
 
 Example:
 
@@ -397,6 +482,8 @@ Supported override fields are `model`, `fallbackModels`, `thinking`, `systemProm
 
 Set `disabled: true` to hide a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output. For bulk control, set `subagents.disableBuiltins: true` in settings.
 
+Set `subagents.disableThinking: true` to clear bundled builtin thinking defaults globally for providers that do not support `:low`, `:medium`, `:high`, or similar model suffixes. A higher-precedence per-agent `thinking` override can opt one builtin back in.
+
 ### Prompt assembly
 
 Subagents are designed to be narrow by default. Custom agents start with a clean system prompt and only the context you intentionally give them. They do not automatically inherit Pi’s whole base prompt, project instruction files, or discovered skills catalog.
@@ -458,7 +545,7 @@ Important fields:
 | `inheritProjectContext` | Keeps or strips inherited project instruction blocks. |
 | `inheritSkills` | Keeps or strips Pi’s discovered skills catalog. |
 | `defaultContext` | Optional `fresh` or `fork` launch context default for this agent. |
-| `skills` | Injects specific skills directly, regardless of `inheritSkills`. |
+| `skills` | Adds specific skills to the child’s available skill list, regardless of `inheritSkills`. |
 | `output` | Default single-agent output file. |
 | `defaultReads` | Files to read before running in chain/parallel behavior. |
 | `defaultProgress` | Maintain `progress.md`. |
@@ -503,7 +590,7 @@ Chains are reusable workflows stored separately from agent files. Use `.chain.md
 |-------|------|
 | Installed package | `package.json` `pi-subagents.chains` or `pi.subagents.chains` |
 | User | `~/.pi/agent/chains/**/*.chain.md`, `~/.pi/agent/chains/**/*.chain.json` |
-| Project | `.pi/chains/**/*.chain.md`, `.pi/chains/**/*.chain.json` |
+| Project | Project config `chains/**/*.chain.md`, `chains/**/*.chain.json` (`.pi/chains/...` in standard Pi) |
 
 Nested subdirectories are discovered recursively. Installed Pi packages can expose chain directories from either `{"pi-subagents":{"chains":["./chains"]}}` or `{"pi":{"subagents":{"chains":["./chains"]}}}` in their package manifest. Package chains load below user/project chains. If both `.chain.md` and `.chain.json` define the same parsed runtime chain name in the same scope, `.chain.json` wins. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
@@ -605,14 +692,14 @@ Parallel outputs are aggregated with clear separators before being passed to the
 
 ## Skills
 
-Skills are `SKILL.md` files injected into an agent’s system prompt.
+Skills are `SKILL.md` files made available to an agent. The prompt includes skill metadata and the file location; the agent reads the full skill file only when the task matches.
 
 Discovery uses project-first precedence:
 
-1. `.pi/skills/{name}/SKILL.md`
+1. Project config `skills/{name}/SKILL.md` (`.pi/skills/{name}/SKILL.md` in standard Pi)
 2. Project packages and project settings packages via `package.json -> pi.skills`
 3. Current task cwd package via `package.json -> pi.skills`
-4. `.pi/settings.json -> skills`
+4. Project config `settings.json -> skills`
 5. `~/.pi/agent/skills/{name}/SKILL.md`
 6. User packages and user settings packages via `package.json -> pi.skills`
 7. `~/.pi/agent/settings.json -> skills`
@@ -627,14 +714,24 @@ Use agent defaults, override them at runtime, or disable them:
 
 For chains, `skill` at the top level is additive. A step-level `skill` overrides that step; `false` disables skills for that step.
 
-Injected skills use this shape:
+Available skills use this shape:
 
 ```xml
-<skill name="safe-bash">
-[skill content from SKILL.md, frontmatter stripped]
-</skill>
+The following configured skills are available to this subagent.
+Use the read tool to load a skill's file when the task matches its description.
+When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.
+
+<available_skills>
+  <skill>
+    <name>safe-bash</name>
+    <description>Run shell commands safely.</description>
+    <location>/absolute/path/to/safe-bash/SKILL.md</location>
+  </skill>
+</available_skills>
 ```
 
+If an agent has an explicit `tools` allowlist and resolved skills, `read` is added for that child run so the listed skill files can be loaded on demand.
+
 Missing skills do not fail execution. The result summary shows a warning.
 
 ### Bundled skill
@@ -743,6 +840,8 @@ Agent definitions are not loaded into context by default. Management actions let
 { action: "list" }
 { action: "list", agentScope: "project" }
 { action: "get", agent: "scout" }
+{ action: "models" }
+{ action: "models", agent: "reviewer" }
 { action: "get", agent: "code-analysis.scout" }
 { action: "get", chainName: "review-pipeline" }
 
@@ -801,7 +900,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
 | `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Steps and chain parallel tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`. With `action: "append-step"`, pass exactly one step to append to a running async chain. |
-| `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
+| `context` | `fresh \| fork` | per-agent default or `fresh` | Explicit `fresh` or `fork` overrides every child. When omitted, each agent uses its own `defaultContext`; `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
 | `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
 | `clarify` | boolean | true for chains | Show TUI preview/edit flow. |
 | `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
@@ -814,7 +913,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `sessionDir` | string | derived | Override session log directory. |
 | `acceptance` | string/object/false | inferred | Override the run's inferred acceptance gates. Use `"auto"`, `"attested"`, `"checked"`, `"verified"`, `"reviewed"`, or `{ level: "none", reason: "..." }`. |
 
-`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`. In multi-agent runs, if any requested agent has `defaultContext: fork` and the launch omits `context`, the whole invocation uses forked context; pass `context: "fresh"` when you intentionally want a fresh run.
+`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`. In multi-agent runs that omit `context`, each agent/task/step follows its own `defaultContext`, so a fresh-default scout can run fresh beside a fork-default worker. Pass explicit `context: "fork"` or `context: "fresh"` when you intentionally want one context for every child.
 
 Use `outputMode: "file-only"` when a saved output may be large and the parent only needs a pointer. The returned text is a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Failed runs and save errors still return normal inline output for debugging. In chains, later `{previous}` steps receive the same compact reference when the prior step used file-only mode.
 

package/agents/context-builder.md

@@ -23,14 +23,14 @@ Working rules:
 - Write the requested output files clearly and concretely.
 - Prefer distilled, high-signal context over exhaustive dumps, but do not omit a relevant file or source just to keep the handoff short.
 
-When running in a chain, expect to generate two files in the chain directory:
+When running in a chain, expect to generate context and meta-prompt handoff material. Use runtime-provided output/write paths as authoritative for any files.
 
-`context.md`
+Context handoff:
 - relevant files with line numbers and key snippets
 - important patterns already used in the codebase
 - dependencies, constraints, and implementation risks
 
-`meta-prompt.md`
+Meta-prompt handoff:
 - goal: the concrete outcome the next agent should produce
 - context/evidence: relevant files, diffs, decisions, constraints, and source-backed facts
 - success criteria: what must be true before the next agent can finish

package/agents/planner.md

@@ -23,7 +23,7 @@ Working rules:
 - Call out risks, dependencies, and anything that needs explicit validation.
 - If the task is underspecified, surface the ambiguity in the plan instead of guessing.
 
-Output format (`plan.md`):
+Output format:
 
 # Implementation Plan
 

package/agents/researcher.md

@@ -29,7 +29,7 @@ Search strategy:
 - practical experience or benchmark query
 - recent developments query when the topic is time-sensitive
 
-Output format (`research.md`):
+Output format:
 
 # Research: [topic]
 

package/agents/scout.md

@@ -28,7 +28,7 @@ Working rules:
 - If you are told to write output, write it to the provided path and keep the final response short.
 - When running solo, summarize what you found after writing the output.
 
-Output format (`context.md`):
+Output format:
 
 # Code Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -68,13 +68,13 @@
     }
   },
   "dependencies": {
-    "@earendil-works/pi-tui": "^0.74.0",
-    "jiti": "^2.7.0",
-    "typebox": "^1.1.24"
+    "@earendil-works/pi-tui": "0.74.0",
+    "jiti": "2.7.0",
+    "typebox": "1.1.24"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0"
+    "@earendil-works/pi-agent-core": "0.74.0",
+    "@earendil-works/pi-ai": "0.74.0",
+    "@earendil-works/pi-coding-agent": "0.74.0"
   }
 }

package/skills/pi-subagents/SKILL.md

@@ -236,6 +236,11 @@ Useful override fields: `model`, `fallbackModels`, `thinking`,
 `disabled`, `skills`, `tools`, and `systemPrompt`. Create a user or project
 agent with the same name only when you want a substantially different agent.
 
+If a provider rejects model IDs with thinking suffixes, use
+`subagents.disableThinking: true` in user or project settings to clear bundled
+builtin thinking defaults globally. A higher-precedence per-agent `thinking`
+override can opt one builtin back in.
+
 ## Discovery and Scope Rules
 
 Agent files can live in:

package/src/agents/agent-management.ts

@@ -8,6 +8,7 @@ import {
 	type AgentSource,
 	type ChainConfig,
 	type ChainStepConfig,
+	BUILTIN_AGENT_NAMES,
 	defaultInheritProjectContext,
 	defaultInheritSkills,
 	defaultSystemPromptMode,
@@ -22,11 +23,15 @@ import { discoverAvailableSkills } from "./skills.ts";
 import {
 	buildProactiveSkillSubagentRecommendationLines,
 } from "./proactive-skills.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { toModelInfo } from "../shared/model-info.ts";
+import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import type { Details, ExtensionConfig } from "../shared/types.ts";
+import { getProjectConfigDir } from "../shared/utils.ts";
 
-type ManagementAction = "list" | "get" | "create" | "update" | "delete";
+type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete";
 type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { config?: ExtensionConfig };
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig };
 
 interface ManagementParams {
 	action?: string;
@@ -166,6 +171,84 @@ function skillsWarning(cwd: string, skills: string[] | undefined): string | unde
 	return missing.length ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
 }
 
+function editableAgentConfig(agent: AgentConfig): AgentConfig {
+	const base = agent.override?.base;
+	if (!base) return { ...agent };
+
+	return {
+		...agent,
+		model: base.model,
+		fallbackModels: base.fallbackModels ? [...base.fallbackModels] : undefined,
+		thinking: base.thinking,
+		systemPromptMode: base.systemPromptMode,
+		inheritProjectContext: base.inheritProjectContext,
+		inheritSkills: base.inheritSkills,
+		defaultContext: base.defaultContext,
+		disabled: base.disabled,
+		systemPrompt: base.systemPrompt,
+		skills: base.skills ? [...base.skills] : undefined,
+		tools: base.tools ? [...base.tools] : undefined,
+		mcpDirectTools: base.mcpDirectTools ? [...base.mcpDirectTools] : undefined,
+		subagentOnlyExtensions: base.subagentOnlyExtensions ? [...base.subagentOnlyExtensions] : undefined,
+		completionGuard: base.completionGuard,
+		override: undefined,
+	};
+}
+
+function readAgentFrontmatterFields(filePath: string): Set<string> {
+	try {
+		const { frontmatter } = parseFrontmatter(fs.readFileSync(filePath, "utf-8"));
+		return new Set(Object.keys(frontmatter));
+	} catch {
+		return new Set();
+	}
+}
+
+function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string, unknown>): Set<string> {
+	const fields = readAgentFrontmatterFields(agent.filePath);
+	const changed = (...names: string[]) => {
+		for (const name of names) fields.delete(name);
+	};
+
+	if (hasKey(cfg, "name")) changed("name");
+	if (hasKey(cfg, "package")) changed("package");
+	if (hasKey(cfg, "description")) changed("description");
+	if (hasKey(cfg, "systemPrompt")) changed("systemPrompt");
+	if (hasKey(cfg, "model")) changed("model");
+	if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
+	if (hasKey(cfg, "tools")) changed("tools");
+	if (hasKey(cfg, "skills")) changed("skill", "skills");
+	if (hasKey(cfg, "extensions")) changed("extensions");
+	if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
+	if (hasKey(cfg, "thinking")) {
+		changed("thinking");
+		if (cfg.thinking === "off") fields.add("thinking");
+	}
+	if (hasKey(cfg, "systemPromptMode")) {
+		changed("systemPromptMode");
+		fields.add("systemPromptMode");
+	}
+	if (hasKey(cfg, "inheritProjectContext")) {
+		changed("inheritProjectContext");
+		fields.add("inheritProjectContext");
+	}
+	if (hasKey(cfg, "inheritSkills")) {
+		changed("inheritSkills");
+		fields.add("inheritSkills");
+	}
+	if (hasKey(cfg, "defaultContext")) changed("defaultContext");
+	if (hasKey(cfg, "output")) changed("output");
+	if (hasKey(cfg, "reads")) changed("defaultReads");
+	if (hasKey(cfg, "progress")) changed("defaultProgress");
+	if (hasKey(cfg, "maxSubagentDepth")) changed("maxSubagentDepth");
+	if (hasKey(cfg, "completionGuard")) {
+		changed("completionGuard");
+		if (cfg.completionGuard === true) fields.add("completionGuard");
+	}
+
+	return fields;
+}
+
 function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: string } {
 	if (!Array.isArray(raw)) return { error: "config.steps must be an array." };
 	if (raw.length === 0) return { error: "config.steps must include at least one step." };
@@ -480,6 +563,84 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	return result(lines.join("\n"));
 }
 
+function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {
+	if (agent.override && agent.model !== agent.override.base.model) {
+		return `${agent.override.scope} override`;
+	}
+	if (agent.model) return "builtin 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 discovered = discoverAgentsAll(ctx.cwd);
+	const builtinByName = new Map(discovered.builtin.map((agent) => [agent.name, agent]));
+	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];
+
+	if (requestedAgent) {
+		const agent = builtinByName.get(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}`);
+		}
+		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"));
+	}
+
+	const lines = [
+		"Builtin subagent models",
+		"",
+		"Current session model:",
+		`  ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
+		"",
+	];
+
+	for (const name of names) {
+		const agent = builtinByName.get(name);
+		if (!agent) {
+			lines.push(name);
+			lines.push("  model:");
+			lines.push("    (builtin definition not found)");
+			lines.push("  source: missing");
+			lines.push("");
+			continue;
+		}
+		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("");
+	}
+
+	return result(lines.join("\n"));
+}
+
 function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for get.", true);
 	const hasBoth = Boolean(params.agent && params.chainName);
@@ -527,9 +688,10 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const scope = scopeRaw as ManagementScope;
 	const isChain = hasKey(cfg, "steps");
 	const d = discoverAgentsAll(ctx.cwd);
+	const projectConfigDir = getProjectConfigDir(ctx.cwd);
 	const targetDir = isChain
-		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, ".pi", "chains")
-		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
+		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(projectConfigDir, "chains")
+		: scope === "user" ? d.userDir : d.projectDir ?? path.join(projectConfigDir, "agents");
 	fs.mkdirSync(targetDir, { recursive: true });
 	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
 	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);
@@ -583,7 +745,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
-		const updated: AgentConfig = { ...target };
+		const updated = editableAgentConfig(target);
 		const oldName = target.name;
 		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
@@ -600,6 +762,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		}
 		const applyError = applyAgentConfig(updated, cfg);
 		if (applyError) return result(applyError, true);
+		const preserveFrontmatterFields = preservedAgentFrontmatterFields(target, cfg);
 		updated.localName = newLocalName;
 		updated.packageName = newPackageName;
 		updated.name = buildRuntimeName(newLocalName, newPackageName);
@@ -621,7 +784,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 			if (renamed.error) return result(renamed.error, true);
 			updated.filePath = renamed.filePath!;
 		}
-		fs.writeFileSync(updated.filePath, serializeAgent(updated), "utf-8");
+		fs.writeFileSync(updated.filePath, serializeAgent(updated, { preserveFrontmatterFields }), "utf-8");
 		if (updated.name !== oldName) {
 			const refs = discoverAgentsAll(ctx.cwd).chains.filter((c) => c.steps.some((s) => s.agent === oldName)).map((c) => `${c.name} (${c.source})`);
 			if (refs.length) warnings.push(`Warning: chains still reference '${oldName}': ${refs.join(", ")}.`);
@@ -703,6 +866,7 @@ export function handleManagementAction(action: string, params: ManagementParams,
 	switch (action as ManagementAction) {
 		case "list": return handleList(params, ctx);
 		case "get": return handleGet(params, ctx);
+		case "models": return handleModels(params, ctx);
 		case "create": return handleCreate(params, ctx);
 		case "update": return handleUpdate(params, ctx);
 		case "delete": return handleDelete(params, ctx);