pi-subagents 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.8.0] - 2026-02-09
+
+### Added
+- **Management mode for `subagent` tool** via `action` field — the LLM can now discover, create, modify, and delete agent/chain definitions at runtime without manual file editing or restarts. Five actions:
+  - `list` — discover agents and chains with scope + description
+  - `get` — full detail for agent or chain, including path and system prompt/steps
+  - `create` — create agent (`.md`) or chain (`.chain.md`) definitions from `config`; immediately usable
+  - `update` — merge-update agent or chain fields, including rename with chain reference warnings
+  - `delete` — remove agent or chain definitions with dangling reference warnings
+- **New `agent-management.ts` module** with all management handlers, validation, and serialization helpers
+- **New management params** in tool schema: `action`, `chainName`, `config`
+- **Agent/chain CRUD safeguards**
+  - Name sanitization (lowercase-hyphenated) for create/rename
+  - Scope-aware uniqueness checks across agents and chains
+  - File-path collision checks to prevent overwriting non-agent markdown files
+  - Scope disambiguation for update/delete when names exist in both user and project scope
+  - Not-found errors include available names for fast self-correction
+  - Per-step validation warnings for model registry and skill availability
+  - Validate-then-mutate ordering — all validation completes before any filesystem mutations
+- **Config field mapping**: `tools` (comma-separated with `mcp:` prefix support), `reads` -> `defaultReads`, `progress` -> `defaultProgress`
+- **Uniform field clearing** — all optional string fields accept both `false` and `""` to clear
+- **JSON string parsing for `config` param** — handles `Type.Any()` delivering objects as JSON strings through the tool framework
+
+## [0.7.0] - 2026-02-09
+
+### Added
+- **Agents Manager overlay** — browse, view, edit, create, and delete agent definitions from a TUI opened via `Ctrl+Shift+A` or the `/agents` command
+  - List screen with search/filter, scope badges (user/project), chain badges
+  - Detail screen showing resolved prompt, recent runs, all frontmatter fields
+  - Edit screen with field-by-field editing, model picker, skill picker, thinking picker, full-screen prompt editor
+  - Create from templates (Blank, Scout, Planner, Implementer, Code Reviewer, Blank Chain)
+  - Delete with confirmation
+  - Launch directly from overlay with task input and skip-clarify toggle (`Tab`)
+- **Chain files** — `.chain.md` files define reusable multi-step chains with YAML-style frontmatter per step, stored alongside agent `.md` files
+  - Chain serializer with round-trip parse/serialize fidelity
+  - Three-state config semantics: `undefined` (inherit), value (override), `false` (disable)
+  - Chain detail screen with flow visualization and dependency map
+  - Chain edit screen (raw file editing)
+  - Create new chains from the template picker or save from the chain-clarify TUI (`W`)
+- **Save overrides from clarify TUI** — press `S` to persist model/output/reads/skills/progress overrides back to the agent's frontmatter file, or `W` (chain mode) to save the full chain configuration as a `.chain.md` file
+- **Multi-select and parallel from overlay** — select agents with `Tab`, then `Ctrl+R` for sequential chain or `Ctrl+P` to open the parallel builder
+  - Parallel builder: add same agent multiple times, set per-slot task overrides, shared task input
+  - Progressive footer: 0 selected (default hints), 1 selected (`[ctrl+r] run [ctrl+p] parallel`), 2+ selected (`[ctrl+r] chain [ctrl+p] parallel`)
+  - Selection count indicator in footer
+- **Slash commands with per-step tasks** — `/run`, `/chain`, and `/parallel` execute subagents with full live progress rendering and tab-completion. Results are sent to the conversation for the LLM to discuss.
+  - Per-step tasks with quotes: `/chain scout "scan code" -> planner "analyze auth"`
+  - Per-step tasks for parallel: `/parallel scanner "find bugs" -> reviewer "check style"`
+  - `--` delimiter also supported: `/chain scout -- scan code -> planner -- analyze auth`
+  - Shared task (no `->`): `/chain scout planner -- shared task`
+  - Tab completion for agent names, aware of task sections (quotes and `--`)
+  - Inline per-step config: `/chain scout[output=ctx.md] "scan code" -> planner[reads=ctx.md] "analyze auth"`
+  - Supported keys: `output`, `reads` (`+` separates files), `model`, `skills`, `progress`
+  - Works on all three commands: `/run agent[key=val]`, `/chain`, `/parallel`
+- **Run history** — per-agent JSONL recording of task, exit code, duration, timestamp
+  - Recent runs shown on agent detail screen (last 5)
+  - Lazy JSONL rotation (keeps last 1000 entries)
+- **Thinking level as first-class agent field** — `thinking` frontmatter field (off, minimal, low, medium, high, xhigh) editable in the Agents Manager
+  - Picker with arrow key navigation and level descriptions
+  - At runtime, appended as `:level` suffix to the model string
+  - Existing suffix detection prevents double-application
+  - Displayed on agent detail screen
+
+### Fixed
+- **Parallel live progress** — top-level parallel execution (`tasks: [...]`) now shows live progress for all concurrent tasks. Each task's `onUpdate` updates its slot in a shared array and emits a merged view, so the renderer can display per-task status, current tools, recent output, and timing in real time. Previously only showed results after all tasks completed.
+- **Slash commands frozen with no progress** — `/run`, `/chain`, and `/parallel` called `runSync`/`executeChain` directly, bypassing the tool framework. No `onUpdate` meant zero live progress, and `await`-ing execution blocked the command handler, making inputs unresponsive. Now all three route through `sendToolCall` → LLM → tool handler, getting full live progress rendering and responsive input for free.
+- **`/run` model override silently dropped** — `/run scout[model=gpt-4o] task` now correctly passes the model through to the tool handler. Added `model` field to the tool schema for single-agent runs.
+- **Quoted tasks with `--` inside split incorrectly** — the segment parser now checks for quoted strings before the `--` delimiter, so tasks like `scout "analyze login -- flow"` parse correctly instead of splitting on the embedded ` -- `.
+- **Chain first-step validation in per-step mode** — `/chain scout -> planner "task"` now correctly errors instead of silently assigning planner's task to scout. The first step must have its own task when using `->` syntax.
+- **Thinking level ignored in async mode** — `async-execution.ts` now applies thinking suffix to the model string before serializing to the runner, matching sync behavior
+- **Step-level model override ignored in async mode** — `executeAsyncChain` now uses `step.model ?? agent.model` as the base for thinking suffix, matching the sync path in `chain-execution.ts`
+- **mcpDirectTools not set in async mode** — `subagent-runner.ts` now sets `MCP_DIRECT_TOOLS` env var per step, matching the sync path in `execution.ts`
+- **`{task}` double-corruption in saved chain launches** — stopped pre-replacing `{task}` in the overlay launch path; raw user task passed as top-level param to `executeChain()`, which uses `params.task` for `originalTask`
+- **Agent serializer `skill` normalization** — `normalizedField` now maps `"skill"` to `"skills"` on the write path
+- **Clarify toggle determinism** — all four ManagerResult paths (single, chain, saved chain, parallel) now use deterministic JSON with `clarify: !result.skipClarify`, eliminating silent breakage from natural language variants
+
+### Changed
+- Agents Manager single-agent and saved-chain launches default to quick run (skip clarify TUI) — the user already reviewed config in the overlay. Multi-agent ad-hoc chains default to showing the clarify TUI so users can configure per-step tasks, models, output files, and skills before execution. Toggle with `Tab` in the task-input screen.
+- Extracted `applyThinkingSuffix(model, thinking)` helper from inline logic in `execution.ts`, shared with `async-execution.ts`
+- Text editor: added word navigation (Alt+Left/Right, Ctrl+Left/Right), word delete (Alt+Backspace), paste support
+- Agent discovery (`agents.ts`): loads `.chain.md` files via `loadChainsFromDir`, exposes `discoverAgentsAll` for overlay
+
 ## [0.6.0] - 2026-02-02
 
 ### Added

