@astrofoundry/pi-astro 0.5.0 → 0.6.0

package/README.md

@@ -53,10 +53,14 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
 **Tools** (LLM-callable):
 - `astro_agent` — delegate a task to a named subagent in an isolated pi subprocess
 - `grimoire` — search indexed technical documentation via the grimoire CLI
+- `edit` — replaces pi's built-in with batch multi-file edits + Codex-style patch mode, preflight validation, atomic rollback
+- `gemini_image` — generate or edit images via Google Gemini native models + Imagen 4; cost-estimated confirmation before every call
 
 **Extensions:**
 - `astro-agents` — registers `astro_agent` + ships 8 bundled subagents
 - `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)
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
 
 **Bundled subagents** (callable via `astro_agent`):

package/extensions/astro-agents/agents/code-reviewer.md

@@ -3,9 +3,7 @@ name: code-reviewer
 description: |-
   Use this agent to review code for quality, security, correctness, and spec compliance. It is read-only and reports issues with severity and remediation guidance.
 color: red
-memory: user
 tools: read, grep, find, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/google-tech-lead.md

@@ -3,9 +3,7 @@ name: google-tech-lead
 description: |-
   Use this agent for designing and implementing anything in the Google/Firebase ecosystem — Cloud Functions 2nd gen (Express), Firestore (data models, security rules, indexes), Firebase Auth (Identity Platform, MFA), Firebase Hosting, Firebase Storage, App Check, and Emulator Suite. This is a tech lead that both architects and writes production code, making decisions about the Firebase stack grounded in official documentation. Examples:\n\n<example>\nContext: Implementing a Cloud Function with Express\nuser: "Create a Cloud Functions 2nd gen HTTP function in europe-west3 that hosts an Express app with versioned API routes (/api/v1/...). It needs middleware for auth token verification, rate limiting, and request validation. Set up proper error handling and CORS."\nassistant: "I'll architect and implement the Cloud Function with Express. Let me use the google-tech-lead agent — it will verify Firebase Functions v2 API, Express integration patterns, and middleware setup through grimoire before writing any code."\n<commentary>\nCloud Functions hosting Express requires specific v2 patterns for region config, CORS handling, and middleware integration that differ from v1.\n</commentary>\n</example>\n\n<example>\nContext: Designing Firestore data model and security rules\nuser: "Design the Firestore schema for API key management. Each partner can have multiple API keys with scopes, expiry dates, and revocation status. Keys must be hashed, never stored in plain text. Write the security rules to enforce that partners can only read their own keys and only admins can create/revoke."\nassistant: "I'll design the data model and security rules. Let me use the google-tech-lead agent to verify Firestore schema patterns, TTL fields, and security rule syntax through grimoire."\n<commentary>\nFirestore data modeling with security rules requires careful schema design that aligns with rule capabilities — you can't write rules for schemas you designed wrong.\n</commentary>\n</example>\n\n<example>\nContext: Setting up Firebase Auth with MFA\nuser: "Implement Firebase Auth with Identity Platform for the dashboard. Users authenticate with email/password, then enroll in TOTP MFA. The enrollment flow generates a QR code, verifies the first code, and enables MFA. All subsequent logins require the TOTP challenge."\nassistant: "I'll implement the full MFA flow. Let me use the google-tech-lead agent to verify the Identity Platform TOTP API, enrollment steps, and challenge verification through grimoire."\n<commentary>\nFirebase Auth MFA with Identity Platform has specific enrollment and challenge flows that must follow the exact API sequence.\n</commentary>\n</example>
 color: orange
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/spec-writer.md

@@ -3,9 +3,7 @@ name: spec-writer
 description: |-
   Use this agent to write or update functional and technical specification documents for new features or changes. It takes a feature request or business requirement as input, researches the existing codebase and specs for context, asks clarifying questions, and produces spec documents that downstream agents (google-tech-lead, ui-architect, ui-frontend-developer, testers) can consume directly. Examples:\n\n<example>\nContext: Writing specs for a new feature\nuser: "Write the functional and technical specs for a webhook retry system. When a webhook delivery fails, the system should retry with exponential backoff (1min, 5min, 30min, 2h, 24h). After 5 failures, mark the webhook as failed and notify the partner via email. Track delivery attempts in Firestore."\nassistant: "I'll write both specs for the webhook retry system. Let me use the spec-writer agent — it will research the existing webhook implementation, check how delivery tracking currently works, ask any clarifying questions, then write specs that the google-tech-lead and tester agents can implement from."\n<commentary>\nNew features need both functional specs (what it does, business rules, user flows) and technical specs (data model, API contract, error handling) before implementation begins.\n</commentary>\n</example>\n\n<example>\nContext: Updating specs for a changed requirement\nuser: "The partner onboarding flow needs to change — instead of admin-created accounts, partners should self-register with email verification, then an admin approves them. Update the functional and technical specs."\nassistant: "I'll update both specs for the new onboarding flow. Let me use the spec-writer agent to read the current specs, identify all sections affected by this change, and write the updates while ensuring consistency with the rest of the system."\n<commentary>\nSpec updates must trace through all affected sections — a change in onboarding flow impacts auth, API routes, Firestore schema, email triggers, and admin workflows.\n</commentary>\n</example>\n\n<example>\nContext: Specifying an API contract\nuser: "We need to add a bulk product import endpoint. Partners upload a CSV, the system validates it, creates products in Odoo, and returns a batch result. Spec out the API contract, validation rules, error handling, and the batch tracking model."\nassistant: "I'll spec the bulk import API. Let me use the spec-writer agent to research the existing product and batch models, check how other bulk operations work in the system, and write a complete API contract with request/response shapes, validation, and error scenarios."\n<commentary>\nAPI contract specs must define every request/response shape, status code, error format, and edge case so the implementing agent has zero ambiguity.\n</commentary>\n</example>
 color: purple
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/tester-api.md

@@ -5,9 +5,7 @@ description: |-
 color: yellow
 skills:
   - postman-cli
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/tester-ui.md

@@ -5,9 +5,7 @@ description: |-
 color: yellow
 skills:
   - playwright-cli
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-architect.md

@@ -3,9 +3,7 @@ name: ui-architect
 description: |-
   Use this agent to create component specifications, screen-by-screen UI specs, and layout patterns from an existing design system. This agent takes the design tokens produced by ui-design-system and defines how every UI element looks, behaves, and responds — button variants, form states, data tables, navigation patterns, status badges, modals, toasts, empty/loading/error states, and full page layouts. It outputs detailed spec documents, not code. Examples:\n\n<example>\nContext: Defining component specifications for a new project\nuser: "Using the design system in docs/ui/ui-specs/ui-00-design-system.md, create the component spec for all common UI elements: buttons, form inputs, selects, checkboxes, toggles, data tables, filter bars, status badges, modals, toasts, empty states, loading states, and error banners."\nassistant: "I'll create the full component specification. Let me use the ui-architect agent — it will read the design tokens, reference shadcn/ui component APIs through grimoire, and define every variant, state, and responsive behavior using the token system."\n<commentary>\nComponent specs require mapping abstract design tokens to concrete UI elements with precise dimensions, colors, states, and responsive behavior.\n</commentary>\n</example>\n\n<example>\nContext: Writing a screen spec for a specific page\nuser: "Write the screen spec for the Orders List page. It needs a filter bar (search, status pills, date range), a data table with sortable columns (Order ID, Partner, Status, Total, Date), pagination, and bulk actions. Reference the component specs and design system tokens."\nassistant: "I'll write the Orders List screen spec. Let me use the ui-architect agent to define the page layout, data requirements, component composition, interactions, and responsive behavior — all referencing the established tokens and component specs."\n<commentary>\nScreen specs compose components into full pages with specific data bindings, interaction flows, and responsive breakpoint behavior.\n</commentary>\n</example>\n\n<example>\nContext: Defining layout shells\nuser: "Define the layout structure for the application: auth shell (login, password reset), partner dashboard shell (sidebar + header + content area), and admin dashboard shell. Include responsive behavior for all three breakpoints."\nassistant: "I'll define all three layout shells. Let me use the ui-architect agent to specify the structure, dimensions, responsive collapse behavior, and how content areas adapt across mobile, tablet, and desktop."\n<commentary>\nLayout shells are the structural foundation that screen specs build on — they define navigation, header, content areas, and responsive behavior.\n</commentary>\n</example>
 color: cyan
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-design-system.md

@@ -3,9 +3,7 @@ name: ui-design-system
 description: |-
   Use this agent to create or modify the foundational design system for a project — design tokens (colors, typography, spacing, border radius, shadows, motion, breakpoints) and their CSS implementation. This agent produces concrete Tailwind v4 + shadcn/ui v2 token files, not component specs or code. It asks clarifying questions before starting, proposes aesthetic direction, validates WCAG contrast ratios, and outputs both CSS config and a design system reference document. Examples:\n\n<example>\nContext: Creating a design system from scratch\nuser: "Create the design system for a maritime logistics dashboard. Brand colors are deep navy and amber gold. Target audience is warehouse managers and logistics operators. Needs dark mode."\nassistant: "I'll create the foundational design system. Let me use the ui-design-system agent — it will propose an aesthetic direction, define all tokens in oklch for shadcn/ui v2, configure the Tailwind v4 @theme block, and validate WCAG contrast ratios before finalizing."\n<commentary>\nA new design system requires establishing the complete visual language: color palette with semantic mapping, typography scale, spacing system, shadows, motion tokens, and breakpoints — all in the correct format for Tailwind v4 + shadcn/ui v2.\n</commentary>\n</example>\n\n<example>\nContext: Modifying an existing design system\nuser: "Our current design system uses hex colors and HSL for shadcn tokens. We need to migrate to oklch for shadcn/ui v2 and add a complete dark mode palette. Current tokens are in docs/ui/ui-specs/ui-00-design-system.md."\nassistant: "I'll migrate the design tokens to oklch and add dark mode. Let me use the ui-design-system agent to convert all colors, verify contrast ratios in both modes, and update the CSS variables and @theme block."\n<commentary>\nMigrating token formats requires systematic conversion, contrast re-validation, and updating the CSS output to match current Tailwind v4 + shadcn/ui v2 conventions.\n</commentary>\n</example>\n\n<example>\nContext: Extending the design system with new tokens\nuser: "We need to add a status badge color system to our design tokens. Statuses: draft, active, processing, shipped, delivered, failed, cancelled. Each needs background, text, and border colors that work in both light and dark mode."\nassistant: "I'll design the status color system. Let me use the ui-design-system agent to create accessible color pairings for each status, define the tokens in oklch, and add them to the CSS variables with dark mode variants."\n<commentary>\nAdding semantic color groups requires careful selection for distinctiveness, accessibility, and consistency with the existing palette.\n</commentary>\n</example>
 color: green
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-frontend-developer.md

@@ -3,9 +3,7 @@ name: ui-frontend-developer
 description: |-
   Use this agent for implementing specific React components, pages, or features with TypeScript, Next.js App Router, Tailwind CSS, and shadcn/ui. This agent receives laser-focused prompts with exact specifications and strictly verifies all SDK/library usage through grimoire before writing any code. Examples:\n\n<example>\nContext: Implementing a specific component from a screen spec\nuser: "Implement the OrderHistoryTable component in src/components/orders/OrderHistoryTable.tsx. It receives OrderRow[] as props, uses shadcn/ui DataTable with sortable columns (Order ID, Date, Status, Total), a status badge using the design system color tokens, and pagination. Follow the screen spec in docs/ui/ui-specs/orders-list.md."\nassistant: "I'll implement the OrderHistoryTable component. Let me use the ui-frontend-developer agent — it will verify shadcn/ui DataTable API and Tailwind token usage through grimoire before writing the component."\n<commentary>\nSpecific component implementation with exact props, library usage, and design system constraints requires the frontend specialist.\n</commentary>\n</example>\n\n<example>\nContext: Fixing a typed component issue\nuser: "The ProductCard component at src/components/catalog/ProductCard.tsx has a type error — the price prop is typed as string but the API returns number. Fix the type, update the Zod schema in src/schemas/product.ts, and ensure the formatter in formatCurrency handles both."\nassistant: "I'll fix the type mismatch across the component, schema, and utility. Let me use the ui-frontend-developer agent to trace the type through all layers."\n<commentary>\nTypeScript type issues that span multiple files need systematic tracing through components, schemas, and utilities.\n</commentary>\n</example>\n\n<example>\nContext: Building a Next.js App Router page\nuser: "Create the /settings/profile page using Next.js App Router. Server Component that fetches user profile via Server Action, with a client form component using React Hook Form + Zod for validation. Use the design system spacing and typography tokens. Spec: docs/ui/ui-specs/settings-profile.md."\nassistant: "I'll build the settings profile page with the Server Component / Client Component split. Let me use the ui-frontend-developer agent to verify Next.js App Router patterns and React Hook Form integration through grimoire."\n<commentary>\nNext.js App Router pages with mixed Server/Client Components and form handling require precise knowledge of current API patterns.\n</commentary>\n</example>
 color: blue
-memory: user
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

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

@@ -0,0 +1,152 @@
+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 { discoverAgents } from "./discovery.ts";
+
+function writeAgent(dir: string, name: string, frontmatter: Record<string, string>, body = ""): void {
+    const fm = Object.entries(frontmatter)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join("\n");
+    writeFileSync(join(dir, `${name}.md`), `---\n${fm}\n---\n${body}\n`, "utf-8");
+}
+
+describe("discoverAgents", () => {
+    let bundleDir: string;
+    let cwd: string;
+    const originalAgentDir = process.env.PI_AGENT_DIR;
+
+    beforeEach(() => {
+        bundleDir = mkdtempSync(join(tmpdir(), "bundle-"));
+        cwd = mkdtempSync(join(tmpdir(), "cwd-"));
+        const pseudoAgentDir = mkdtempSync(join(tmpdir(), "agentdir-"));
+        mkdirSync(join(pseudoAgentDir, "agents"), { recursive: true });
+        process.env.PI_AGENT_DIR = pseudoAgentDir;
+    });
+
+    afterEach(() => {
+        rmSync(bundleDir, { recursive: true, force: true });
+        rmSync(cwd, { recursive: true, force: true });
+        process.env.PI_AGENT_DIR = originalAgentDir;
+    });
+
+    it("returns empty array when no agent dirs exist", () => {
+        rmSync(bundleDir, { recursive: true, force: true });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents).toEqual([]);
+    });
+
+    it("loads bundled agents with name, description, body", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "does a" }, "system prompt a");
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents).toHaveLength(1);
+        expect(agents[0].name).toBe("a");
+        expect(agents[0].description).toBe("does a");
+        expect(agents[0].systemPrompt.trim()).toBe("system prompt a");
+        expect(agents[0].source).toBe("bundle");
+    });
+
+    it("parses color field", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "x", color: "red" });
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.color).toBe("red");
+    });
+
+    it("parses tools as comma-separated list", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "x", tools: "read, bash, grep" });
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.tools).toEqual(["read", "bash", "grep"]);
+    });
+
+    it("omits tools when field is absent", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "x" });
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.tools).toBeUndefined();
+    });
+
+    it("parses skills as YAML list", () => {
+        writeFileSync(
+            join(bundleDir, "a.md"),
+            `---\nname: a\ndescription: x\nskills:\n  - playwright-cli\n  - grimoire\n---\n`,
+            "utf-8",
+        );
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.skills).toEqual(["playwright-cli", "grimoire"]);
+    });
+
+    it("parses skills as comma-separated string when inline", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "x", skills: "alpha, beta" });
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.skills).toEqual(["alpha", "beta"]);
+    });
+
+    it("omits skills when empty", () => {
+        writeAgent(bundleDir, "a", { name: "a", description: "x", skills: "" });
+        const [agent] = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agent.skills).toBeUndefined();
+    });
+
+    it("skips files missing name or description", () => {
+        writeAgent(bundleDir, "a", { name: "a" }); // missing description
+        writeAgent(bundleDir, "b", { description: "x" }); // missing name
+        writeAgent(bundleDir, "c", { name: "c", description: "x" });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents.map((a) => a.name)).toEqual(["c"]);
+    });
+
+    it("skips non-.md files", () => {
+        writeFileSync(join(bundleDir, "notes.txt"), "not an agent", "utf-8");
+        writeAgent(bundleDir, "a", { name: "a", description: "x" });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents).toHaveLength(1);
+    });
+
+    it("project agents override user + bundle when scope is 'both'", () => {
+        writeAgent(bundleDir, "shared", { name: "shared", description: "from bundle" });
+
+        const projectAgentsDir = join(cwd, ".pi", "agents");
+        mkdirSync(projectAgentsDir, { recursive: true });
+        writeAgent(projectAgentsDir, "shared", { name: "shared", description: "from project" });
+
+        const agents = discoverAgents({ cwd, bundleDir, scope: "both" });
+        const shared = agents.find((a) => a.name === "shared");
+        expect(shared?.description).toBe("from project");
+        expect(shared?.source).toBe("project");
+    });
+
+    it("scope='user' skips project agents", () => {
+        writeAgent(bundleDir, "b", { name: "b", description: "bundle" });
+        const projectAgentsDir = join(cwd, ".pi", "agents");
+        mkdirSync(projectAgentsDir, { recursive: true });
+        writeAgent(projectAgentsDir, "p", { name: "p", description: "project" });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents.map((a) => a.name).sort()).toEqual(["b"]);
+    });
+
+    it("scope='project' skips user-level agents", () => {
+        writeAgent(bundleDir, "b", { name: "b", description: "bundle" });
+        const projectAgentsDir = join(cwd, ".pi", "agents");
+        mkdirSync(projectAgentsDir, { recursive: true });
+        writeAgent(projectAgentsDir, "p", { name: "p", description: "project" });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "project" });
+        expect(agents.map((a) => a.name).sort()).toEqual(["b", "p"]);
+    });
+
+    it("walks parent directories to find nearest .pi/agents", () => {
+        const deep = join(cwd, "a", "b", "c");
+        mkdirSync(deep, { recursive: true });
+        const projectAgentsDir = join(cwd, ".pi", "agents");
+        mkdirSync(projectAgentsDir, { recursive: true });
+        writeAgent(projectAgentsDir, "p", { name: "p", description: "project" });
+
+        const agents = discoverAgents({ cwd: deep, bundleDir, scope: "project" });
+        expect(agents.map((a) => a.name)).toContain("p");
+    });
+
+    it("ignores symlinks to non-existent targets", () => {
+        // symlink behavior — create a file, our loader should accept symlinks
+        writeAgent(bundleDir, "a", { name: "a", description: "x" });
+        const agents = discoverAgents({ cwd, bundleDir, scope: "user" });
+        expect(agents).toHaveLength(1);
+    });
+});

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

@@ -0,0 +1,208 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentConfig } from "./discovery.ts";
+
+vi.mock("./discovery.ts", () => ({
+    discoverAgents: vi.fn(),
+}));
+
+vi.mock("./spawn.ts", () => ({
+    runAgent: vi.fn(),
+}));
+
+vi.mock("node:fs", async (importActual) => {
+    const actual = await importActual<typeof import("node:fs")>();
+    return { ...actual, existsSync: vi.fn(actual.existsSync) };
+});
+
+type ToolDef = {
+    name: string;
+    execute: (
+        id: string,
+        input: { agent: string; task: string; scope?: "user" | "project" | "both" },
+        signal: AbortSignal | undefined,
+        onUpdate: unknown,
+        ctx: {
+            cwd: string;
+            hasUI: boolean;
+            ui: {
+                notify: ReturnType<typeof vi.fn>;
+                confirm: ReturnType<typeof vi.fn>;
+            };
+        },
+    ) => Promise<{ content: Array<{ text: string }>; details: { agent: string; source: string } }>;
+};
+
+function makePi(): { tools: ToolDef[]; registerTool: (t: ToolDef) => void } {
+    const tools: ToolDef[] = [];
+    return { tools, registerTool: (t) => tools.push(t) };
+}
+
+function makeCtx(): {
+    cwd: string;
+    hasUI: boolean;
+    ui: { notify: ReturnType<typeof vi.fn>; confirm: ReturnType<typeof vi.fn> };
+} {
+    return {
+        cwd: "/tmp/test-cwd",
+        hasUI: true,
+        ui: {
+            notify: vi.fn(),
+            confirm: vi.fn().mockResolvedValue(true),
+        },
+    };
+}
+
+const sampleAgent: AgentConfig = {
+    name: "scout",
+    description: "quick recon",
+    color: "red",
+    systemPrompt: "You are scout.",
+    source: "bundle",
+    filePath: "/pkg/extensions/astro-agents/agents/scout.md",
+};
+
+describe("astro-agents extension (astro_agent tool)", () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("registers the astro_agent tool", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        vi.mocked(discoverAgents).mockReturnValue([sampleAgent]);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(pi.tools[0].name).toBe("astro_agent");
+    });
+
+    it("throws when agent name is not found; lists available", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        vi.mocked(discoverAgents).mockReturnValue([sampleAgent]);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await expect(
+            pi.tools[0].execute("t", { agent: "ghost", task: "x" }, undefined, undefined, ctx),
+        ).rejects.toThrow(/not found.+scout/);
+    });
+
+    it("happy path: spawns subagent and returns its text", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        vi.mocked(discoverAgents).mockReturnValue([sampleAgent]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "done", exitCode: 0, stderr: "" });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const res = await pi.tools[0].execute("t", { agent: "scout", task: "recon" }, undefined, undefined, ctx);
+        expect(res.content[0].text).toBe("done");
+        expect(ctx.ui.notify).toHaveBeenCalled();
+    });
+
+    it("throws on non-zero exit", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        vi.mocked(discoverAgents).mockReturnValue([sampleAgent]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "", exitCode: 1, stderr: "boom" });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        await expect(
+            pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, makeCtx()),
+        ).rejects.toThrow(/exited with code 1/);
+    });
+
+    it("returns placeholder when agent produced no output", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        vi.mocked(discoverAgents).mockReturnValue([sampleAgent]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "", exitCode: 0, stderr: "" });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const res = await pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, makeCtx());
+        expect(res.content[0].text).toMatch(/no output/);
+    });
+
+    it("prompts confirmation for project-scoped agent and respects 'no'", async () => {
+        const projectAgent = { ...sampleAgent, source: "project" as const };
+        const { discoverAgents } = await import("./discovery.ts");
+        vi.mocked(discoverAgents).mockReturnValue([projectAgent]);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        ctx.ui.confirm.mockResolvedValue(false);
+        await expect(
+            pi.tools[0].execute("t", { agent: "scout", task: "x", scope: "project" }, undefined, undefined, ctx),
+        ).rejects.toThrow(/cancelled/);
+    });
+
+    it("warns when declared skill isn't in the package", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        const agentWithSkill: AgentConfig = { ...sampleAgent, skills: ["ghost-skill"] };
+        vi.mocked(discoverAgents).mockReturnValue([agentWithSkill]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "ok", exitCode: 0, stderr: "" });
+        const fs = await import("node:fs");
+        vi.mocked(fs.existsSync).mockImplementation((p) => !String(p).endsWith("ghost-skill"));
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/skill .*ghost-skill.*not present/), "warning");
+    });
+
+    it("resolves declared skill paths that exist in the package skills dir", async () => {
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        const agentWithSkill: AgentConfig = { ...sampleAgent, skills: ["playwright-cli"] };
+        vi.mocked(discoverAgents).mockReturnValue([agentWithSkill]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "ok", exitCode: 0, stderr: "" });
+        const fs = await import("node:fs");
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        await pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, makeCtx());
+        const runAgentCalls = vi.mocked(runAgent).mock.calls;
+        expect(runAgentCalls[0][0].skillPaths).toHaveLength(1);
+    });
+
+    it("agent without color renders plain name in notify", async () => {
+        const noColor: AgentConfig = { ...sampleAgent, color: undefined };
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        vi.mocked(discoverAgents).mockReturnValue([noColor]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "ok", exitCode: 0, stderr: "" });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, ctx);
+        const notifyMsg = ctx.ui.notify.mock.calls[0][0] as string;
+        expect(notifyMsg).toContain("scout");
+    });
+
+    it("agent with unknown color falls back to plain name", async () => {
+        const weirdColor: AgentConfig = { ...sampleAgent, color: "fuchsia-tangerine" };
+        const { discoverAgents } = await import("./discovery.ts");
+        const { runAgent } = await import("./spawn.ts");
+        vi.mocked(discoverAgents).mockReturnValue([weirdColor]);
+        vi.mocked(runAgent).mockResolvedValue({ text: "ok", exitCode: 0, stderr: "" });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.tools[0].execute("t", { agent: "scout", task: "x" }, undefined, undefined, ctx);
+        expect(ctx.ui.notify).toHaveBeenCalled();
+    });
+});

package/extensions/astro-agents/index.ts

@@ -43,9 +43,27 @@ const params = Type.Object({
     ),
 });
 
-function colorizePrefix(agentName: string, color: string | undefined): string {
-    if (!color) return agentName;
-    return `[${color}] ${agentName}`;
+const ANSI_RESET = "\x1b[0m";
+const ANSI_BOLD = "\x1b[1m";
+
+const COLOR_BADGE: Record<string, string> = {
+    red: "\x1b[41m\x1b[97m",
+    orange: "\x1b[48;5;208m\x1b[30m",
+    yellow: "\x1b[43m\x1b[30m",
+    green: "\x1b[42m\x1b[97m",
+    blue: "\x1b[44m\x1b[97m",
+    purple: "\x1b[45m\x1b[97m",
+    magenta: "\x1b[45m\x1b[97m",
+    cyan: "\x1b[46m\x1b[30m",
+    white: "\x1b[47m\x1b[30m",
+    gray: "\x1b[100m\x1b[97m",
+};
+
+function agentBadge(agentName: string, color: string | undefined): string {
+    const key = color?.toLowerCase();
+    const bg = key ? COLOR_BADGE[key] : undefined;
+    if (!bg) return agentName;
+    return `${bg}${ANSI_BOLD} ${agentName} ${ANSI_RESET}`;
 }
 
 export default function astroAgentsExtension(pi: ExtensionAPI): void {
@@ -80,7 +98,7 @@ export default function astroAgentsExtension(pi: ExtensionAPI): void {
                 }
             }
 
-            ctx.ui.notify(`Running ${colorizePrefix(agent.name, agent.color)}…`, "info");
+            ctx.ui.notify(`Running ${agentBadge(agent.name, agent.color)}…`, "info");
 
             const skillPaths = agent.skills ? resolvePackageSkills(agent.skills, ctx) : [];