@astrofoundry/pi-astro 0.6.4 → 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,8 @@ 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";
 
@@ -130,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;
@@ -175,7 +181,9 @@ async function callGeminiNative(
             }
         }
     }
-    return images;
+    const inputTokens = (response as { usageMetadata?: { promptTokenCount?: number } }).usageMetadata
+        ?.promptTokenCount;
+    return { images, inputTokens };
 }
 
 async function callImagen(
@@ -183,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;
@@ -208,7 +216,7 @@ async function callImagen(
             });
         }
     }
-    return images;
+    return { images };
 }
 
 function saveImages(images: DecodedImage[], dir: string, prompt: string): string[] {
@@ -233,12 +241,16 @@ function saveImages(images: DecodedImage[], dir: string, prompt: string): string
 
 function renderPreview(model: ImageModel, p: Params, estimate: { estimatedUsd: number; breakdown: string }): string {
     const nImages = isImagen(model) ? p.number_of_images ?? 1 : 1;
+    const aspect = p.aspect_ratio ?? "1:1";
+    const size = p.image_size ?? "1K";
+    const resolution = formatResolution(resolveResolution(model, aspect, size));
     const lines: string[] = [];
     lines.push(`Model: ${model}`);
     lines.push(`Prompt: "${p.prompt}"`);
-    if (p.image_size) lines.push(`Size: ${p.image_size}`);
-    if (p.aspect_ratio) lines.push(`Aspect ratio: ${p.aspect_ratio}`);
-    lines.push(`Images: ${nImages}`);
+    lines.push(`Aspect: ${aspect}${p.aspect_ratio ? "" : " (default)"}`);
+    lines.push(`Size: ${size}${p.image_size ? "" : " (default)"}`);
+    lines.push(`Resolution: ${resolution}`);
+    lines.push(`Images: ${nImages}${p.number_of_images === undefined && isImagen(model) ? " (default)" : ""}`);
     if (p.negative_prompt) lines.push(`Negative: "${p.negative_prompt.slice(0, 80)}"`);
     if (p.seed !== undefined) lines.push(`Seed: ${p.seed}`);
     if (p.person_generation) lines.push(`People: ${p.person_generation}`);
@@ -337,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}`);
@@ -357,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/gemini-image/resolution.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { formatResolution, resolveResolution } from "./resolution.ts";
+
+describe("resolveResolution", () => {
+    it("defaults to 1:1 1K = 1024×1024", () => {
+        const r = resolveResolution("gemini-2.5-flash-image", undefined, undefined);
+        expect(r.width).toBe(1024);
+        expect(r.height).toBe(1024);
+        expect(r.approximate).toBe(false);
+    });
+
+    it("scales 2K as 2x", () => {
+        const r = resolveResolution("gemini-2.5-flash-image", "1:1", "2K");
+        expect(r.width).toBe(2048);
+        expect(r.height).toBe(2048);
+    });
+
+    it("scales 4K as 4x", () => {
+        const r = resolveResolution("gemini-3-pro-image-preview", "1:1", "4K");
+        expect(r.width).toBe(4096);
+        expect(r.height).toBe(4096);
+    });
+
+    it("16:9 at 1K → 1344×768", () => {
+        const r = resolveResolution("gemini-2.5-flash-image", "16:9", "1K");
+        expect(r.width).toBe(1344);
+        expect(r.height).toBe(768);
+    });
+
+    it("21:9 at 1K → 1536×672", () => {
+        const r = resolveResolution("gemini-2.5-flash-image", "21:9", "1K");
+        expect(r.width).toBe(1536);
+        expect(r.height).toBe(672);
+    });
+
+    it("Imagen flagged as approximate", () => {
+        const r = resolveResolution("imagen-4.0-generate-001", "1:1", "1K");
+        expect(r.approximate).toBe(true);
+    });
+
+    it("unknown aspect falls back to 1:1", () => {
+        const r = resolveResolution("gemini-2.5-flash-image", "7:3", "1K");
+        expect(r.width).toBe(1024);
+        expect(r.height).toBe(1024);
+    });
+});
+
+describe("formatResolution", () => {
+    it("exact Gemini is shown without tilde", () => {
+        expect(formatResolution({ width: 1024, height: 1024, approximate: false })).toBe("1024×1024");
+    });
+
+    it("approximate Imagen gets tilde prefix", () => {
+        expect(formatResolution({ width: 1024, height: 1024, approximate: true })).toBe("~1024×1024");
+    });
+});

package/extensions/gemini-image/resolution.ts

@@ -0,0 +1,62 @@
+/**
+ * Resolve the expected output resolution for a given (model, aspect_ratio, image_size).
+ *
+ * Base table is the documented Gemini 2.5 Flash Image matrix. 2K/4K scale the
+ * base by 2x/4x. Imagen's published resolutions vary per model and aren't in
+ * the public docs at the same granularity, so we use the same base and flag
+ * the result as approximate.
+ */
+
+import { isImagen, type ImageModel } from "./models.ts";
+
+type AspectRatio =
+    | "1:1"
+    | "2:3"
+    | "3:2"
+    | "3:4"
+    | "4:3"
+    | "4:5"
+    | "5:4"
+    | "9:16"
+    | "16:9"
+    | "21:9";
+
+// Gemini 2.5 Flash Image 1K dimensions, per ai.google.dev/gemini-api/docs/image-generation.
+const BASE_1K: Record<AspectRatio, [number, number]> = {
+    "1:1": [1024, 1024],
+    "2:3": [832, 1248],
+    "3:2": [1248, 832],
+    "3:4": [864, 1184],
+    "4:3": [1184, 864],
+    "4:5": [896, 1152],
+    "5:4": [1152, 896],
+    "9:16": [768, 1344],
+    "16:9": [1344, 768],
+    "21:9": [1536, 672],
+};
+
+export interface ResolutionInfo {
+    width: number;
+    height: number;
+    approximate: boolean;
+}
+
+export function resolveResolution(
+    model: ImageModel,
+    aspectRatio: string | undefined,
+    imageSize: "1K" | "2K" | "4K" | undefined,
+): ResolutionInfo {
+    const ratio = (aspectRatio ?? "1:1") as AspectRatio;
+    const base = BASE_1K[ratio] ?? BASE_1K["1:1"];
+    const size = imageSize ?? "1K";
+    const multiplier = size === "4K" ? 4 : size === "2K" ? 2 : 1;
+    return {
+        width: base[0] * multiplier,
+        height: base[1] * multiplier,
+        approximate: isImagen(model),
+    };
+}
+
+export function formatResolution(info: ResolutionInfo): string {
+    return `${info.approximate ? "~" : ""}${info.width}×${info.height}`;
+}

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" },
+    ],
+};