package/README.md

@@ -39,8 +39,9 @@ Use `agentScope` parameter to control discovery: `"user"` (default), `"project"`
 ---
 name: scout
 description: Fast codebase recon
-tools: read, grep, find, ls, bash, mcp:chrome-devtools
+tools: read, grep, find, ls, bash, mcp:chrome-devtools  # mcp: requires pi-mcp-adapter
 model: claude-haiku-4-5
+thinking: high               # off, minimal, low, medium, high, xhigh
 skill: safe-bash, chrome-devtools  # comma-separated skills to inject
 output: context.md           # writes to {chain_dir}/context.md
 defaultReads: context.md     # comma-separated files to read
@@ -51,6 +52,8 @@ interactive: true            # (parsed but not enforced in v1)
 Your system prompt goes here (the markdown body after frontmatter).
 ```
 
+The `thinking` field sets a default extended thinking level for the agent. At runtime it's appended as a `:level` suffix to the model string (e.g., `claude-sonnet-4-5:high`). If the model already has a thinking suffix (from a chain-clarify override), the agent's default is not double-applied.
+
 **MCP Tools**
 
 Agents can use MCP server tools directly (requires the [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) extension). Add `mcp:` prefixed entries to the `tools` field:
@@ -76,8 +79,151 @@ The MCP adapter's metadata cache must be populated for direct tools to work. On
 
 **Resolution priority:** step override > agent frontmatter > disabled
 
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `/run <agent> <task>` | Run a single agent with a task |
+| `/chain agent1 "task1" -> agent2 "task2"` | Run agents in sequence with per-step tasks |
+| `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel with per-step tasks |
+| `/agents` | Open the Agents Manager overlay |
+
+All commands validate agent names locally and tab-complete them, then route through the tool framework for full live progress rendering. Results are sent to the conversation for the LLM to discuss.
+
+### Per-Step Tasks
+
+Use `->` to separate steps and give each step its own task with quotes or `--`:
+
+```
+/chain scout "scan the codebase" -> planner "create implementation plan"
+/parallel scanner "find security issues" -> reviewer "check code style"
+```
+
+Both double and single quotes work. The `--` delimiter also works: `/chain scout -- scan code -> planner -- analyze auth`.
+
+Steps without a task inherit behavior from the execution mode: chain steps get `{previous}` (output from the prior step), parallel steps get the first available task as a fallback.
+
+```
+/chain scout "analyze auth" -> planner -> implementer
+# scout: "analyze auth", planner: gets scout's output, implementer: gets planner's output
+```
+
+**Shared task (no `->`):** Space-separated agents with a single `--` task:
+
+```
+/chain scout planner -- analyze the auth system
+/parallel scout reviewer -- check for security issues
+```
+
+### Inline Per-Step Config
+
+Append `[key=value,...]` to any agent name to override its defaults:
+
+```
+/chain scout[output=context.md] "scan code" -> planner[reads=context.md] "analyze auth"
+/run scout[model=anthropic/claude-sonnet-4] summarize this codebase
+/parallel scanner[output=scan.md] "find issues" -> reviewer[output=review.md] "check style"
+```
+
+| Key | Example | Description |
+|-----|---------|-------------|
+| `output` | `output=context.md` | Write results to file (relative to chain dir for `/chain`/`/parallel`, temp dir for `/run`) |
+| `reads` | `reads=a.md+b.md` | Read files before executing (`+` separates multiple) |
+| `model` | `model=anthropic/claude-sonnet-4` | Override model for this step |
+| `skills` | `skills=planning+review` | Override skills (`+` separates multiple) |
+| `progress` | `progress` | Enable progress tracking |
+
+Set `output=false`, `reads=false`, or `skills=false` to explicitly disable.
+
+## Agents Manager
+
+Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay — a TUI for browsing, viewing, editing, creating, and launching agents and chains.
+
+**Screens:**
+
+| Screen | Description |
+|--------|-------------|
+| List | Browse all agents and chains with search/filter, scope badges, chain badges |
+| Detail | View resolved prompt, frontmatter fields, recent run history |
+| Edit | Edit fields with specialized pickers (model, thinking, skills, prompt editor) |
+| Chain Detail | View chain steps with flow visualization and dependency map |
+| Parallel Builder | Build parallel execution slots, add same agent multiple times, per-slot task overrides |
+| Task Input | Enter task and launch with optional skip-clarify toggle |
+| New Agent | Create from templates (Blank, Scout, Planner, Implementer, Code Reviewer, Blank Chain) |
+
+**List screen keybindings:**
+- `↑↓` — navigate agents/chains
+- `Enter` — view detail
+- Type any character — search/filter
+- `Tab` — toggle selection (agents only)
+- `Ctrl+N` — new agent from template
+- `Ctrl+K` — clone current item
+- `Ctrl+D` or `Del` — delete current item
+- `Ctrl+R` — run selected (1 agent: launch, 2+: sequential chain)
+- `Ctrl+P` — open parallel builder (from selection or cursor agent)
+- `Esc` — clear query, then selection, then close overlay
+
+**Parallel builder keybindings:**
+- `↑↓` — navigate slots
+- `Ctrl+A` — add agent (opens search picker)
+- `Del` or `Ctrl+D` — remove slot
+- `Enter` — edit per-slot task override
+- `Ctrl+R` — continue to task input (requires 2+ slots)
+- `Esc` — back to list
+
+**Task input keybindings:**
+- `Enter` — launch (or quick run if skip-clarify is on)
+- `Tab` — toggle skip-clarify (defaults to on for all manager launches)
+- `Esc` — back
+
+**Multi-select workflow:** Select agents with `Tab`, then press `Ctrl+R` for a sequential chain or `Ctrl+P` to open the parallel builder. The parallel builder lets you add the same agent multiple times, set per-slot task overrides, and launch N agents in parallel. Slots without a custom task use the shared task entered on the next screen.
+
+## Chain Files
+
+Chains are `.chain.md` files stored alongside agent files. They define reusable multi-step pipelines.
+
+**Chain file locations:**
+
+| Scope | Path |
+|-------|------|
+| User | `~/.pi/agent/agents/{name}.chain.md` |
+| Project | `.pi/agents/{name}.chain.md` |
+
+**Format:**
+
+```markdown
+---
+name: scout-planner
+description: Gather context then plan implementation
+---
+
+## scout
+output: context.md
+
+Analyze the codebase for {task}
+
+## planner
+reads: context.md
+model: anthropic/claude-sonnet-4-5:high
+progress: true
+
+Create an implementation plan based on {previous}
+```
+
+Each `## agent-name` section defines a step. Config lines (`output`, `reads`, `model`, `skills`, `progress`) go immediately after the header. A blank line separates config from the task text. Chains support the same three-state semantics as tool params: omitted (inherit from agent), value (override), `false` (disable).
+
+Chains can be created from the Agents Manager template picker ("Blank Chain"), or saved from the chain-clarify TUI during execution.
+
 ## Features (beyond base)
 
