@astrofoundry/pi-astro 0.6.5 → 0.6.6

package/README.md

@@ -61,6 +61,7 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
 - `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`
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
 
 **Bundled subagents** (callable via `astro_agent`):

package/extensions/gemini-image/index.test.ts

@@ -371,6 +371,49 @@ describe("gemini-image extension", () => {
         rmSync(sourceDir, { recursive: true, force: true });
     });
 
+    it("summary includes exact cost for Imagen (flat pricing)", async () => {
+        generateImagesMock.mockResolvedValue({
+            generatedImages: [
+                { image: { imageBytes: "A", mimeType: "image/png" } },
+                { image: { imageBytes: "B", mimeType: "image/png" } },
+            ],
+        });
+        const { tool } = await load();
+        const res = await tool.execute(
+            "t",
+            {
+                prompt: "x",
+                model: "imagen-4.0-fast-generate-001",
+                number_of_images: 2,
+                skip_confirm: true,
+            },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        const text = (res.content as Array<{ type: string; text?: string }>)[0].text as string;
+        expect(text).toMatch(/Cost:\s+\$0\.0400/); // 2 × 0.02
+        expect(res.details.actualCostUsd).toBeCloseTo(0.04, 4);
+    });
+
+    it("summary includes cost using usageMetadata.promptTokenCount when present", async () => {
+        generateContentMock.mockResolvedValue({
+            candidates: [{ content: { parts: [{ inlineData: { mimeType: "image/png", data: "X" } }] } }],
+            usageMetadata: { promptTokenCount: 1000 },
+        });
+        const { tool } = await load();
+        const res = await tool.execute(
+            "t",
+            { prompt: "x", model: "gemini-3-pro-image-preview", skip_confirm: true },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        const text = (res.content as Array<{ type: string; text?: string }>)[0].text as string;
+        expect(text).toMatch(/Cost:/);
+        expect(text).toContain("1000 input tokens");
+    });
+
     it("Imagen config: numberOfImages + negative_prompt + seed + person_generation all pass through", async () => {
         generateImagesMock.mockResolvedValue({
             generatedImages: [{ image: { imageBytes: "X", mimeType: "image/png" } }],

package/extensions/gemini-image/index.ts

@@ -19,7 +19,7 @@ import {
     type ImageModel,
 } from "./models.ts";
 import { parseTweaks } from "./parseTweaks.ts";
-import { estimateCost, formatUsd, hasPricing } from "./pricing.ts";
+import { computeActualCost, estimateCost, formatUsd, hasPricing } from "./pricing.ts";
 import { formatResolution, resolveResolution } from "./resolution.ts";
 
 const DEFAULT_SAVE_SUBDIR = ".gemini-images";
@@ -131,12 +131,17 @@ interface DecodedImage {
     mimeType: string;
 }
 
+interface CallResult {
+    images: DecodedImage[];
+    inputTokens?: number;
+}
+
 async function callGeminiNative(
     ai: GoogleGenAI,
     model: string,
     p: Params,
     signal: AbortSignal | undefined,
-): Promise<DecodedImage[]> {
+): Promise<CallResult> {
     const imageConfig: Record<string, string> = {};
     if (p.aspect_ratio) imageConfig.aspectRatio = p.aspect_ratio;
     if (p.image_size) imageConfig.imageSize = p.image_size;
@@ -176,7 +181,9 @@ async function callGeminiNative(
             }
         }
     }
-    return images;
+    const inputTokens = (response as { usageMetadata?: { promptTokenCount?: number } }).usageMetadata
+        ?.promptTokenCount;
+    return { images, inputTokens };
 }
 
 async function callImagen(
@@ -184,7 +191,7 @@ async function callImagen(
     model: string,
     p: Params,
     signal: AbortSignal | undefined,
-): Promise<DecodedImage[]> {
+): Promise<CallResult> {
     const config: Record<string, unknown> = {};
     if (p.aspect_ratio) config.aspectRatio = p.aspect_ratio;
     if (p.image_size) config.imageSize = p.image_size;
@@ -209,7 +216,7 @@ async function callImagen(
             });
         }
     }
-    return images;
+    return { images };
 }
 
 function saveImages(images: DecodedImage[], dir: string, prompt: string): string[] {
@@ -342,19 +349,27 @@ export default function geminiImageExtension(pi: ExtensionAPI): void {
             const finalModel = (final.model as ImageModel | undefined) ?? DEFAULT_MODEL;
 
             const ai = new GoogleGenAI({ apiKey });
-            const images = isImagen(finalModel)
+            const call = isImagen(finalModel)
                 ? await callImagen(ai, finalModel, final, signal)
                 : await callGeminiNative(ai, finalModel, final, signal);
 
-            if (images.length === 0) {
+            if (call.images.length === 0) {
                 throw new Error("Model returned no images.");
             }
 
             const saveDir = final.save_to ? resolve(ctx.cwd, final.save_to) : join(ctx.cwd, DEFAULT_SAVE_SUBDIR);
-            const savedPaths = saveImages(images, saveDir, final.prompt);
+            const savedPaths = saveImages(call.images, saveDir, final.prompt);
+
+            const actual = hasPricing(finalModel)
+                ? computeActualCost(finalModel, {
+                      numberOfImages: call.images.length,
+                      imageSize: final.image_size,
+                      inputTokens: call.inputTokens,
+                  })
+                : undefined;
 
             const summaryLines = [
-                `Generated ${images.length} image${images.length > 1 ? "s" : ""} with ${finalModel}.`,
+                `Generated ${call.images.length} image${call.images.length > 1 ? "s" : ""} with ${finalModel}.`,
                 `Prompt: "${final.prompt}"`,
             ];
             if (final.aspect_ratio) summaryLines.push(`Aspect ratio: ${final.aspect_ratio}`);
@@ -362,16 +377,25 @@ export default function geminiImageExtension(pi: ExtensionAPI): void {
             if (final.negative_prompt) summaryLines.push(`Negative: "${final.negative_prompt}"`);
             if (final.person_generation) summaryLines.push(`People: ${final.person_generation}`);
             if (final.seed !== undefined) summaryLines.push(`Seed: ${final.seed}`);
+            if (actual) {
+                const exact = isImagen(finalModel) || call.inputTokens !== undefined;
+                summaryLines.push(`Cost: ${exact ? formatUsd(actual.usd) : `~${formatUsd(actual.usd)}`} (${actual.breakdown})`);
+            }
             summaryLines.push(`Saved to:\n  ${savedPaths.join("\n  ")}`);
 
             const content: AgentToolResult<unknown>["content"] = [
                 { type: "text", text: summaryLines.join("\n") },
-                ...images.map((img) => ({ type: "image" as const, data: img.data, mimeType: img.mimeType })),
+                ...call.images.map((img) => ({ type: "image" as const, data: img.data, mimeType: img.mimeType })),
             ];
 
             return {
                 content,
-                details: { model: finalModel, images: images.length, savedPaths },
+                details: {
+                    model: finalModel,
+                    images: call.images.length,
+                    savedPaths,
+                    actualCostUsd: actual?.usd,
+                },
             };
         },
     });

package/extensions/gemini-image/pricing.test.ts

@@ -93,3 +93,46 @@ describe("hasPricing", () => {
         expect(hasPricing("imagen-4.0-fast-generate-001")).toBe(true);
     });
 });
+
+describe("computeActualCost", () => {
+    it("Imagen: flat × count, exact", async () => {
+        const { computeActualCost } = await import("./pricing.ts");
+        const r = computeActualCost("imagen-4.0-fast-generate-001", { numberOfImages: 3 });
+        expect(r.usd).toBeCloseTo(0.06, 5);
+        expect(r.breakdown).toContain("0.02");
+    });
+
+    it("Gemini native with real input tokens: exact formula", async () => {
+        const { computeActualCost } = await import("./pricing.ts");
+        const r = computeActualCost("gemini-3-pro-image-preview", {
+            numberOfImages: 2,
+            imageSize: "2K",
+            inputTokens: 500,
+        });
+        // output: 2 × 0.134 = 0.268; input: 500 / 1M × 2.00 = 0.001; total ~0.269
+        expect(r.usd).toBeCloseTo(0.269, 3);
+        expect(r.breakdown).toContain("500 input tokens");
+    });
+
+    it("Gemini native with missing input tokens: falls back to 0", async () => {
+        const { computeActualCost } = await import("./pricing.ts");
+        const r = computeActualCost("gemini-2.5-flash-image", { numberOfImages: 1 });
+        expect(r.usd).toBeGreaterThanOrEqual(0);
+        expect(r.breakdown).toContain("0 input tokens");
+    });
+
+    it("4K output uses higher rate", async () => {
+        const { computeActualCost } = await import("./pricing.ts");
+        const at2k = computeActualCost("gemini-3-pro-image-preview", {
+            numberOfImages: 1,
+            imageSize: "2K",
+            inputTokens: 0,
+        });
+        const at4k = computeActualCost("gemini-3-pro-image-preview", {
+            numberOfImages: 1,
+            imageSize: "4K",
+            inputTokens: 0,
+        });
+        expect(at4k.usd).toBeGreaterThan(at2k.usd);
+    });
+});

package/extensions/gemini-image/pricing.ts

@@ -97,6 +97,38 @@ export function formatUsd(usd: number): string {
     return `$${usd.toFixed(4)}`;
 }
 
+export interface ActualUsage {
+    inputTokens?: number;
+    numberOfImages: number;
+    imageSize?: "1K" | "2K" | "4K";
+}
+
+export interface ActualCostResult {
+    usd: number;
+    breakdown: string;
+}
+
+export function computeActualCost(model: ImageModel, usage: ActualUsage): ActualCostResult {
+    const price = PRICES[model];
+    if (price.kind === "flat") {
+        return {
+            usd: price.perImage * usage.numberOfImages,
+            breakdown: `${usage.numberOfImages} × $${price.perImage.toFixed(2)}/image`,
+        };
+    }
+    const perImage =
+        usage.imageSize === "4K" ? price.outputPerImage4K : price.outputPerImage1Kor2K;
+    const outputCost = perImage * usage.numberOfImages;
+    const inputTokens = usage.inputTokens ?? 0;
+    const inputCost = (inputTokens / 1_000_000) * price.inputPer1M;
+    return {
+        usd: inputCost + outputCost,
+        breakdown:
+            `${usage.numberOfImages} × $${perImage.toFixed(3)} (${usage.imageSize ?? "1K/2K"}) + ` +
+            `${inputTokens} input tokens`,
+    };
+}
+
 export function hasPricing(model: ImageModel): boolean {
     return model in PRICES;
 }

package/extensions/security-guard/config.test.ts

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("config", () => {
+    let root: string;
+    const originalDir = process.env.PI_CODING_AGENT_DIR;
+    const originalDryRun = process.env.PI_SECURITY_GUARD_DRY_RUN;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "sg-cfg-"));
+        process.env.PI_CODING_AGENT_DIR = root;
+        delete process.env.PI_SECURITY_GUARD_DRY_RUN;
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+        process.env.PI_CODING_AGENT_DIR = originalDir;
+        if (originalDryRun === undefined) delete process.env.PI_SECURITY_GUARD_DRY_RUN;
+        else process.env.PI_SECURITY_GUARD_DRY_RUN = originalDryRun;
+    });
+
+    it("uses defaults when config file missing", async () => {
+        const { loadConfig } = await import("./config.ts");
+        const r = loadConfig();
+        expect(r.configExists).toBe(false);
+        expect(r.rules.operations.length).toBeGreaterThan(0);
+        expect(r.errors).toEqual([]);
+    });
+
+    it("loads user JSON rules overriding defaults when non-empty", async () => {
+        writeFileSync(
+            join(root, "security-guard.json"),
+            JSON.stringify({
+                operations: [{ pattern: "myop", action: "block" }],
+                writes: [{ pattern: "*.secret", action: "prompt" }],
+            }),
+            "utf-8",
+        );
+        const { loadConfig } = await import("./config.ts");
+        const r = loadConfig();
+        expect(r.configExists).toBe(true);
+        expect(r.rules.operations).toEqual([{ pattern: "myop", action: "block" }]);
+        expect(r.rules.writes).toEqual([{ pattern: "*.secret", action: "prompt" }]);
+        // reads missing → defaults used
+        expect(r.rules.reads.length).toBeGreaterThan(0);
+    });
+
+    it("invalid JSON falls back to defaults and records error", async () => {
+        writeFileSync(join(root, "security-guard.json"), "{not json", "utf-8");
+        const { loadConfig } = await import("./config.ts");
+        const r = loadConfig();
+        expect(r.errors.length).toBeGreaterThan(0);
+        expect(r.rules.operations.length).toBeGreaterThan(0);
+    });
+
+    it("malformed rule (bad action) is skipped with error", async () => {
+        writeFileSync(
+            join(root, "security-guard.json"),
+            JSON.stringify({
+                operations: [
+                    { pattern: "ok", action: "block" },
+                    { pattern: "bad", action: "nuke-from-orbit" },
+                    { pattern: "", action: "prompt" }, // empty pattern
+                    "not-an-object",
+                ],
+            }),
+            "utf-8",
+        );
+        const { loadConfig } = await import("./config.ts");
+        const r = loadConfig();
+        expect(r.rules.operations).toEqual([{ pattern: "ok", action: "block" }]);
+        expect(r.errors.length).toBeGreaterThanOrEqual(3);
+    });
+
+    it("non-array section logs error and falls back to default for that section", async () => {
+        writeFileSync(
+            join(root, "security-guard.json"),
+            JSON.stringify({ operations: "not an array" }),
+            "utf-8",
+        );
+        const { loadConfig } = await import("./config.ts");
+        const r = loadConfig();
+        expect(r.errors.some((e) => e.includes("operations"))).toBe(true);
+    });
+
+    it("ensureExampleConfig creates .example file once", async () => {
+        const { ensureExampleConfig } = await import("./config.ts");
+        mkdirSync(root, { recursive: true });
+        ensureExampleConfig();
+        const p = join(root, "security-guard.json.example");
+        expect(existsSync(p)).toBe(true);
+        const first = readFileSync(p, "utf-8");
+        // Running again doesn't overwrite / doesn't throw
+        ensureExampleConfig();
+        expect(readFileSync(p, "utf-8")).toBe(first);
+    });
+
+    it("isDryRun flips with env var", async () => {
+        const { isDryRun } = await import("./config.ts");
+        expect(isDryRun()).toBe(false);
+        process.env.PI_SECURITY_GUARD_DRY_RUN = "1";
+        expect(isDryRun()).toBe(true);
+    });
+});

