@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/skill-registry/src/vault.ts

@@ -0,0 +1,80 @@
+/**
+ * @pi-unipi/skill-registry — the skill vault
+ *
+ * `~/.unipi/skill-vault/` holds skills the user keeps but does not want
+ * everywhere. With the proxy on, pi discovers the vault (resources_discover)
+ * and the registry keeps vault skills OFF until a scope turns them on.
+ * Layout: any directory containing SKILL.md, up to three levels deep
+ * (`vault/<skill>/SKILL.md` or `vault/<pack>/<skill>/SKILL.md`).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function vaultDir(): string {
+  return process.env.UNIPI_SKILL_VAULT || join(homedir(), ".unipi", "skill-vault");
+}
+
+export interface VaultSkill {
+  name: string;
+  description: string;
+  filePath: string;
+  baseDir: string;
+}
+
+/** Minimal frontmatter reader: `name:` and `description:` (plain, `>`, `|`). */
+export function parseFrontmatter(text: string): { name?: string; description?: string } {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const lines = match[1]!.split(/\r?\n/);
+  const out: { name?: string; description?: string } = {};
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i]!.match(/^(name|description):\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1] as "name" | "description";
+    let value = m[2]!.trim();
+    if (/^[>|][+-]?$/.test(value)) {
+      const block: string[] = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]!) || lines[i + 1] === "")) block.push(lines[++i]!.trim());
+      value = block.join(" ").trim();
+    }
+    out[key] = value.replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+export function listVaultSkills(dir: string = vaultDir()): VaultSkill[] {
+  const out: VaultSkill[] = [];
+  const walk = (d: string, depth: number) => {
+    if (depth > 3 || !existsSync(d)) return;
+    let names: string[];
+    try {
+      names = readdirSync(d);
+    } catch {
+      return;
+    }
+    if (names.includes("SKILL.md") && d !== dir) {
+      const filePath = join(d, "SKILL.md");
+      try {
+        const fm = parseFrontmatter(readFileSync(filePath, "utf-8"));
+        const name = fm.name || d.split("/").pop()!;
+        if (fm.description) out.push({ name, description: fm.description, filePath, baseDir: d });
+      } catch {
+        // unreadable skill — skip
+      }
+      return;
+    }
+    for (const n of names) {
+      if (n.startsWith(".")) continue;
+      const p = join(d, n);
+      try {
+        if (statSync(p).isDirectory()) walk(p, depth + 1);
+      } catch {
+        // skip
+      }
+    }
+  };
+  walk(dir, 0);
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}

package/packages/subagents/README.md

@@ -1,121 +1,41 @@
 # @pi-unipi/subagents
 