+- **Slash Commands**: `/run`, `/chain`, `/parallel` with tab-completion and live progress
+- **Agents Manager Overlay**: Browse, view, edit, create, delete, and launch agents/chains from a TUI (`Ctrl+Shift+A`)
+- **Management Actions**: LLM can list, inspect, create, update, and delete agent/chain definitions via `action` field
+- **Chain Files**: Reusable `.chain.md` files with per-step config, saveable from the clarify TUI
+- **Multi-select & Parallel**: Select agents in the overlay, launch as chain or parallel
+- **Run History**: Per-agent JSONL recording of task, exit code, duration; shown on detail screen
+- **Thinking Level**: First-class `thinking` frontmatter field with picker UI and runtime suffix application
+- **Agent Templates**: Create agents from presets (Scout, Planner, Implementer, Code Reviewer, Blank Chain)
 - **Skill Injection**: Agents declare skills in frontmatter; skills get injected into system prompts
 - **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
@@ -127,6 +273,8 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 - `w` - Edit writes/output file (single, chain only)
 - `r` - Edit reads list (chain only)
 - `p` - Toggle progress tracking (chain only)
+- `S` - Save current overrides to agent's frontmatter file (all modes)
+- `W` - Save chain configuration to a `.chain.md` file (chain only)
 
 *Model selector mode:*
 - `↑↓` - Navigate model list