package/extensions/security-guard/config.ts

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_RULES } from "./defaults.ts";
+import type { RuleAction, SecurityRule, SecurityRules } from "./types.ts";
+
+export interface ConfigLoadResult {
+    rules: SecurityRules;
+    configPath: string;
+    configExists: boolean;
+    errors: string[];
+}
+
+function configPath(): string {
+    const dir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+    return join(dir, "security-guard.json");
+}
+
+function examplePath(): string {
+    return `${configPath()}.example`;
+}
+
+const VALID_ACTIONS: readonly RuleAction[] = ["prompt", "block", "allow"];
+
+function validateRule(raw: unknown, errors: string[], where: string): SecurityRule | null {
+    if (typeof raw !== "object" || raw === null) {
+        errors.push(`${where}: rule is not an object`);
+        return null;
+    }
+    const r = raw as Record<string, unknown>;
+    if (typeof r.pattern !== "string" || r.pattern.length === 0) {
+        errors.push(`${where}: missing or empty 'pattern' string`);
+        return null;
+    }
+    if (typeof r.action !== "string" || !(VALID_ACTIONS as readonly string[]).includes(r.action)) {
+        errors.push(`${where}: action must be one of ${VALID_ACTIONS.join(", ")}`);
+        return null;
+    }
+    return { pattern: r.pattern, action: r.action as RuleAction };
+}
+
+function validateRules(raw: unknown, errors: string[]): SecurityRules {
+    const out: SecurityRules = { operations: [], writes: [], reads: [] };
+    if (typeof raw !== "object" || raw === null) {
+        errors.push("config root is not an object");
+        return out;
+    }
+    const r = raw as Record<string, unknown>;
+    for (const section of ["operations", "writes", "reads"] as const) {
+        const list = r[section];
+        if (list === undefined) continue;
+        if (!Array.isArray(list)) {
+            errors.push(`${section}: expected array, got ${typeof list}`);
+            continue;
+        }
+        for (let i = 0; i < list.length; i++) {
+            const rule = validateRule(list[i], errors, `${section}[${i}]`);
+            if (rule) out[section].push(rule);
+        }
+    }
+    return out;
+}
+
+export function loadConfig(): ConfigLoadResult {
+    const path = configPath();
+    const errors: string[] = [];
+    if (!existsSync(path)) {
+        return { rules: DEFAULT_RULES, configPath: path, configExists: false, errors };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+        const rules = validateRules(parsed, errors);
+        const merged: SecurityRules = {
+            operations: rules.operations.length > 0 ? rules.operations : DEFAULT_RULES.operations,
+            writes: rules.writes.length > 0 ? rules.writes : DEFAULT_RULES.writes,
+            reads: rules.reads.length > 0 ? rules.reads : DEFAULT_RULES.reads,
+        };
+        return { rules: merged, configPath: path, configExists: true, errors };
+    } catch (err) {
+        errors.push(`invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return { rules: DEFAULT_RULES, configPath: path, configExists: true, errors };
+    }
+}
+
+const EXAMPLE_CONTENT = `{
+  "_comment": "Copy this file to security-guard.json to activate. Patterns support globs: * matches one path segment, ** matches any number, ? matches one char. ~/ expands to your home directory. Longest matching pattern wins, so narrow 'allow' rules override broader 'block' rules.",
+  "operations": [
+    { "pattern": "rm -rf /", "action": "block" },
+    { "pattern": "mkfs", "action": "block" },
+    { "pattern": "dd if=", "action": "block" },
+    { "pattern": "> /dev/", "action": "block" },
+    { "pattern": "> /dev/null", "action": "allow" },
+    { "pattern": "rm -rf", "action": "prompt" },
+    { "pattern": "sudo", "action": "prompt" }
+  ],
+  "writes": [
+    { "pattern": "**/.env", "action": "block" },
+    { "pattern": "**/.env.*", "action": "block" },
+    { "pattern": "~/.ssh/**", "action": "block" },
+    { "pattern": "~/.aws/**", "action": "block" },
+    { "pattern": "/etc/**", "action": "prompt" }
+  ],
+  "reads": [
+    { "pattern": "~/.ssh/**", "action": "block" },
+    { "pattern": "~/.aws/credentials", "action": "block" },
+    { "pattern": "**/.env", "action": "prompt" }
+  ]
+}
+`;
+
+export function ensureExampleConfig(): void {
+    const path = examplePath();
+    if (existsSync(path)) return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, EXAMPLE_CONTENT, "utf-8");
+}
+
+export function isDryRun(): boolean {
+    return process.env.PI_SECURITY_GUARD_DRY_RUN === "1";
+}

package/extensions/security-guard/defaults.ts

@@ -0,0 +1,38 @@
+import type { SecurityRules } from "./types.ts";
+
+/**
+ * Conservative baseline rules. Users override via ~/.pi/agent/security-guard.json.
+ * Patterns support globs (`*`, `**`, `?`) and `~` expansion.
+ */
+export const DEFAULT_RULES: SecurityRules = {
+    operations: [
+        { pattern: "rm -rf /", action: "block" },
+        { pattern: ":(){ :|:&", action: "block" }, // fork bomb fragment
+        { pattern: "mkfs", action: "block" },
+        { pattern: "dd if=", action: "block" },
+        { pattern: "> /dev/sd", action: "block" },
+        { pattern: "> /dev/null", action: "allow" },
+        { pattern: "> /dev/", action: "block" },
+        { pattern: "rm -rf", action: "prompt" },
+        { pattern: "sudo", action: "prompt" },
+        { pattern: "chmod -R 777", action: "prompt" },
+    ],
+    writes: [
+        { pattern: "**/.env", action: "block" },
+        { pattern: "**/.env.*", action: "block" },
+        { pattern: "~/.ssh/**", action: "block" },
+        { pattern: "~/.aws/**", action: "block" },
+        { pattern: "~/.gnupg/**", action: "block" },
+        { pattern: "/etc/**", action: "prompt" },
+        { pattern: "~/.bash_history", action: "prompt" },
+        { pattern: "~/.zsh_history", action: "prompt" },
+    ],
+    reads: [
+        { pattern: "~/.ssh/**", action: "block" },
+        { pattern: "~/.aws/credentials", action: "block" },
+        { pattern: "~/.aws/**", action: "prompt" },
+        { pattern: "~/.gnupg/**", action: "block" },
+        { pattern: "**/.env", action: "prompt" },
+        { pattern: "**/.env.*", action: "prompt" },
+    ],
+};

package/extensions/security-guard/index.test.ts

@@ -0,0 +1,296 @@
+import { mkdirSync, 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: Record<string, unknown>, ctx: unknown) => Promise<unknown>;
+type CommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
+
+interface CapturedPi {
+    commands: Map<string, { description?: string; handler: CommandHandler }>;
+    handlers: Record<string, Handler>;
+    registerCommand: (name: string, opts: { description?: string; handler: CommandHandler }) => void;
+    on: (event: string, handler: Handler) => void;
+}
+
+function makePi(): CapturedPi {
+    const commands = new Map();
+    const handlers: Record<string, Handler> = {};
+    return {
+        commands,
+        handlers,
+        registerCommand: (name, opts) => {
+            commands.set(name, opts);
+        },
+        on: (event, handler) => {
+            handlers[event] = handler;
+        },
+    };
+}
+
+interface Ctx {
+    cwd: string;
+    hasUI: boolean;
+    ui: {
+        notify: ReturnType<typeof vi.fn>;
+        confirm: ReturnType<typeof vi.fn>;
+    };
+}
+
+function makeCtx(opts: { cwd?: string; hasUI?: boolean; allow?: boolean } = {}): Ctx {
+    return {
+        cwd: opts.cwd ?? "/tmp/cwd",
+        hasUI: opts.hasUI ?? true,
+        ui: {
+            notify: vi.fn(),
+            confirm: vi.fn().mockResolvedValue(opts.allow ?? true),
+        },
+    };
+}
+
+describe("security-guard tool_call hook", () => {
+    let root: string;
+    const originalDir = process.env.PI_CODING_AGENT_DIR;
+    const originalDryRun = process.env.PI_SECURITY_GUARD_DRY_RUN;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "sg-ext-"));
+        process.env.PI_CODING_AGENT_DIR = root;
+        delete process.env.PI_SECURITY_GUARD_DRY_RUN;
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+        process.env.PI_CODING_AGENT_DIR = originalDir;
+        if (originalDryRun === undefined) delete process.env.PI_SECURITY_GUARD_DRY_RUN;
+        else process.env.PI_SECURITY_GUARD_DRY_RUN = originalDryRun;
+    });
+
+    async function load(rules?: Record<string, unknown>): Promise<{ pi: CapturedPi }> {
+        if (rules) {
+            mkdirSync(root, { recursive: true });
+            writeFileSync(join(root, "security-guard.json"), JSON.stringify(rules), "utf-8");
+        }
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        return { pi };
+    }
+
+    it("registers tool_call handler + /security-guard command", async () => {
+        const { pi } = await load();
+        expect(pi.handlers.tool_call).toBeDefined();
+        expect(pi.commands.has("security-guard")).toBe(true);
+    });
+
+    it("blocks bash command matching 'rm -rf /' (default block rule)", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = (await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "rm -rf / && echo done" } },
+            ctx,
+        )) as { block?: boolean; reason?: string } | undefined;
+        expect(result?.block).toBe(true);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/Blocked/), "warning");
+    });
+
+    it("allows benign bash commands (no rule match)", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "ls -la" } },
+            ctx,
+        );
+        expect(result).toBeUndefined();
+    });
+
+    it("'> /dev/null' allow rule overrides broader '> /dev/' block rule", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "echo hi > /dev/null" } },
+            ctx,
+        );
+        expect(result).toBeUndefined();
+    });
+
+    it("prompt rule: user confirms → allowed", async () => {
+        const { pi } = await load({
+            operations: [{ pattern: "testcmd", action: "prompt" }],
+        });
+        const ctx = makeCtx({ allow: true });
+        const result = await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "testcmd now" } },
+            ctx,
+        );
+        expect(result).toBeUndefined();
+        expect(ctx.ui.confirm).toHaveBeenCalled();
+    });
+
+    it("prompt rule: user denies → blocked", async () => {
+        const { pi } = await load({
+            operations: [{ pattern: "testcmd", action: "prompt" }],
+        });
+        const ctx = makeCtx({ allow: false });
+        const result = (await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "testcmd now" } },
+            ctx,
+        )) as { block?: boolean; reason?: string };
+        expect(result?.block).toBe(true);
+    });
+
+    it("prompt rule without UI → blocked with reason", async () => {
+        const { pi } = await load({
+            operations: [{ pattern: "testcmd", action: "prompt" }],
+        });
+        const ctx = makeCtx({ hasUI: false });
+        const result = (await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "testcmd" } },
+            ctx,
+        )) as { block?: boolean };
+        expect(result?.block).toBe(true);
+    });
+
+    it("write to .env is blocked", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx({ cwd: "/repo" });
+        const result = (await pi.handlers.tool_call(
+            { toolName: "write", input: { path: ".env" } },
+            ctx,
+        )) as { block?: boolean };
+        expect(result?.block).toBe(true);
+    });
+
+    it("edit batch: one entry hits a protected path → whole edit blocked", async () => {
+        const { pi } = await load({
+            writes: [{ pattern: "**/protected.ts", action: "block" }],
+        });
+        const ctx = makeCtx({ cwd: "/repo" });
+        const result = (await pi.handlers.tool_call(
+            {
+                toolName: "edit",
+                input: {
+                    multi: [
+                        { path: "safe.ts", oldText: "a", newText: "b" },
+                        { path: "sub/protected.ts", oldText: "x", newText: "y" },
+                    ],
+                },
+            },
+            ctx,
+        )) as { block?: boolean };
+        expect(result?.block).toBe(true);
+    });
+
+    it("edit patch mode: extracts paths from '*** Add/Update/Delete File:' headers", async () => {
+        const { pi } = await load({
+            writes: [{ pattern: "**/secret.ts", action: "block" }],
+        });
+        const ctx = makeCtx({ cwd: "/repo" });
+        const patch = "*** Begin Patch\n*** Add File: src/secret.ts\n+x\n*** End Patch";
+        const result = (await pi.handlers.tool_call(
+            { toolName: "edit", input: { patch } },
+            ctx,
+        )) as { block?: boolean };
+        expect(result?.block).toBe(true);
+    });
+
+    it("read of ~/.ssh/id_rsa is blocked", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = (await pi.handlers.tool_call(
+            { toolName: "read", input: { path: "~/.ssh/id_rsa" } },
+            ctx,
+        )) as { block?: boolean };
+        expect(result?.block).toBe(true);
+    });
+
+    it("other tool names pass through untouched", async () => {
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = await pi.handlers.tool_call(
+            { toolName: "grep", input: { pattern: "foo" } },
+            ctx,
+        );
+        expect(result).toBeUndefined();
+    });
+
+    it("DRY-RUN mode: would-be-blocked passes through with notify prefix", async () => {
+        process.env.PI_SECURITY_GUARD_DRY_RUN = "1";
+        const { pi } = await load();
+        const ctx = makeCtx();
+        const result = await pi.handlers.tool_call(
+            { toolName: "bash", input: { command: "rm -rf /" } },
+            ctx,
+        );
+        expect(result).toBeUndefined(); // NOT blocked
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/DRY-RUN/), "warning");
+    });
+});
+
+describe("security-guard command", () => {
+    let root: string;
+    const originalDir = process.env.PI_CODING_AGENT_DIR;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "sg-cmd-"));
+        process.env.PI_CODING_AGENT_DIR = root;
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+        process.env.PI_CODING_AGENT_DIR = originalDir;
+    });
+
+    it("status sub-command prints rule counts", async () => {
+        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.commands.get("security-guard")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/operations=/), "info");
+    });
+
+    it("reload re-reads config + notifies", async () => {
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        mkdirSync(root, { recursive: true });
+        writeFileSync(
+            join(root, "security-guard.json"),
+            JSON.stringify({ operations: [{ pattern: "new-one", action: "block" }] }),
+            "utf-8",
+        );
+        const ctx = makeCtx();
+        await pi.commands.get("security-guard")!.handler("reload", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/reloaded/), "info");
+    });
+
+    it("test sub-command reports match", async () => {
+        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.commands.get("security-guard")!.handler("test bash rm -rf /", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/block/), "info");
+    });
+
+    it("test with unknown kind warns", async () => {
+        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.commands.get("security-guard")!.handler("test foo bar", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/usage/), "warning");
+    });
+
+    it("test reports no match as 'would be allowed'", async () => {
+        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.commands.get("security-guard")!.handler("test bash ls -la", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/no match/), "info");
+    });
+});

package/extensions/security-guard/index.ts

@@ -0,0 +1,173 @@
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent } from "@mariozechner/pi-coding-agent";
+import { ensureExampleConfig, isDryRun, loadConfig } from "./config.ts";
+import { findMatchingRule, normalizePath } from "./rules.ts";
+import type { SecurityRule, SecurityRules } from "./types.ts";
+
+interface Decision {
+    block: boolean;
+    reason?: string;
+}
+
+async function evaluate(
+    label: string,
+    target: string,
+    rules: readonly SecurityRule[],
+    ctx: ExtensionContext,
+): Promise<Decision> {
+    const rule = findMatchingRule(target, rules);
+    if (!rule || rule.action === "allow") return { block: false };
+
+    const dryRun = isDryRun();
+    const prefix = dryRun ? "[security-guard DRY-RUN] " : "";
+
+    if (rule.action === "block") {
+        ctx.ui.notify(
+            `${prefix}Blocked ${label}: matched pattern "${rule.pattern}"`,
+            "warning",
+        );
+        if (dryRun) return { block: false };
+        return {
+            block: true,
+            reason: `Blocked by security-guard: pattern "${rule.pattern}"`,
+        };
+    }
+
+    // prompt
+    if (!ctx.hasUI) {
+        if (dryRun) return { block: false };
+        return {
+            block: true,
+            reason: "security-guard: confirmation required but no UI available",
+        };
+    }
+    const confirmed = await ctx.ui.confirm(
+        `Security check — ${label}`,
+        `Matched pattern "${rule.pattern}"\n\nTarget: ${target}\n\nAllow this operation?`,
+    );
+    if (confirmed) return { block: false };
+    ctx.ui.notify(`${prefix}Denied ${label}`, "warning");
+    if (dryRun) return { block: false };
+    return { block: true, reason: "Denied by user via security-guard" };
+}
+
+function extractEditPaths(input: Record<string, unknown>): string[] {
+    const paths: string[] = [];
+    if (typeof input.path === "string") paths.push(input.path);
+    const multi = input.multi;
+    if (Array.isArray(multi)) {
+        for (const item of multi) {
+            if (item && typeof item === "object" && typeof (item as { path?: unknown }).path === "string") {
+                paths.push((item as { path: string }).path);
+            }
+        }
+    }
+    const patch = input.patch;
+    if (typeof patch === "string") {
+        const re = /^\*\*\* (?:Add File|Update File|Delete File):\s+(.+)$/gm;
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(patch)) !== null) {
+            paths.push(m[1].trim());
+        }
+    }
+    return paths;
+}
+
+async function handleToolCall(
+    event: ToolCallEvent,
+    ctx: ExtensionContext,
+    rules: SecurityRules,
+): Promise<{ block?: boolean; reason?: string } | undefined> {
+    switch (event.toolName) {
+        case "bash": {
+            const command = (event.input as { command?: string }).command ?? "";
+            const decision = await evaluate("bash command", command, rules.operations, ctx);
+            if (decision.block) return { block: true, reason: decision.reason };
+            return undefined;
+        }
+        case "write": {
+            const target = normalizePath(String((event.input as { path?: string }).path ?? ""), ctx.cwd);
+            const decision = await evaluate(`write to ${target}`, target, rules.writes, ctx);
+            if (decision.block) return { block: true, reason: decision.reason };
+            return undefined;
+        }
+        case "edit": {
+            const paths = extractEditPaths(event.input as Record<string, unknown>);
+            for (const raw of paths) {
+                const target = normalizePath(raw, ctx.cwd);
+                const decision = await evaluate(`edit of ${target}`, target, rules.writes, ctx);
+                if (decision.block) return { block: true, reason: decision.reason };
+            }
+            return undefined;
+        }
+        case "read": {
+            const target = normalizePath(String((event.input as { path?: string }).path ?? ""), ctx.cwd);
+            const decision = await evaluate(`read of ${target}`, target, rules.reads, ctx);
+            if (decision.block) return { block: true, reason: decision.reason };
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+
+export default function securityGuardExtension(pi: ExtensionAPI): void {
+    ensureExampleConfig();
+    let loaded = loadConfig();
+
+    pi.registerCommand("security-guard", {
+        description: "Security guard status / reload / test. Usage: /security-guard [status|reload|test <bash|write|read> <input>]",
+        handler: async (args, ctx) => {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const sub = parts[0] ?? "status";
+
+            if (sub === "reload") {
+                loaded = loadConfig();
+                const n =
+                    loaded.rules.operations.length +
+                    loaded.rules.writes.length +
+                    loaded.rules.reads.length;
+                ctx.ui.notify(
+                    `security-guard reloaded: ${n} rules${loaded.errors.length > 0 ? `; ${loaded.errors.length} errors` : ""}`,
+                    loaded.errors.length > 0 ? "warning" : "info",
+                );
+                return;
+            }
+
+            if (sub === "test") {
+                const kind = parts[1];
+                const input = parts.slice(2).join(" ");
+                if (!kind || !input || !["bash", "write", "read"].includes(kind)) {
+                    ctx.ui.notify("usage: /security-guard test <bash|write|read> <input>", "warning");
+                    return;
+                }
+                const rules =
+                    kind === "bash"
+                        ? loaded.rules.operations
+                        : kind === "write"
+                        ? loaded.rules.writes
+                        : loaded.rules.reads;
+                const target = kind === "bash" ? input : normalizePath(input, ctx.cwd);
+                const rule = findMatchingRule(target, rules);
+                ctx.ui.notify(
+                    rule
+                        ? `match: pattern "${rule.pattern}" -> ${rule.action}`
+                        : `no match (would be allowed)`,
+                    "info",
+                );
+                return;
+            }
+
+            // status (default)
+            const { rules, configPath, configExists, errors } = loaded;
+            const lines = [
+                `config: ${configPath}${configExists ? "" : " (not found — using defaults)"}`,
+                `operations=${rules.operations.length} writes=${rules.writes.length} reads=${rules.reads.length}`,
+                isDryRun() ? "dry-run: ON (PI_SECURITY_GUARD_DRY_RUN=1)" : "dry-run: off",
+            ];
+            if (errors.length > 0) lines.push(`errors: ${errors.join("; ")}`);
+            ctx.ui.notify(lines.join(" | "), "info");
+        },
+    });
+
+    pi.on("tool_call", async (event, ctx) => handleToolCall(event, ctx, loaded.rules));
+}

package/extensions/security-guard/rules.test.ts

@@ -0,0 +1,96 @@
+import { homedir } from "node:os";
+import { describe, expect, it } from "vitest";
+import { expandHome, findMatchingRule, matchesPattern, normalizePath } from "./rules.ts";
+
+describe("expandHome", () => {
+    it("expands ~/foo", () => {
+        expect(expandHome("~/foo")).toBe(`${homedir()}/foo`);
+    });
+
+    it("expands bare ~", () => {
+        expect(expandHome("~")).toBe(homedir());
+    });
+
+    it("leaves non-tilde paths unchanged", () => {
+        expect(expandHome("/etc/hosts")).toBe("/etc/hosts");
+        expect(expandHome("foo/bar")).toBe("foo/bar");
+    });
+});
+
+describe("normalizePath", () => {
+    it("resolves relative paths against cwd", () => {
+        expect(normalizePath("foo.txt", "/tmp")).toBe("/tmp/foo.txt");
+    });
+
+    it("keeps absolute paths", () => {
+        expect(normalizePath("/abs/path", "/tmp")).toBe("/abs/path");
+    });
+
+    it("expands ~", () => {
+        expect(normalizePath("~/a", "/tmp")).toBe(`${homedir()}/a`);
+    });
+});
+
+describe("matchesPattern", () => {
+    it("substring match on bash command", () => {
+        expect(matchesPattern("sudo rm -rf /tmp/x", { pattern: "rm -rf", action: "prompt" })).toBe(true);
+    });
+
+    it("substring does NOT match when absent", () => {
+        expect(matchesPattern("ls -la", { pattern: "rm -rf", action: "prompt" })).toBe(false);
+    });
+
+    it("glob ** matches deep paths", () => {
+        expect(matchesPattern("/Users/x/.ssh/id_rsa", { pattern: "~/.ssh/**", action: "block" })).toBe(false);
+        // Reason: the test path's home isn't the CURRENT user's home. Glob is anchored.
+        const real = `${homedir()}/.ssh/id_rsa`;
+        expect(matchesPattern(real, { pattern: "~/.ssh/**", action: "block" })).toBe(true);
+    });
+
+    it("glob * does NOT cross /", () => {
+        expect(matchesPattern("/a/b/c", { pattern: "/a/*", action: "block" })).toBe(false);
+        expect(matchesPattern("/a/b", { pattern: "/a/*", action: "block" })).toBe(true);
+    });
+
+    it("glob ? matches single char", () => {
+        expect(matchesPattern("/tmp/a.env", { pattern: "/tmp/?.env", action: "block" })).toBe(true);
+        expect(matchesPattern("/tmp/ab.env", { pattern: "/tmp/?.env", action: "block" })).toBe(false);
+    });
+
+    it("character class [abc]", () => {
+        expect(matchesPattern("/tmp/a", { pattern: "/tmp/[abc]", action: "block" })).toBe(true);
+        expect(matchesPattern("/tmp/z", { pattern: "/tmp/[abc]", action: "block" })).toBe(false);
+    });
+
+    it("glob **/.env matches any depth", () => {
+        expect(matchesPattern("/src/app/.env", { pattern: "**/.env", action: "block" })).toBe(true);
+        expect(matchesPattern("/.env", { pattern: "**/.env", action: "block" })).toBe(true);
+    });
+
+    it("metacharacters in non-glob pattern are escaped (fall back to substring)", () => {
+        // Pattern has no *, ?, [ — substring path used; no regex injection
+        expect(matchesPattern("something", { pattern: "some(thing)", action: "block" })).toBe(false);
+        expect(matchesPattern("some(thing)", { pattern: "some(thing)", action: "block" })).toBe(true);
+    });
+});
+
+describe("findMatchingRule — longest wins", () => {
+    const rules = [
+        { pattern: "> /dev/", action: "block" as const },
+        { pattern: "> /dev/null", action: "allow" as const },
+    ];
+
+    it("allow /dev/null overrides block /dev/", () => {
+        const r = findMatchingRule("echo hi > /dev/null", rules);
+        expect(r?.action).toBe("allow");
+    });
+
+    it("block /dev/sda still blocks when no narrower rule exists", () => {
+        const r = findMatchingRule("echo hi > /dev/sda", rules);
+        expect(r?.action).toBe("block");
+    });
+
+    it("no match returns null", () => {
+        expect(findMatchingRule("ls -la", rules)).toBeNull();
+    });
+});

package/extensions/security-guard/rules.ts

@@ -0,0 +1,90 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import type { SecurityRule } from "./types.ts";
+
+export function expandHome(pattern: string): string {
+    if (pattern === "~") return homedir();
+    if (pattern.startsWith("~/")) return `${homedir()}/${pattern.slice(2)}`;
+    return pattern;
+}
+
+/**
+ * Normalize a filesystem path for matching: expand `~`, resolve relative paths
+ * against cwd. Non-filesystem strings (bash commands) should NOT go through this.
+ */
+export function normalizePath(p: string, cwd: string): string {
+    const expanded = expandHome(p);
+    return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+}
+
+/**
+ * Convert a glob pattern to a RegExp source. Supports:
+ *   ?       any single non-separator char
+ *   *       any run of non-separator chars
+ *   **      any run of chars including separators
+ *   [abc]   character class
+ * All other regex metacharacters are escaped.
+ */
+function globToRegex(glob: string): RegExp {
+    let src = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                src += ".*";
+                i++;
+            } else {
+                src += "[^/]*";
+            }
+        } else if (c === "?") {
+            src += "[^/]";
+        } else if (c === "[") {
+            const end = glob.indexOf("]", i);
+            if (end === -1) {
+                src += "\\[";
+            } else {
+                src += glob.slice(i, end + 1);
+                i = end;
+            }
+        } else if (/[.+^${}()|\\]/.test(c)) {
+            src += `\\${c}`;
+        } else {
+            src += c;
+        }
+    }
+    return new RegExp(`^${src}$`);
+}
+
+function isGlob(pattern: string): boolean {
+    return /[*?[]/.test(pattern);
+}
+
+/**
+ * Does `text` match `rule.pattern`? For globs, matches as a whole path / whole
+ * string. For non-glob patterns, falls back to substring match (friendlier for
+ * bash commands and filename fragments).
+ */
+export function matchesPattern(text: string, rule: SecurityRule): boolean {
+    const expanded = expandHome(rule.pattern);
+    if (isGlob(rule.pattern)) {
+        const re = globToRegex(expanded);
+        return re.test(text);
+    }
+    return text.includes(expanded) || text.includes(rule.pattern);
+}
+
+/**
+ * Longest-match wins, so narrow `allow` exceptions override broad `block` rules
+ * (e.g. `> /dev/` = block, `> /dev/null` = allow).
+ */
+export function findMatchingRule(text: string, rules: readonly SecurityRule[]): SecurityRule | null {
+    let best: SecurityRule | null = null;
+    for (const rule of rules) {
+        if (matchesPattern(text, rule)) {
+            if (best === null || rule.pattern.length > best.pattern.length) {
+                best = rule;
+            }
+        }
+    }
+    return best;
+}

package/extensions/security-guard/types.ts

@@ -0,0 +1,12 @@
+export type RuleAction = "prompt" | "block" | "allow";
+
+export interface SecurityRule {
+    pattern: string;
+    action: RuleAction;
+}
+
+export interface SecurityRules {
+    operations: SecurityRule[];
+    writes: SecurityRule[];
+    reads: SecurityRule[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"