@astrofoundry/pi-astro 0.17.1 → 0.18.1

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono): 16 curated subagents (8 general-purpose + 8 Flourish-pipeline) orchestrated by the bundled [`pi-subagents`](https://github.com/nicobailon/pi-subagents), a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 5 skills, and an `astro` theme. `pi-subagents` ships inside this package (`bundledDependencies`), so a single `pi install` brings everything.
+Personal customizations for the [pi coding agent](https://github.com/earendil-works/pi): 19 subagents (8 general-purpose, 8 Flourish-pipeline, 3 homelab specialists) run by the bundled `astro-subagents` extension, a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 8 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -18,7 +18,7 @@ If you previously installed the older `@mariozechner/pi-coding-agent` (now depre
 pi install npm:@astrofoundry/pi-astro
 ```
 
-`pi-subagents` is bundled inside this package. It loads automatically from `node_modules/pi-subagents/` and registers the `subagent` tool. **Do not also run `pi install npm:pi-subagents` separately**, that would load a second copy and pi would refuse the duplicate tool registration. The `astro-agents-loader` extension syncs each `agents/*.md` into `~/.pi/agent/agents/astro.<name>.md` on session start so `pi-subagents` picks them up.
+Agents load straight from the package: bundled agents are named `astro.<name>` (for example `astro.code-reviewer`), your own agents in `~/.pi/agent/agents/*.md` keep their plain names. If an earlier version copied bundled agents into that folder as `astro.*.md`, the first session removes those copies.
 
 ### 3. Install CLI prerequisites
 
@@ -51,23 +51,24 @@ Or run `/settings` inside pi and select `astro`.
 
 ```bash
 pi list           # confirm @astrofoundry/pi-astro is installed
-pi                # launch; confirm [Extensions] lists astro-agents-loader, grimoire, astro-footer, subagent, etc.
+pi                # launch; confirm [Extensions] lists astro-subagents, grimoire, astro-footer, specialist-gate, etc.
 ```
 
 ## What's inside
 
 **Tools** (LLM-callable):
-- `subagent` (from the bundled `pi-subagents`) - delegate tasks to any of the bundled agents, run them in parallel, chain them, or run them async with status/interrupt/resume
+- `subagent` - delegate a task to any agent, run several in parallel, or chain them (`{previous}` carries the prior output). Each agent runs in its own `pi` process with its own tool allowlist and skills; `/run <agent> -- <task>` does the same from the prompt, `/agents` lists what is available
 - `grimoire` - search indexed technical documentation via the grimoire CLI
 - `edit` - replaces pi's built-in with batch multi-file edits and Codex-style patch mode, preflight validation, atomic rollback
 - `gemini_image` - generate or edit images via Google Gemini native models and Imagen 4; cost-estimated confirmation before every call
 
 **Extensions:**
-- `astro-agents-loader` - copies bundled agent definitions into `~/.pi/agent/agents/astro.<name>.md` on session start so `pi-subagents` discovers them. Idempotent, namespaced, prunes stale entries.
+- `astro-subagents` - the `subagent` tool, `/run`, and `/agents`. Reads `agents/*.md` from this package and `~/.pi/agent/agents`; a child may delegate one more level by default (`maxSubagentDepth` in an agent tightens it)
 - `grimoire` - registers `grimoire` tool
 - `multi-edit` - registers the enhanced `edit` tool
 - `gemini-image` - registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` - blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
+- `specialist-gate` - gives each specialist agent (`astro.arcane`, `astro.identity`, `astro.network`) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through `sudo`, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has `~/.pi/agent/specialists.json`. `/specialists` prints the status. Host setup is described in [specialists/README.md](specialists/README.md).
 - `notify-on-stop` - runs a shell command when the agent finishes a turn (sound, voice, desktop notification). **Default: off.** Enable with `/notify on` (state persists in `~/.pi/agent/notify-on-stop.json`); disable with `/notify off`. macOS default command: plays the Glass system sound and speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Hard-kill (overrides `/notify on`) with `PI_STOP_NOTIFY_OFF=1`. Commands: `/notify [on|off|status|test]`. See [extensions/notify-on-stop/README.md](extensions/notify-on-stop/README.md) for full details.
   - **macOS voice install (required once for the default):** open **System Settings, Accessibility, Spoken Content, System Voice, Manage Voices...**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB to 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` - only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: ...]` text fallback. **Requires enabling `Terminal > Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
@@ -76,12 +77,13 @@ pi                # launch; confirm [Extensions] lists astro-agents-loader, grim
 - `astro-welcome` - pixel-art astronaut welcome screen (24-bit colour, twinkling starfield, rotating funny tagline, live stats) rendered on session start; auto-dismisses after 6 s, on first keystroke, or on first prompt submit. See [extensions/astro-welcome/README.md](extensions/astro-welcome/README.md).
 - `caveman` - `/caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]` toggles a persistent compressed-output mode. No argument toggles between off and the default level (`full`). Active level is shown as a footer badge and survives `/reload`. The skill body at `skills/caveman/SKILL.md` is also available as a one-shot via `/skill:caveman`.
 
-**Bundled subagents** (callable via the `subagent` tool from `pi-subagents`):
+**Bundled subagents** (call them as `astro.<name>`):
 - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
+- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium, certificates), `network` (UniFi, FreeRADIUS, Tailscale, read-only)
 - Flourish pipeline: `flourish-input-vision` (image to spec), `flourish-input-narrative` (text to spec), `flourish-input-codebase` (HTML to spec), `flourish-architect` (spec to plan), `flourish-template-developer` (plan to SDK template, needs `@flourish/sdk`), `flourish-example-builder` (template to realistic example), `flourish-preview-runner` (multi-breakpoint preview + screenshots, needs `@flourish/sdk`), `flourish-reviewer` (audit)
 
 **Skills** (loadable via `/skill:<name>`):
-- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`, `arcane`, `identity`, `network` (the last three are injected into their specialist agents)
 
 **Theme:**
 - `astro` - dark, gold accent, GitHub-dark-inspired
@@ -91,13 +93,19 @@ pi                # launch; confirm [Extensions] lists astro-agents-loader, grim
 Delegate to a subagent:
 
 ```
-use the code-reviewer agent to review src/routes/products.ts
+use astro.code-reviewer to review src/routes/products.ts
 ```
 
-Run several agents in parallel via pi-subagents:
+Run several agents in parallel:
 
 ```
-run reviewer and tester-api in parallel on the auth middleware changes
+run astro.code-reviewer and astro.tester-api in parallel on the auth middleware changes
+```
+
+Or from the prompt line:
+
+```
+/run astro.arcane -- list the Arcane projects and their state
 ```
 
 Search docs:

package/agents/arcane.md

@@ -0,0 +1,20 @@
+---
+name: arcane
+description: Operates the Arcane container platform and its Compose apps through the arcane tool. Project definitions change through GitOps, then the CLI syncs and verifies. Use for container and project status, logs, restarts, deploys, and Compose changes on the Arcane VM.
+tools: read, arcane, subagent
+skills: arcane
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+---
+You are the Arcane specialist. The `arcane` tool is your only way to reach Arcane and its GitOps repository. You have no shell and no file access; if a task needs anything else, say so and stop.
+
+Rules:
+
+- Read first. Run `arcane` with `["projects", "list"]` or `["containers", "list"]` before proposing a change.
+- Project definitions (Compose files, `.env` layout, project folders) change only through `gitops write`, `gitops commit`, `gitops push`, then a sync or `projects up`. Never try to edit a running project through the CLI; the tool refuses it.
+- Operational actions (restart, logs, stats, redeploy, image pull, prune) go straight through the CLI.
+- Confirm destructive operations (`down`, `delete`, `prune`) are explicitly requested in the task before running them.
+- Report facts from the JSON output. Sensitive fields are already removed; never guess at what was removed.
+- Delegate through `subagent` only to another specialist (`astro.identity`, `astro.network`) and only for that specialist's own area.

package/agents/identity.md

@@ -0,0 +1,20 @@
+---
+name: identity
+description: Operates Zitadel (users, service users, projects, applications, roles) and the DMZ guest that runs Pomerium, nginx, and lego through the identity tool. Use for identity, access, routes, and certificate questions and operations.
+tools: read, identity, subagent
+skills: identity
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+---
+You are the identity specialist. The `identity` tool is your only way to reach Zitadel and the DMZ guest. You have no shell and no file access; if a task needs anything else, say so and stop.
+
+Rules:
+
+- Read before you write. List existing Zitadel resources before creating one; never create duplicates.
+- Zitadel calls use the v2 resource APIs (`/v2/...`); use `/management/v1/` or `/admin/v1/` only when v2 lacks the operation.
+- Responses are redacted; a client secret or key is shown once by Zitadel and is not recoverable through this tool. When an operation returns a secret, tell the caller to store it in Vaultwarden immediately.
+- Pomerium route changes are edits to `02-pulsar-proxmox/dmz/config.yaml` in the homelab repository, deployed with its `deploy.sh`. Through this tool you can render, restart, reload, renew certificates, and read state. Propose the route diff; do not claim to have deployed it.
+- Confirm destructive operations (deleting users, applications, projects) are explicitly requested in the task.
+- Delegate through `subagent` only to another specialist (`astro.arcane`, `astro.network`) and only for that specialist's own area.

package/agents/network.md

@@ -0,0 +1,20 @@
+---
+name: network
+description: Operates the UniFi network (sites, devices, clients, networks, firewall policies), FreeRADIUS on LXC 108, and the Tailscale router on LXC 105 through the network tool. Use for network, VLAN, Wi-Fi, policy, and remote-access questions and checks.
+tools: read, network, subagent
+skills: network
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+---
+You are the network specialist. The `network` tool is your only way to reach UniFi, FreeRADIUS, and Tailscale. You have no shell and no file access; if a task needs anything else, say so and stop.
+
+Rules:
+
+- UniFi access is read-only in this version. Report configuration and state; when a change is needed, describe the exact UniFi setting and value and stop.
+- Start with `["unifi", "sites"]` to get the site id; every other UniFi read needs it.
+- RADIUS and Tailscale operations are fixed checks on the guests; `radius-check` validates the FreeRADIUS configuration without restarting it.
+- Wi-Fi CA rotation and device certificates are out of scope for this tool; point the caller to the homelab repository's `radius` folder.
+- Report facts from the JSON output. Never infer a client's identity beyond what UniFi returns.
+- Delegate through `subagent` only to another specialist (`astro.arcane`, `astro.identity`) and only for that specialist's own area.

package/extensions/astro-subagents/agents.test.ts

@@ -0,0 +1,109 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { type AgentDirs, discoverAgents, parseAgentFile, parseList, resolveSkills } from "./agents.ts";
+
+describe("parseAgentFile", () => {
+    const file = `---
+name: arcane
+description: Operates Arcane.
+tools: read, arcane, subagent
+skills: [arcane]
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+timeoutMinutes: 30
+---
+You are the Arcane specialist.
+`;
+
+    it("namespaces bundled agents and keeps user agents bare", () => {
+        const bundled = parseAgentFile(file, "/pkg/agents/arcane.md", "bundled");
+        const user = parseAgentFile(file, "/home/.pi/agent/agents/arcane.md", "user");
+        expect(bundled?.name).toBe("astro.arcane");
+        expect(user?.name).toBe("arcane");
+    });
+
+    it("normalizes every supported field", () => {
+        const agent = parseAgentFile(file, "/pkg/agents/arcane.md", "bundled");
+        expect(agent).toMatchObject({
+            description: "Operates Arcane.",
+            tools: ["read", "arcane", "subagent"],
+            skills: ["arcane"],
+            systemPromptMode: "replace",
+            inheritProjectContext: false,
+            inheritSkills: false,
+            maxSubagentDepth: 1,
+            timeoutMinutes: 30,
+            systemPrompt: "You are the Arcane specialist.",
+        });
+    });
+
+    it("applies defaults and rejects files without name or description", () => {
+        const minimal = parseAgentFile("---\nname: scout\ndescription: Recon\n---\nBody", "/a.md", "user");
+        expect(minimal).toMatchObject({ tools: undefined, skills: [], systemPromptMode: "replace", inheritProjectContext: false, inheritSkills: false });
+        expect(minimal?.maxSubagentDepth).toBeUndefined();
+        expect(parseAgentFile("---\nname: x\n---\nBody", "/b.md", "user")).toBeNull();
+        expect(parseAgentFile("---\nname: 'bad name!'\ndescription: d\n---\n", "/c.md", "user")).toBeNull();
+    });
+
+    it("accepts list values as strings or arrays", () => {
+        expect(parseList("read, bash")).toEqual(["read", "bash"]);
+        expect(parseList(["read", " bash "])).toEqual(["read", "bash"]);
+        expect(parseList(42)).toEqual([]);
+    });
+});
+
+describe("discovery", () => {
+    let root: string;
+    let dirs: AgentDirs;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "astro-agents-"));
+        dirs = {
+            bundledAgents: join(root, "pkg", "agents"),
+            bundledSkills: join(root, "pkg", "skills"),
+            userAgents: join(root, "user", "agents"),
+            userSkills: join(root, "user", "skills"),
+        };
+        for (const d of Object.values(dirs)) mkdirSync(d, { recursive: true });
+        writeFileSync(join(dirs.bundledAgents, "arcane.md"), "---\nname: arcane\ndescription: bundled\nskills: arcane\n---\nB");
+        writeFileSync(join(dirs.bundledAgents, "broken.md"), "no frontmatter");
+        writeFileSync(join(dirs.userAgents, "scout.md"), "---\nname: scout\ndescription: user\n---\nS");
+        writeFileSync(join(dirs.userAgents, "astro.arcane.md"), "---\nname: arcane\ndescription: legacy copy\n---\nL");
+        mkdirSync(join(dirs.bundledSkills, "arcane"), { recursive: true });
+        writeFileSync(join(dirs.bundledSkills, "arcane", "SKILL.md"), "---\nname: arcane\ndescription: d\n---\n# Arcane skill\nBody");
+        mkdirSync(join(dirs.userSkills, "mine"), { recursive: true });
+        writeFileSync(join(dirs.userSkills, "mine", "SKILL.md"), "mine body");
+    });
+
+    afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+    it("loads bundled and user agents, warns on broken files", () => {
+        const result = discoverAgents(root, "user", dirs);
+        expect(result.agents.map((a) => a.name).sort()).toEqual(["arcane", "astro.arcane", "scout"]);
+        expect(result.warnings).toHaveLength(1);
+        expect(result.warnings[0]).toContain("broken.md");
+    });
+
+    it("loads project agents only when asked and lets them override", () => {
+        const project = join(root, "repo", ".pi", "agents");
+        mkdirSync(project, { recursive: true });
+        writeFileSync(join(project, "scout.md"), "---\nname: scout\ndescription: project\n---\nP");
+        const cwd = join(root, "repo", "src");
+        mkdirSync(cwd, { recursive: true });
+        expect(discoverAgents(cwd, "user", dirs).agents.find((a) => a.name === "scout")?.description).toBe("user");
+        const both = discoverAgents(cwd, "both", dirs);
+        expect(both.agents.find((a) => a.name === "scout")?.description).toBe("project");
+        expect(both.projectAgentsDir).toBe(project);
+    });
+
+    it("resolves skills from bundled then user folders and strips frontmatter", () => {
+        const { skills, missing } = resolveSkills(["arcane", "mine", "nope"], dirs);
+        expect(skills.map((s) => s.name)).toEqual(["arcane", "mine"]);
+        expect(skills[0].body).toBe("# Arcane skill\nBody");
+        expect(missing).toEqual(["nope"]);
+    });
+});

package/extensions/astro-subagents/agents.ts

@@ -0,0 +1,200 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentSource = "bundled" | "user" | "project";
+export type AgentScope = "user" | "project" | "both";
+export type SystemPromptMode = "replace" | "append";
+
+/** Bundled agents register under this namespace, e.g. `astro.arcane`. */
+export const BUNDLED_NAMESPACE = "astro";
+
+export interface AgentConfig {
+    /** Name callers use: `astro.<name>` for bundled agents, `<name>` otherwise. */
+    name: string;
+    description: string;
+    tools?: string[];
+    skills: string[];
+    model?: string;
+    thinking?: string;
+    systemPromptMode: SystemPromptMode;
+    inheritProjectContext: boolean;
+    inheritSkills: boolean;
+    maxSubagentDepth?: number;
+    timeoutMinutes?: number;
+    systemPrompt: string;
+    source: AgentSource;
+    filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+    agents: AgentConfig[];
+    projectAgentsDir: string | null;
+    warnings: string[];
+}
+
+export interface AgentDirs {
+    bundledAgents: string;
+    bundledSkills: string;
+    userAgents: string;
+    userSkills: string;
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export function defaultDirs(): AgentDirs {
+    const packageRoot = path.resolve(here, "..", "..");
+    return {
+        bundledAgents: path.join(packageRoot, "agents"),
+        bundledSkills: path.join(packageRoot, "skills"),
+        userAgents: path.join(getAgentDir(), "agents"),
+        userSkills: path.join(getAgentDir(), "skills"),
+    };
+}
+
+type Frontmatter = {
+    name?: unknown;
+    description?: unknown;
+    tools?: unknown;
+    skills?: unknown;
+    model?: unknown;
+    thinking?: unknown;
+    systemPromptMode?: unknown;
+    inheritProjectContext?: unknown;
+    inheritSkills?: unknown;
+    maxSubagentDepth?: unknown;
+    timeoutMinutes?: unknown;
+};
+
+/** `tools: read, bash` and `tools: [read, bash]` are both in use. */
+export function parseList(value: unknown): string[] {
+    const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+    return raw
+        .filter((t): t is string => typeof t === "string")
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+
+function parseBoolean(value: unknown, fallback: boolean): boolean {
+    if (typeof value === "boolean") return value;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return fallback;
+}
+
+function parsePositiveInt(value: unknown): number | undefined {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+
+export function parseAgentFile(content: string, filePath: string, source: AgentSource): AgentConfig | null {
+    const { frontmatter, body } = parseFrontmatter<Frontmatter>(content);
+    if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") return null;
+    const localName = frontmatter.name.trim();
+    if (!/^[A-Za-z0-9][\w.-]*$/.test(localName)) return null;
+    const tools = parseList(frontmatter.tools);
+    const mode = frontmatter.systemPromptMode === "append" ? "append" : "replace";
+    return {
+        name: source === "bundled" ? `${BUNDLED_NAMESPACE}.${localName}` : localName,
+        description: frontmatter.description.trim(),
+        tools: tools.length > 0 ? tools : undefined,
+        skills: parseList(frontmatter.skills),
+        model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+        thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+        systemPromptMode: mode,
+        inheritProjectContext: parseBoolean(frontmatter.inheritProjectContext, false),
+        inheritSkills: parseBoolean(frontmatter.inheritSkills, false),
+        maxSubagentDepth: parsePositiveInt(frontmatter.maxSubagentDepth),
+        timeoutMinutes: parsePositiveInt(frontmatter.timeoutMinutes),
+        systemPrompt: body.trim(),
+        source,
+        filePath,
+    };
+}
+
+function loadAgentsFromDir(dir: string, source: AgentSource, warnings: string[]): AgentConfig[] {
+    const agents: AgentConfig[] = [];
+    if (!fs.existsSync(dir)) return agents;
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return agents;
+    }
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".md")) continue;
+        if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+        const filePath = path.join(dir, entry.name);
+        let content: string;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        } catch {
+            continue;
+        }
+        const agent = parseAgentFile(content, filePath, source);
+        if (!agent) {
+            warnings.push(`${filePath}: missing or invalid name/description frontmatter, skipped`);
+            continue;
+        }
+        agents.push(agent);
+    }
+    return agents;
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+    let current = cwd;
+    for (;;) {
+        const candidate = path.join(current, CONFIG_DIR_NAME, "agents");
+        try {
+            if (fs.statSync(candidate).isDirectory()) return candidate;
+        } catch {
+            /* keep walking */
+        }
+        const parent = path.dirname(current);
+        if (parent === current) return null;
+        current = parent;
+    }
+}
+
+/**
+ * Bundled agents always load. `scope` controls the others: user agents by
+ * default, project agents (`.pi/agents`, repo-controlled) only when asked.
+ * A user or project agent with the same runtime name overrides a bundled one.
+ */
+export function discoverAgents(cwd: string, scope: AgentScope, dirs: AgentDirs = defaultDirs()): AgentDiscoveryResult {
+    const warnings: string[] = [];
+    const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+    const bundled = loadAgentsFromDir(dirs.bundledAgents, "bundled", warnings);
+    const user = scope === "project" ? [] : loadAgentsFromDir(dirs.userAgents, "user", warnings);
+    const project = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project", warnings);
+    const byName = new Map<string, AgentConfig>();
+    for (const agent of [...bundled, ...user, ...project]) byName.set(agent.name, agent);
+    return { agents: [...byName.values()], projectAgentsDir, warnings };
+}
+
+export interface ResolvedSkill {
+    name: string;
+    filePath: string;
+    body: string;
+}
+
+/** Finds `<name>/SKILL.md` in the bundled skills first, then the user's. */
+export function resolveSkills(names: string[], dirs: AgentDirs = defaultDirs()): { skills: ResolvedSkill[]; missing: string[] } {
+    const skills: ResolvedSkill[] = [];
+    const missing: string[] = [];
+    for (const name of names) {
+        const candidates = [path.join(dirs.bundledSkills, name, "SKILL.md"), path.join(dirs.userSkills, name, "SKILL.md")];
+        const filePath = candidates.find((c) => fs.existsSync(c));
+        if (!filePath) {
+            missing.push(name);
+            continue;
+        }
+        skills.push({ name, filePath, body: stripFrontmatter(fs.readFileSync(filePath, "utf-8")).trim() });
+    }
+    return { skills, missing };
+}
+
+export function formatAgentList(agents: AgentConfig[]): string {
+    return agents.map((a) => `${a.name}: ${a.description}`).join("\n");
+}

