@astrofoundry/pi-astro 0.5.1 → 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/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/spawn.test.ts

@@ -0,0 +1,218 @@
+import { EventEmitter } from "node:events";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:child_process", () => ({
+    spawn: vi.fn(),
+}));
+
+function makeFakeProc(): {
+    proc: EventEmitter & { stdout: EventEmitter; stderr: EventEmitter; kill: ReturnType<typeof vi.fn> };
+    close: (code: number) => void;
+    error: (err: Error) => void;
+    emit: (w: "stdout" | "stderr", chunk: string) => void;
+} {
+    const proc = Object.assign(new EventEmitter(), {
+        stdout: new EventEmitter(),
+        stderr: new EventEmitter(),
+        kill: vi.fn(),
+    });
+    return {
+        proc,
+        close: (code) => proc.emit("close", code),
+        error: (err) => proc.emit("error", err),
+        emit: (w, chunk) => proc[w].emit("data", Buffer.from(chunk, "utf-8")),
+    };
+}
+
+describe("runAgent (spawn.ts)", () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("spawns pi with --mode json -p --no-session and captures agent_end", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "sys" },
+            task: "do thing",
+            cwd: "/tmp",
+        });
+
+        // Emit an agent_end with a single assistant message
+        fake.emit(
+            "stdout",
+            JSON.stringify({
+                type: "agent_end",
+                messages: [{ role: "assistant", content: [{ type: "text", text: "result" }] }],
+            }) + "\n",
+        );
+        fake.close(0);
+
+        const res = await promise;
+        expect(res.exitCode).toBe(0);
+        expect(res.text).toBe("result");
+
+        const args = vi.mocked(spawn).mock.calls[0][1] as string[];
+        expect(args).toContain("--mode");
+        expect(args).toContain("json");
+        expect(args).toContain("-p");
+        expect(args).toContain("--no-session");
+    });
+
+    it("includes --tools when agent has tools", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: {
+                name: "a",
+                description: "x",
+                source: "bundle",
+                filePath: "/tmp/a.md",
+                systemPrompt: "",
+                tools: ["read", "bash"],
+            },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.close(0);
+        await promise;
+        const args = vi.mocked(spawn).mock.calls[0][1] as string[];
+        expect(args).toContain("--tools");
+        expect(args).toContain("read,bash");
+    });
+
+    it("includes --no-skills + --skill paths when skills declared", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: {
+                name: "a",
+                description: "x",
+                source: "bundle",
+                filePath: "/tmp/a.md",
+                systemPrompt: "",
+                skills: ["playwright-cli"],
+            },
+            task: "t",
+            cwd: "/tmp",
+            skillPaths: ["/pkg/skills/playwright-cli"],
+        });
+        fake.close(0);
+        await promise;
+        const args = vi.mocked(spawn).mock.calls[0][1] as string[];
+        expect(args).toContain("--no-skills");
+        expect(args).toContain("--skill");
+        expect(args).toContain("/pkg/skills/playwright-cli");
+    });
+
+    it("appends --append-system-prompt when agent has a systemPrompt", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "body" },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.close(0);
+        await promise;
+        const args = vi.mocked(spawn).mock.calls[0][1] as string[];
+        expect(args).toContain("--append-system-prompt");
+    });
+
+    it("returns empty text when agent_end has no assistant messages", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "" },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.emit("stdout", JSON.stringify({ type: "agent_end", messages: [] }) + "\n");
+        fake.close(0);
+        const res = await promise;
+        expect(res.text).toBe("");
+    });
+
+    it("ignores non-JSON stdout lines gracefully", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "" },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.emit("stdout", "garbage not json\n");
+        fake.close(0);
+        const res = await promise;
+        expect(res.exitCode).toBe(0);
+    });
+
+    it("captures stderr into the result", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "" },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.emit("stderr", "oops");
+        fake.close(1);
+        const res = await promise;
+        expect(res.stderr).toContain("oops");
+        expect(res.exitCode).toBe(1);
+    });
+
+    it("resolves with exitCode 1 on spawn error", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "" },
+            task: "t",
+            cwd: "/tmp",
+        });
+        fake.error(new Error("spawn failed"));
+        const res = await promise;
+        expect(res.exitCode).toBe(1);
+        expect(res.stderr).toContain("spawn failed");
+    });
+
+    it("kills process on abort signal", async () => {
+        const { spawn } = await import("node:child_process");
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const { runAgent } = await import("./spawn.ts");
+        const ac = new AbortController();
+        const promise = runAgent({
+            agent: { name: "a", description: "x", source: "bundle", filePath: "/tmp/a.md", systemPrompt: "" },
+            task: "t",
+            cwd: "/tmp",
+            signal: ac.signal,
+        });
+        ac.abort();
+        expect(fake.proc.kill).toHaveBeenCalledWith("SIGTERM");
+        fake.close(0);
+        await promise;
+    });
+});

package/extensions/claude-globals/index.test.ts

@@ -0,0 +1,77 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type Handler = (event: { systemPrompt: string }) => Promise<{ systemPrompt: string } | undefined>;
+
+interface CapturedPi {
+    on: (event: string, handler: Handler) => void;
+    handlers: Record<string, Handler>;
+}
+
+function makePi(): CapturedPi {
+    const handlers: Record<string, Handler> = {};
+    return {
+        handlers,
+        on: (event, handler) => {
+            handlers[event] = handler;
+        },
+    };
+}
+
+describe("claude-globals extension", () => {
+    let fakeHome: string;
+    const homeEnv = process.env.HOME;
+
+    beforeEach(() => {
+        fakeHome = mkdtempSync(join(tmpdir(), "claude-glob-"));
+        process.env.HOME = fakeHome;
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        rmSync(fakeHome, { recursive: true, force: true });
+        process.env.HOME = homeEnv;
+    });
+
+    it("appends ~/.claude/CLAUDE.md content inside a wrapper tag", async () => {
+        const claudeDir = join(fakeHome, ".claude");
+        const { mkdirSync } = await import("node:fs");
+        mkdirSync(claudeDir, { recursive: true });
+        writeFileSync(join(claudeDir, "CLAUDE.md"), "RULE ONE\nRULE TWO", "utf-8");
+
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+
+        const result = await pi.handlers.before_agent_start({ systemPrompt: "SYS" });
+        expect(result).toBeDefined();
+        expect(result?.systemPrompt).toContain("SYS");
+        expect(result?.systemPrompt).toContain("<claude-global-rules");
+        expect(result?.systemPrompt).toContain("RULE ONE");
+        expect(result?.systemPrompt).toContain("RULE TWO");
+        expect(result?.systemPrompt).toContain("</claude-global-rules>");
+    });
+
+    it("returns undefined when ~/.claude/CLAUDE.md does not exist", async () => {
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const result = await pi.handlers.before_agent_start({ systemPrompt: "SYS" });
+        expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when ~/.claude/CLAUDE.md is empty / whitespace", async () => {
+        const claudeDir = join(fakeHome, ".claude");
+        const { mkdirSync } = await import("node:fs");
+        mkdirSync(claudeDir, { recursive: true });
+        writeFileSync(join(claudeDir, "CLAUDE.md"), "   \n\n  ", "utf-8");
+
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const result = await pi.handlers.before_agent_start({ systemPrompt: "SYS" });
+        expect(result).toBeUndefined();
+    });
+});