@@ -150,10 +298,13 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 - `Esc` - Save changes and exit
 - `Ctrl+C` - Discard changes and exit
 - `←→` - Move cursor left/right
+- `Alt+←→` - Move cursor by word
 - `↑↓` - Move cursor up/down by display line (auto-scrolls)
 - `Page Up/Down` or `Shift+↑↓` - Move cursor by viewport (12 lines)
 - `Home/End` - Start/end of current display line
 - `Ctrl+Home/End` - Start/end of text
+- `Alt+Backspace` - Delete word backward
+- Paste supported (multi-line in multi-line editors)
 
 ## Skills
 
@@ -249,14 +400,78 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 { dir: "/tmp/pi-async-subagent-runs/a53ebe46-..." }
 ```
 
+## Management Actions
+
+Agent definitions are not loaded into LLM context by default. Management actions let the LLM discover, inspect, create, and modify agent and chain definitions at runtime through the `subagent` tool — no manual file editing or restart required. Newly created agents are immediately usable in the same session. Set `action` and omit execution payloads (`task`, `chain`, `tasks`).
+
+```typescript
+// Discover all agents and chains (management defaults to both scopes)
+{ action: "list" }
+{ action: "list", agentScope: "project" }
+
+// Inspect one agent or chain (searches both scopes)
+{ action: "get", agent: "scout" }
+{ action: "get", chainName: "review-pipeline" }
+
+// Create agent
+{ action: "create", config: {
+  name: "Code Scout",
+  description: "Scans codebases for patterns and issues",
+  scope: "user",
+  systemPrompt: "You are a code scout...",
+  model: "anthropic/claude-sonnet-4",
+  tools: "read, bash, mcp:github/search_repositories",
+  skills: "parallel-scout",
+  thinking: "high",
+  output: "context.md",
+  reads: "shared-context.md",
+  progress: true
+}}
+
+// Create chain (presence of steps creates .chain.md)
+{ action: "create", config: {
+  name: "review-pipeline",
+  description: "Scout then review",
+  scope: "project",
+  steps: [
+    { agent: "scout", task: "Scan {task}", output: "context.md" },
+    { agent: "reviewer", task: "Review {previous}", reads: ["context.md"] }
+  ]
+}}
+
+// Update agent fields (merge semantics)
+{ action: "update", agent: "scout", config: { model: "openai/gpt-4o" } }
+{ action: "update", agent: "scout", config: { output: false, skills: "" } } // clear optional fields
+{ action: "update", chainName: "review-pipeline", config: {
+  steps: [
+    { agent: "scout", task: "Scan {task}", output: "context.md" },
+    { agent: "reviewer", task: "Improved review of {previous}", reads: ["context.md"] }
+  ]
+}}
+
+// Delete definitions
+{ action: "delete", agent: "scout" }
+{ action: "delete", chainName: "review-pipeline" }
+```
+
+Notes:
+- `create` uses `config.scope` (`"user"` or `"project"`), not `agentScope`.
+- `update`/`delete` use `agentScope` only for scope disambiguation when the same name exists in both scopes.
+- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, and `tools` supports `mcp:` entries that map to direct MCP tools.
+- To clear any optional field, set it to `false` or `""` (e.g., `{ model: false }` or `{ skills: "" }`). Both work for all string-typed fields.
+
 ## Parameters
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agent` | string | - | Agent name (single mode) |
+| `agent` | string | - | Agent name (single mode) or target for management get/update/delete |
 | `task` | string | - | Task string (single mode) |