package/extensions/astro-subagents/child.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import type { AgentConfig } from "./agents.ts";
+import {
+    AGENT_ENV,
+    applyEventLine,
+    buildChildArgs,
+    buildChildEnv,
+    childRemaining,
+    composeSystemPrompt,
+    currentDepth,
+    DEPTH_ENV,
+    emptyUsage,
+    finalOutput,
+    isFailed,
+    REMAINING_ENV,
+    resultOutput,
+    type RunResult,
+    runAgent,
+} from "./child.ts";
+
+const agent: AgentConfig = {
+    name: "astro.arcane",
+    description: "d",
+    tools: ["read", "arcane", "subagent"],
+    skills: ["arcane"],
+    systemPromptMode: "replace",
+    inheritProjectContext: false,
+    inheritSkills: false,
+    maxSubagentDepth: 1,
+    systemPrompt: "You are the Arcane specialist.",
+    source: "bundled",
+    filePath: "/pkg/agents/arcane.md",
+};
+
+describe("child arguments", () => {
+    it("builds a print-mode invocation with a strict tool allowlist and replaced prompt", () => {
+        const args = buildChildArgs({ agent, task: "list projects", promptFile: "/tmp/p.md", defaults: { model: "openai-codex/gpt-5.5", thinkingLevel: "medium" } });
+        expect(args).toEqual([
+            "--mode", "json", "-p", "--no-session",
+            "--model", "openai-codex/gpt-5.5",
+            "--thinking", "medium",
+            "--tools", "read,arcane,subagent",
+            "--no-context-files",
+            "--no-skills",
+            "--system-prompt", "/tmp/p.md",
+            "--", "Task: list projects",
+        ]);
+    });
+
+    it("appends instead of replacing and inherits context when asked", () => {
+        const open: AgentConfig = { ...agent, tools: undefined, systemPromptMode: "append", inheritProjectContext: true, inheritSkills: true, model: "anthropic/claude-x", thinking: "high" };
+        const args = buildChildArgs({ agent: open, task: "t", promptFile: "/tmp/p.md", defaults: { model: "other", thinkingLevel: "low" } });
+        expect(args).toEqual(["--mode", "json", "-p", "--no-session", "--model", "anthropic/claude-x", "--thinking", "high", "--append-system-prompt", "/tmp/p.md", "--", "Task: t"]);
+    });
+
+    it("does not pass the parent's thinking level to an agent that pins its own model", () => {
+        const pinned: AgentConfig = { ...agent, model: "m" };
+        expect(buildChildArgs({ agent: pinned, task: "t", promptFile: null, defaults: { thinkingLevel: "high" } })).not.toContain("--thinking");
+    });
+
+    it("inlines skills after the agent prompt", () => {
+        expect(composeSystemPrompt(agent, [{ name: "arcane", filePath: "/s", body: "Skill body" }])).toBe("You are the Arcane specialist.\n\n## Skill: arcane\n\nSkill body");
+    });
+
+    it("marks the child with agent name, depth, and remaining levels", () => {
+        const env = buildChildEnv(agent, 0, 1, { PATH: "/usr/bin" });
+        expect(env).toEqual({ PATH: "/usr/bin", [AGENT_ENV]: "astro.arcane", [DEPTH_ENV]: "1", [REMAINING_ENV]: "1" });
+    });
+
+    it("computes delegation depth from the environment and tightens per agent", () => {
+        expect(currentDepth({})).toEqual({ depth: 0, remaining: 2 });
+        expect(currentDepth({ [DEPTH_ENV]: "1", [REMAINING_ENV]: "1" })).toEqual({ depth: 1, remaining: 1 });
+        expect(currentDepth({ [DEPTH_ENV]: "x", [REMAINING_ENV]: "-3" })).toEqual({ depth: 0, remaining: 0 });
+        expect(childRemaining(2, agent)).toBe(1);
+        expect(childRemaining(1, agent)).toBe(0);
+        expect(childRemaining(3, { ...agent, maxSubagentDepth: undefined })).toBe(2);
+    });
+});
+
+describe("event parsing", () => {
+    it("accumulates assistant messages, usage, model, and stop reason", () => {
+        const result: RunResult = { agent: "a", agentSource: "bundled", task: "t", exitCode: -1, messages: [], stderr: "", usage: emptyUsage() };
+        const msg = {
+            role: "assistant",
+            content: [{ type: "toolCall", id: "1", name: "arcane", arguments: { args: ["projects", "list"] } }],
+            model: "gpt-5.5",
+            usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, totalTokens: 15, cost: { total: 0.01 } },
+            stopReason: "toolUse",
+        };
+        expect(applyEventLine(JSON.stringify({ type: "message_end", message: msg }), result)).toBe(true);
+        expect(applyEventLine(JSON.stringify({ type: "message_end", message: { ...msg, content: [{ type: "text", text: "Done." }], stopReason: "stop" } }), result)).toBe(true);
+        expect(applyEventLine("not json", result)).toBe(false);
+        expect(applyEventLine(JSON.stringify({ type: "other" }), result)).toBe(false);
+        expect(result.usage).toMatchObject({ turns: 2, input: 20, output: 10, contextTokens: 15 });
+        expect(result.model).toBe("gpt-5.5");
+        expect(result.stopReason).toBe("stop");
+        expect(finalOutput(result.messages)).toBe("Done.");
+        result.exitCode = 0;
+        expect(isFailed(result)).toBe(false);
+        expect(resultOutput(result)).toBe("Done.");
+    });
+
+    it("reports failures with the error message or stderr", () => {
+        const failed: RunResult = { agent: "a", agentSource: "user", task: "t", exitCode: 1, messages: [], stderr: "boom\n", usage: emptyUsage() };
+        expect(isFailed(failed)).toBe(true);
+        expect(resultOutput(failed)).toBe("boom");
+        expect(resultOutput({ ...failed, errorMessage: "quota" })).toBe("quota");
+    });
+});
+
+describe("runAgent", () => {
+    const fakePi = (script: string) => (args: string[]) => ({ command: "/bin/sh", args: ["-c", script, "pi", ...args] });
+
+    it("spawns the child, parses its JSON events, and passes the environment", async () => {
+        const script = `printf '%s\\n' "{\\"type\\":\\"message_end\\",\\"message\\":{\\"role\\":\\"assistant\\",\\"content\\":[{\\"type\\":\\"text\\",\\"text\\":\\"agent=$ASTRO_SUBAGENT_AGENT depth=$ASTRO_SUBAGENT_DEPTH remaining=$ASTRO_SUBAGENT_REMAINING tools=$4\\"}],\\"stopReason\\":\\"stop\\"}}"`;
+        const updates: string[] = [];
+        const result = await runAgent({
+            agent: { ...agent, skills: [] },
+            skills: [],
+            task: "hello",
+            cwd: process.cwd(),
+            depth: 0,
+            remaining: 1,
+            defaults: {},
+            invocation: fakePi(script),
+            onUpdate: (r) => updates.push(finalOutput(r.messages)),
+        });
+        expect(result.exitCode).toBe(0);
+        expect(finalOutput(result.messages)).toBe("agent=astro.arcane depth=1 remaining=1 tools=--no-session");
+        expect(updates).toHaveLength(1);
+    });
+
+    it("returns stderr and a non-zero exit code on failure", async () => {
+        const result = await runAgent({ agent, skills: [], task: "t", cwd: process.cwd(), depth: 0, remaining: 1, defaults: {}, invocation: fakePi("echo nope >&2; exit 3") });
+        expect(result.exitCode).toBe(3);
+        expect(resultOutput(result)).toBe("nope");
+    });
+
+    it("aborts through the signal", async () => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), 100);
+        const result = await runAgent({ agent, skills: [], task: "t", cwd: process.cwd(), depth: 0, remaining: 1, defaults: {}, signal: controller.signal, invocation: fakePi("sleep 5") });
+        expect(result.stopReason).toBe("aborted");
+        expect(isFailed(result)).toBe(true);
+    });
+
+    it("kills the child after timeoutMinutes", async () => {
+        const slow: AgentConfig = { ...agent, timeoutMinutes: 0.001 };
+        const result = await runAgent({ agent: slow, skills: [], task: "t", cwd: process.cwd(), depth: 0, remaining: 1, defaults: {}, invocation: fakePi("sleep 5") });
+        expect(result.errorMessage).toMatch(/timed out/);
+        expect(isFailed(result)).toBe(true);
+    });
+});