-Delegate work to focused child agents — in parallel, in the background, or as scripted multi-agent workflows. Feature parity with [pi-subagents](https://github.com/nicobailon/pi-subagents), built on unipi conventions: foreground children run in-process (live widget streaming), background/fork/resume/worktree runs use child `pi` processes.
-
-## Agents
-
-Built-in agents (lowest discovery priority — user/project definitions override):
-
-| Agent | Use it for |
-|-------|------------|
-| `explore` | Read-only file research and parallel reads |
-| `work` | File modifications with transparent locking |
-| `scout` | Fast codebase recon: entry points, data flow, risks |
-| `researcher` | Web research with sources (`web_search`, `multi_web_content_read`) |
-| `worker` | Implementation: narrow edits, validation, escalation |
-| `reviewer` | Code review of diffs, plans, solutions |
-| `oracle` | Second opinion; challenges assumptions without editing |
-| `delegate` | Lightweight general delegate close to the parent session |
-
-Custom agents are markdown files with YAML frontmatter:
-
-```markdown
----
-name: security-reviewer
-description: Security-focused review
-tools: read, grep, find
-thinking: high
-memory: { scope: "project", path: "security-reviewer" }
----
-
-Review changes for unsafe input handling...
-```
-
-Discovery: project `.unipi/config/agents/` > global `~/.unipi/config/agents/` > builtins. Aliases resolve (`developer` → `worker`, `advisor` → `oracle`). Per-agent overrides live in `subagents.json`.
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `spawn_helper` | Launch agents: single child, `workflowScript` orchestration, or management `action`s |
-| `get_helper_result` | Wait on / inspect background runs; `nonBlocking` wake subscriptions |
-
-### Single child
-
-```
-spawn_helper({ agent: "scout", task: "Analyze the auth flow" })
-spawn_helper({ agent: "worker", task: "Implement it", run_in_background: true })
-spawn_helper({ agent: "reviewer", task: "Review", gate: "npm test" })
-```
-
-Legacy aliases (`type`, `prompt`, `max_turns`) still work.
-
-### Scripted workflows
-
-```js
-spawn_helper({ workflowScript: `
-  const scan = await runs.run("scan", { agent: "scout", task: "Analyze auth" });
-  const reviews = await runs.all([
-    { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
-    { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
-  ]);
-  return reviews.map(r => r.output);
-`, async: false })
-```
-
-`runs.run` / `runs.all` / `runs.steer` inside a sandboxed VM. Budgets (`turnBudget`, `toolBudget`, `usageBudget`), worktree isolation, fork context, and acceptance gates available per child.
-
-### Management actions
-
-```
-spawn_helper({ action: "list" | "get" | "status" | "children.list" })
-spawn_helper({ action: "resume", id: "<run>", message: "Reconsider X" })
-spawn_helper({ action: "doctor" | "guide", topic: "workflows" })
-spawn_helper({ action: "mission.create", mission: { title, objective } })
-spawn_helper({ action: "schedule.create", name, agent, task, every: "30m" })
-```
-
-## Observability
-
-- **FleetView** panel: active work from both transports. `↓` to inspect, `j/k` navigate, `enter` opens transcripts, `esc` closes.
-- **`/unipi:subagents-fleet`** · **`/unipi:subagents-doctor`** · **`/unipi:subagents-guide [topic]`**
-- Background completions arrive as `<task-notification>` follow-ups automatically.
-- Supervisor channel: blocked children can `contact_supervisor` for decisions.
-
-## Configuration
-
-`~/.unipi/config/subagents.json` (global) + `<workspace>/.unipi/config/subagents.json`:
-
-```json
-{
-  "subagents": {
-    "defaultModel": "ds/deepseek-v4-flash",
-    "asyncByDefault": true,
-    "maxSubagentSpawnsPerRun": 64,
-    "fleetViewPlacement": "belowEditor"
-  }
-}
-```
-
-Full key reference: `spawn_helper({ action: "guide", topic: "configuration" })`. Env overrides use the `UNIPI_SUBAGENT_*` prefix.
-
-## Storage
-
-| Path | Contents |
-|------|----------|
-| `~/.unipi/missions/<project-hash>/` | Durable mission records |
-| `~/.unipi/schedules/<project-hash>/` | Scheduled runs |
-| `~/.unipi/agent-memory/` | Per-agent persistent memory |
-| temp root (`unipi-subagents-*`) | Run artifacts, results, channels (auto-cleaned) |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/unipi:subagents-fleet` | Show active fleet |
-| `/unipi:subagents-doctor` | Config + capacity diagnosis |
-| `/unipi:subagents-guide [topic]` | Bundled guide |
-
-## Prompt shortcuts
-
-`/council`, `/parallel-review`, `/review-loop`, `/parallel-research`, `/gather-context-and-clarify`, `/parallel-cleanup` — packaged prompt templates for common orchestration patterns.
+Devin-model subagents for pi: the lead delegates self-contained work to independent child
+agents (`pi --mode rpc`) that run alongside it.
+
+- `run_subagent` — foreground (wait + report) or background (`<subagent_completion_notification>`
+  followUp, exactly once). Approval prompts reach the user only while a foreground waiter is
+  attached; background subagents are denied with a reason ("running in the background… don't
+  retry"). `resume:<agent_id>` continues an earlier agent in its session file.
+- `read_subagent` — shared tool (core registry): reads subagents AND Fusion sidekick handoffs.
+- Profiles: `subagent_explore` (read-only allowlist + cheap default model),
+  `subagent_general` (all tools minus nesting, parent's model), and custom markdown agents from
+  `~/.unipi/config/agents/` + `<workspace>/.unipi/config/agents/` (project wins).
+- Nesting: children spawn only below `UNIPI_SUBAGENT_MAX_DEPTH` (default 1 = no nesting).
+
+## Screen
+
+| Where | What |
+|---|---|
+| Chat | `● Explore subagent <title>` card — live tail + `└ General · ds/deepseek-flash · 32s · 20 tool calls · 10k in · 0.2k out · $0.11 · ctrl+b background · esc cancel` while it runs, then `└ Completed · 32s · 20 tool calls · 10k in · 0.2k out · $0.11` (ctrl+o shows the report). The stats line ticks live — profile, model, tool-call count, duration, tokens and cost (cost is omitted when the model's pricing is unknown). Background finishes: `● Subagent "<title>" completed └ …`. |
+| Below the input | `N subagents (k running) · ↓ select` plus one stat line per running agent, ticking each second — stays for the session, survives restart + resume. |
+| Dock (↓ from an empty input, or `/unipi:subagents`) | `↑↓` navigate · `↵` view the live transcript · `f` foreground · `x` cancel · `esc` close. |
+| Transcript view | task, tool calls with output, text; `↑↓`/PgUp/PgDn scroll, `g`/`G` top/end, `o` full tool output. |
+| Foreground | Spinner reads `Subagent running · Ctrl+B to run in background`. **Ctrl+B** sends every foreground subagent to the background; **Esc** cancels a foreground run. `f` on a background agent shows its live steps above the input and routes its approvals to you. |
+
+States: running `◐`, completed `✓`, failed `✗`, cancelled `⊘` (its own state — "cancelled by you"
+when you pressed Esc or `x`).
+
+## Config
+
+`/unipi:settings → Subagents`: enabled, default subagent model (picker; empty = Fusion sidekick →
+your model), default thinking, max running at once, **Manage agents…**. Settings and agent files
+are re-read every turn — no restart.
+
+`/unipi:agents` — list profiles; create a custom agent step by step (name → this project / all
+projects → description → model → tools → prompt); edit, copy between global/project, or delete.
+Files use the Devin/Claude format (`name`, `description`, `model`, `allowed-tools`|`tools`,
+`thinking`, `max-nesting`; body = system prompt).
+
+State: `~/.unipi/workspace/<id>/state/subagents/sessions/<lead-session-id>/` (`index.json` + one
+`<agent_id>.jsonl` child session per agent).

package/packages/subagents/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/subagents",
-  "version": "3.0.0-alpha.2",
-  "description": "Subagents for UniPi — parallel execution, file locking, workflow integration",
+  "version": "3.0.0-alpha.21",
+  "description": "Subagents for UniPi — Devin-model independent child agents",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,7 +9,8 @@
     "test": "npx tsx --test src/__tests__/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2",
+    "@pi-unipi/core": "3.0.0-alpha.21",
+    "@pi-unipi/utility": "3.0.0-alpha.21",
     "@earendil-works/pi-agent-core": "^0.87.1",
     "acorn": "8.18.0"
   },
@@ -24,22 +25,14 @@
   "files": [
     "src/**/*.ts",
     "!src/__tests__/**",
-    "src/global.d.ts",
-    "agents/*.md",
-    "prompts/*.md",
-    "skills/**/*",
     "README.md"
   ],
   "pi": {
     "extensions": [
       "./src/index.ts"
     ],
-    "skills": [
-      "./skills"
-    ],
-    "prompts": [
-      "./prompts"
-    ],
+    "skills": [],
+    "prompts": [],
     "themes": []
   }
 }

package/packages/subagents/skills/subagents/SKILL.md

@@ -1,49 +1,25 @@
 ---
-name: unipi-subagents
-description: |
-  Delegate work to builtin or custom subagents with single-agent, parallel,
-  scripted-chaining, async, forked-context, and coordinated workflows. Use
-  for advisory review, implementation handoffs, and multi-step tasks where a
-  single agent should stay in control while other agents contribute context,
-  planning, or execution.
+name: subagents
+description: Delegating work to independent subagents (run_subagent/read_subagent).
 ---
 
-# Pi Subagents
+# Subagents
 
-This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
+The model drives delegation through tools. For the user: `/unipi:subagents` (or ↓ from an empty
+input) opens the subagent panel; `/unipi:agents` manages custom agents; Ctrl+B moves a foreground
+subagent to the background.
 
-Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child. Chaining is still supported, but it is code-driven: use `await runs.run(...)` for sequential steps, `runs.all([...])` for parallel fanout, and ordinary JavaScript for branching, retries, gate monitors, and aggregation. Keep workflow helpers portable: use plain helper functions or explicit Promise chains, not nested `async function` helpers, async arrows, or async methods. Do not use legacy top-level `chain` / `tasks` inputs or durable `.chain.md` execution. Scripted workflows normally start asynchronously unless config sets `asyncByDefault:false`; set `async:true` explicitly when async behavior matters. Pass `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` for final reviews, backlog gates, run-to-completion convenience, or because no other work is available.
+- `run_subagent({title, task, profile, is_background?, resume?})` launches an independent agent
+  with its own context. It does not see this conversation — put everything it needs in `task`.
+- `read_subagent({agent_id?, block?, timeout?})` reads/waits on a subagent (or a Fusion
+  sidekick handoff) by id.
 
-Package-installed agents appear in `spawn_helper({ action: "list" })` with builtin, user, and project agents. If `surf-cli` is installed as a Pi package, the Surf browser extension is loaded, and Chrome is logged into a ChatGPT Pro account, Surf can expose `gpt-pro`: a read-only async advisor that reaches ChatGPT web through Surf Oracle. Check it with `spawn_helper({ action: "get", agent: "gpt-pro" })` and run it with `subagent({ agent: "gpt-pro", task: "Review this plan and identify release risks." })`.
+Profiles:
+- `subagent_explore` — read-only (read/grep/find/ls/web_search/memory_search/memory_list), cheaper default model.
+- `subagent_general` — all tools except nesting tools, runs on your model.
+- Custom `.md` agents under `~/.unipi/config/agents/` (global) or
+  `<workspace>/.unipi/config/agents/` (project), YAML frontmatter:
+  `name, description, model, tools|allowed-tools, thinking, max-nesting`; body = system prompt.
 
-## How to use this router
-
-Read the matching reference file before acting. Paths are relative to this `SKILL.md`; resolve them against `skills/subagents/` and load them with the read tool.
-
-| Task | Read |
-| --- | --- |
-| Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
-| Use council mode, convene several advisors, debate a decision, cross-examine recommendations, critique or improve a plan with multiple model perspectives, or run `/council` | `../council-mode/SKILL.md` |
-| Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
-| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
-| List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
-| Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
-
-For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
-
-## Always-on constraints
-
-- Keep the parent as orchestrator and final decision-maker.
-- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
-- For plan, design, or architecture advice that asks for council mode, asks to convene several advisors, compare model perspectives, debate a decision, cross-examine recommendations, or critique and improve a plan, read `../council-mode/SKILL.md` and use Council Mode instead of ad hoc parallel oracle calls.
-- For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with one `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
-- Use one writer per cwd/worktree unless isolated worktrees are intentional.
-- For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.
-- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` with stable keys and aggregate output unless there is truly only one child.
-- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- Use async/background by default. Final reviews, gate checks, oracle checks, and backlog lanes stay async. Use `async:false` only when the parent must block until completion. Do not poll just to wait. For adaptive gates, branch in `workflowScript`.
-- For Pi extension repos whose canonical checkout is under `~/.pi/agent/extensions`, never create lane worktrees as sibling directories there. Pi auto-loads `~/.pi/agent/extensions/*/index.ts`, so sibling worktrees can register duplicate tools. Put lanes under `~/.pi/agent/worktrees`, another worktree base outside auto-discovery, or a temporary clone. If a lane must run the modified extension itself, use an isolated Pi config home with `PI_CODING_AGENT_DIR=<lane-config> pi --no-extensions -e <lane>/index.ts`. Use full containers only when path and config isolation are insufficient.
-- Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
-- Escalate unresolved product, architecture, authority, release, merge, or safety decisions upward instead of letting a child decide silently.
-- Treat receipts, CI, review bots, and external-run records as evidence, not authority to merge, close, comment, publish, or release.
-- As a conservative orchestration policy, do not pass `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model. If a worker is interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+Rules: parallelize independent work; foreground waits for the report; background can't ask
+for approval (auto-denied); resume a finished/failed/cancelled agent with `resume:<agent_id>`.

package/packages/subagents/src/agents.ts

@@ -0,0 +1,213 @@
+/**
+ * @pi-unipi/subagents — `/unipi:agents`: manage custom agents without
+ * hand-writing frontmatter. List built-ins + customs, create one step by step
+ * (name → scope → description → model → tools → prompt), edit the file in
+ * pi's editor, copy between global and project, delete.
+ *
+ * Files: ~/.unipi/config/agents/<name>.md (global) and
+ * <workspace>/.unipi/config/agents/<name>.md (project, wins).
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { getSharedFusionStatus, registerCommandRunner } from "@pi-unipi/core";
+import { EXPLORE_TOOLS, builtinProfiles, loadProfiles, type AgentProfile } from "./profiles.js";
+import { resolveModel } from "./model-resolver.js";
+
+export const AGENTS_COMMAND = "unipi:agents";
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+const NEW_LABEL = "＋ New agent…";
+
+export function agentsDir(scope: "global" | "project", cwd: string, home = homedir()): string {
+  return join(scope === "global" ? home : cwd, ".unipi", "config", "agents");
+}
+
+/** Where a custom profile's file lives (flat file or directory layout). */
+export function agentFile(profile: Pick<AgentProfile, "id" | "source">, cwd: string, home = homedir()): string | undefined {
+  if (profile.source === "builtin") return undefined;
+  const dir = agentsDir(profile.source, cwd, home);
+  for (const candidate of [join(dir, `${profile.id}.md`), ...["AGENT.md", "AGENTS.md", "agent.md", "agents.md"].map((f) => join(dir, profile.id, f))]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+export interface AgentDraft {
+  name: string;
+  description: string;
+  model?: string;
+  tools?: string[];
+  thinking?: string;
+  prompt: string;
+}
+
+/** Render a draft as the Devin/Claude-compatible markdown file. */
+export function agentMarkdown(d: AgentDraft): string {
+  const fm = [`name: ${d.name}`, `description: ${JSON.stringify(d.description)}`];
+  if (d.model) fm.push(`model: ${d.model}`);
+  if (d.thinking) fm.push(`thinking: ${d.thinking}`);
+  if (d.tools && d.tools.length > 0) fm.push("allowed-tools:", ...d.tools.map((t) => `  - ${t}`));
+  return `---\n${fm.join("\n")}\n---\n\n${d.prompt.trim()}\n`;
+}
+
+export function validateName(name: string, existing: readonly string[]): string | null {
+  if (!NAME_RE.test(name)) return "Use lowercase letters, digits, - or _ (max 48).";
+  if (builtinProfiles().some((b) => b.id === name)) return `${name} is a built-in profile name.`;
+  if (existing.includes(name)) return `An agent named ${name} already exists.`;
+  return null;
+}
+
+function promptTemplate(name: string, description: string): string {
+  return `You are the ${name} subagent: ${description}\n\nWork only on the task you are given. You do not see the parent conversation; everything you need is in the task.\n\nFinish with a concise report for the parent agent: what you found or did, with file paths and line numbers, and anything you could not determine.`;
+}
+
+function describe(p: AgentProfile): string {
+  const tools = p.tools === undefined ? "all tools" : p.tools.length <= 4 ? p.tools.join(", ") : `${String(p.tools.length)} tools`;
+  const model = p.model ?? (p.id === "subagent_general" ? "your model" : "default subagent model");
+  return `${p.id} · ${p.source} · ${model} · ${tools} — ${p.description}`;
+}
+
+type UI = ExtensionContext["ui"];
+
+/** Short list + "Other…" with a fuzzy name match (hundreds of models don't
+ *  fit a plain select). undefined = default subagent model; null = cancelled. */
+async function pickModel(ui: UI, ctx: ExtensionContext): Promise<string | undefined | null> {
+  const DEFAULT = "Default subagent model (recommended)";
+  const OTHER = "Other… (type a name — fuzzy match)";
+  const cur = ctx.model as { provider?: string; id?: string } | undefined;
+  const choices = new Map<string, string>();
+  if (cur?.provider && cur.id) choices.set(`Your current model — ${cur.provider}/${cur.id}`, `${cur.provider}/${cur.id}`);
+  const sidekick = getSharedFusionStatus()?.sidekickKey;
+  if (sidekick) choices.set(`Fusion sidekick — ${sidekick}`, sidekick);
+  const choice = await ui.select("Model", [DEFAULT, ...choices.keys(), OTHER]);
+  if (choice === undefined) return null;
+  if (choice === DEFAULT) return undefined;
+  if (choice !== OTHER) return choices.get(choice);
+  while (true) {
+    const raw = (await ui.input("Model name (e.g. deepseek-flash, sonnet, openrouter/…)", ""))?.trim();
+    if (!raw) return null;
+    const found = ctx.modelRegistry ? resolveModel(raw, ctx.modelRegistry as never) : raw;
+    if (typeof found !== "string") return `${found.provider}/${found.id}`;
+    if (!ctx.modelRegistry) return raw;
+    ui.notify(`No model matches "${raw}".`, "warning");
+  }
+}
+
+async function pickTools(ui: UI): Promise<string[] | undefined | null> {
+  const READ = `Read-only (${EXPLORE_TOOLS.join(", ")})`;
+  const ALL = "All tools (like subagent_general)";
+  const CUSTOM = "Custom list…";
+  const choice = await ui.select("Tools", [READ, ALL, CUSTOM]);
+  if (choice === undefined) return null;
+  if (choice === READ) return [...EXPLORE_TOOLS];
+  if (choice === ALL) return undefined;
+  const raw = await ui.input("Tools (comma-separated)", "read, grep, find, ls, bash");
+  if (raw === undefined) return null;
+  const list = raw.split(",").map((t) => t.trim()).filter(Boolean);
+  return list.length > 0 ? list : undefined;
+}
+
+async function createAgent(ctx: ExtensionContext, existing: readonly string[], onChange: () => void): Promise<void> {
+  const ui = ctx.ui;
+  let name: string | undefined;
+  while (name === undefined) {
+    const raw = await ui.input("New agent — name (e.g. reviewer)", "");
+    if (raw === undefined) return;
+    const err = validateName(raw.trim(), existing);
+    if (err) ui.notify(err, "warning");
+    else name = raw.trim();
+  }
+  const scopeChoice = await ui.select(`Save ${name} for`, ["This project (.unipi/config/agents)", "All projects (~/.unipi/config/agents)"]);
+  if (scopeChoice === undefined) return;
+  const scope = scopeChoice.startsWith("This") ? "project" : "global";
+  const description = (await ui.input("Description — the parent agent reads this to pick the profile", ""))?.trim();
+  if (!description) return;
+  const model = await pickModel(ui, ctx);
+  if (model === null) return;
+  const tools = await pickTools(ui);
+  if (tools === null) return;
+  const prompt = await ui.editor(`${name} — system prompt (enter saves)`, promptTemplate(name, description));
+  if (prompt === undefined || !prompt.trim()) return;
+  const file = join(agentsDir(scope, ctx.cwd), `${name}.md`);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, agentMarkdown({ name, description, model, tools, prompt }), "utf8");
+  onChange();
+  ui.notify(`Agent ${name} saved to ${file}. The agent can use it from the next turn.`, "info");
+}
+
+async function editAgent(ctx: ExtensionContext, file: string, onChange: () => void): Promise<void> {
+  const before = readFileSync(file, "utf8");
+  const after = await ctx.ui.editor(`Edit ${file}`, before);
+  if (after === undefined || after === before) return;
+  try {
+    parseFrontmatter(after);
+  } catch (e) {
+    ctx.ui.notify(`Not saved — frontmatter doesn't parse: ${e instanceof Error ? e.message : String(e)}`, "error");
+    return;
+  }
+  writeFileSync(file, after, "utf8");
+  onChange();
+  ctx.ui.notify(`Saved ${file}.`, "info");
+}
+
+async function manageCustom(ctx: ExtensionContext, profile: AgentProfile, onChange: () => void): Promise<void> {
+  const file = agentFile(profile, ctx.cwd);
+  if (file === undefined) {
+    ctx.ui.notify(`Can't find the file for ${profile.id}.`, "error");
+    return;
+  }
+  const other = profile.source === "project" ? "global" : "project";
+  const EDIT = "Edit file";
+  const COPY = `Copy to ${other === "global" ? "all projects (global)" : "this project"}`;
+  const DELETE = "Delete";
+  const choice = await ctx.ui.select(`${profile.id} (${profile.source}) — ${file}`, [EDIT, COPY, DELETE]);
+  if (choice === EDIT) return editAgent(ctx, file, onChange);
+  if (choice === COPY) {
+    const target = join(agentsDir(other, ctx.cwd), `${profile.id}.md`);
+    if (existsSync(target) && !(await ctx.ui.confirm("Overwrite?", `${target} already exists.`))) return;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, readFileSync(file, "utf8"), "utf8");
+    onChange();
+    ctx.ui.notify(`Copied to ${target}.`, "info");
+    return;
+  }
+  if (choice === DELETE && (await ctx.ui.confirm(`Delete ${profile.id}?`, file))) {
+    rmSync(file);
+    onChange();
+    ctx.ui.notify(`Deleted ${file}.`, "info");
+  }
+}
+
+export async function agentsManager(ctx: ExtensionContext, onChange: () => void): Promise<void> {
+  if (!ctx.hasUI) return;
+  while (true) {
+    const { profiles, warnings } = loadProfiles(ctx.cwd);
+    for (const w of warnings) ctx.ui.notify(`subagents: ${w}`, "warning");
+    const labels = profiles.map(describe);
+    const choice = await ctx.ui.select("Subagent profiles — pick one to manage, or create a new agent", [...labels, NEW_LABEL]);
+    if (choice === undefined) return;
+    if (choice === NEW_LABEL) {
+      await createAgent(ctx, profiles.map((p) => p.id), onChange);
+      continue;
+    }
+    const profile = profiles[labels.indexOf(choice)];
+    if (profile === undefined) return;
+    if (profile.source === "builtin") {
+      ctx.ui.notify(`${profile.id} is built in and can't be edited. Create a custom agent to change the model, tools or prompt.`, "info");
+      continue;
+    }
+    await manageCustom(ctx, profile, onChange);
+  }
+}
+
+export function registerAgentsCommand(pi: ExtensionAPI, deps: { onChange: (cwd: string) => void }): void {
+  const run = (ctx: ExtensionContext) => agentsManager(ctx, () => deps.onChange(ctx.cwd));
+  pi.registerCommand("unipi:agents", {
+    description: "Manage subagent profiles: list, create, edit, copy, delete custom agents",
+    handler: async (_args, ctx) => run(ctx),
+  });
+  registerCommandRunner(AGENTS_COMMAND, async (rawCtx) => run(rawCtx as ExtensionContext));
+}