+| `action` | string | - | Management action: `list`, `get`, `create`, `update`, `delete` |
+| `chainName` | string | - | Chain name for management get/update/delete |
+| `config` | object | - | Agent or chain config for management create/update |
 | `output` | `string \| false` | agent default | Override output file for single agent |
 | `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
+| `model` | string | agent default | Override model for single agent |
 | `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
@@ -282,6 +497,7 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 | `reads` | `string[] \| false` | agent default | Override files to read from chain dir |
 | `progress` | boolean | agent default | Override progress.md tracking |
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
+| `model` | string | agent default | Override model for this step |
 
 *Parallel step fields:*
 
@@ -302,6 +518,7 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 | `reads` | `string[] \| false` | agent default | Override files to read |
 | `progress` | boolean | agent default | Override progress tracking |
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
+| `model` | string | agent default | Override model for this task |
 
 Status tool:
 
@@ -360,16 +577,22 @@ Session files (JSONL) are stored under a per-run session dir (temp by default).
 
 ## Live progress (sync mode)
 
-During sync execution, the collapsed view shows:
+During sync execution, the collapsed view shows real-time progress for single, chain, and parallel modes.
+
+**Chains:**
 - Header: `... chain 1/2 | 8 tools, 1.4k tok, 38s`
 - Chain visualization with status: `✓scout → ●planner` (✓=done, ●=running, ○=pending, ✗=failed)
 - Current tool: `> read: packages/tui/src/...`
 - Recent output lines (last 2-3 lines)
-- Hint: `(ctrl+o to expand)`
+
+**Parallel:**
+- Header: `... parallel 2/4 | 12 tools, 2.1k tok, 15s`
+- Per-task step cards showing status icon, agent name, model, tool count, and duration
+- Current tool and recent output for each running task
 
 Press **Ctrl+O** to expand the full streaming view with complete output per step.
 
-> **Note:** Chain visualization is only shown for sequential chains. Chains with parallel steps show the header and progress but not the step-by-step visualization.
+> **Note:** Chain visualization (the `✓scout → ●planner` line) is only shown for sequential chains. Chains with parallel steps show per-step cards instead.
 
 ## Async observability
 
@@ -403,20 +626,33 @@ Legacy events (still emitted):
 ## Files
 
 ```
-├── index.ts           # Main extension (registerTool)
-├── agents.ts          # Agent discovery + frontmatter parsing
-├── skills.ts          # Skill resolution, caching, and discovery
-├── settings.ts        # Chain behavior resolution, templates, chain dir
-├── chain-clarify.ts   # TUI component for chain clarification
-├── chain-execution.ts # Chain orchestration (sequential + parallel)
-├── async-execution.ts # Async/background execution support
-├── execution.ts       # Core runSync for single agent execution
-├── render.ts          # TUI rendering (widget, tool result display)
-├── artifacts.ts       # Artifact management
-├── formatters.ts      # Output formatting utilities
-├── schemas.ts         # TypeBox parameter schemas
-├── utils.ts           # Shared utility functions
-├── types.ts           # Shared types
-├── subagent-runner.ts # Async runner
-└── notify.ts          # Async completion notifications
+├── index.ts                      # Main extension, tool registration, overlay dispatch
+├── agents.ts                     # Agent + chain discovery, frontmatter parsing
+├── skills.ts                     # Skill resolution, caching, and discovery
+├── settings.ts                   # Chain behavior resolution, templates, chain dir
+├── chain-clarify.ts              # TUI for chain/single/parallel clarification
+├── chain-execution.ts            # Chain orchestration (sequential + parallel)
+├── chain-serializer.ts           # Parse/serialize .chain.md files
+├── async-execution.ts            # Async/background execution support
+├── execution.ts                  # Core runSync, applyThinkingSuffix
+├── render.ts                     # TUI rendering (widget, tool result display)
+├── artifacts.ts                  # Artifact management
+├── formatters.ts                 # Output formatting utilities
+├── schemas.ts                    # TypeBox parameter schemas
+├── utils.ts                      # Shared utility functions
+├── types.ts                      # Shared types and constants
+├── subagent-runner.ts            # Async runner (detached process)
+├── notify.ts                     # Async completion notifications
+├── agent-manager.ts              # Overlay orchestrator, screen routing, CRUD
+├── agent-manager-list.ts         # List screen (search, multi-select, progressive footer)
+├── agent-manager-detail.ts       # Detail screen (resolved prompt, runs, fields)
+├── agent-manager-edit.ts         # Edit screen (pickers, prompt editor)
+├── agent-manager-parallel.ts     # Parallel builder screen (slot management, agent picker)
+├── agent-manager-chain-detail.ts # Chain detail screen (flow visualization)
+├── agent-management.ts           # Management action handlers (list, get, create, update, delete)
+├── agent-serializer.ts           # Serialize agents to markdown frontmatter
+├── agent-templates.ts            # Agent/chain creation templates
+├── render-helpers.ts             # Shared pad/row/header/footer helpers
+├── run-history.ts                # Per-agent run recording (JSONL)
+└── text-editor.ts                # Shared text editor (word nav, paste)
 ```