@astrofoundry/pi-astro 0.16.1 → 0.18.1

package/extensions/astro-subagents/render.ts

@@ -0,0 +1,221 @@
+import * as os from "node:os";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Message } from "@earendil-works/pi-ai";
+import { getMarkdownTheme, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { finalOutput, isFailed, type RunResult, type UsageStats } from "./child.ts";
+
+export type Mode = "single" | "parallel" | "chain";
+
+export interface SubagentDetails {
+    mode: Mode;
+    results: RunResult[];
+}
+
+const COLLAPSED_ITEM_COUNT = 10;
+
+function formatTokens(count: number): string {
+    if (count < 1000) return count.toString();
+    if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+    if (count < 1000000) return `${Math.round(count / 1000)}k`;
+    return `${(count / 1000000).toFixed(1)}M`;
+}
+
+export function formatUsage(usage: UsageStats, model?: string): string {
+    const parts: string[] = [];
+    if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+    if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+    if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+    if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+    if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+    if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+    if (usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+    if (model) parts.push(model);
+    return parts.join(" ");
+}
+
+function aggregateUsage(results: RunResult[]): UsageStats {
+    const total: UsageStats = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+    for (const r of results) {
+        total.input += r.usage.input;
+        total.output += r.usage.output;
+        total.cacheRead += r.usage.cacheRead;
+        total.cacheWrite += r.usage.cacheWrite;
+        total.cost += r.usage.cost;
+        total.turns += r.usage.turns;
+    }
+    return total;
+}
+
+type Fg = (color: ThemeColor, text: string) => string;
+
+function str(value: unknown, fallback: string): string {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function shortenPath(p: string): string {
+    const home = os.homedir();
+    return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+export function formatToolCall(toolName: string, args: Record<string, unknown>, fg: Fg): string {
+    switch (toolName) {
+        case "bash": {
+            const command = str(args.command, "...");
+            return fg("muted", "$ ") + fg("toolOutput", command.length > 60 ? `${command.slice(0, 60)}...` : command);
+        }
+        case "read":
+        case "write":
+        case "edit": {
+            const filePath = shortenPath(str(args.file_path, str(args.path, "...")));
+            return fg("muted", `${toolName} `) + fg("accent", filePath);
+        }
+        case "ls":
+            return fg("muted", "ls ") + fg("accent", shortenPath(str(args.path, ".")));
+        case "find":
+            return fg("muted", "find ") + fg("accent", str(args.pattern, "*")) + fg("dim", ` in ${shortenPath(str(args.path, "."))}`);
+        case "grep":
+            return fg("muted", "grep ") + fg("accent", `/${str(args.pattern, "")}/`) + fg("dim", ` in ${shortenPath(str(args.path, "."))}`);
+        default: {
+            const preview = JSON.stringify(args);
+            return fg("accent", toolName) + fg("dim", ` ${preview.length > 50 ? `${preview.slice(0, 50)}...` : preview}`);
+        }
+    }
+}
+
+type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, unknown> };
+
+function displayItems(messages: Message[]): DisplayItem[] {
+    const items: DisplayItem[] = [];
+    for (const msg of messages) {
+        if (msg.role !== "assistant") continue;
+        for (const part of msg.content) {
+            if (part.type === "text") items.push({ type: "text", text: part.text });
+            else if (part.type === "toolCall") items.push({ type: "toolCall", name: part.name, args: part.arguments as Record<string, unknown> });
+        }
+    }
+    return items;
+}
+
+function statusIcon(r: RunResult, theme: Theme): string {
+    if (r.exitCode === -1) return theme.fg("warning", "⏳");
+    return isFailed(r) ? theme.fg("error", "✗") : theme.fg("success", "✓");
+}
+
+function renderItems(items: DisplayItem[], theme: Theme, expanded: boolean, limit?: number): string {
+    const toShow = limit ? items.slice(-limit) : items;
+    const skipped = limit && items.length > limit ? items.length - limit : 0;
+    const fg: Fg = (c, t) => theme.fg(c, t);
+    let text = skipped > 0 ? theme.fg("muted", `... ${skipped} earlier items\n`) : "";
+    for (const item of toShow) {
+        if (item.type === "text") text += `${theme.fg("toolOutput", expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n"))}\n`;
+        else text += `${theme.fg("muted", "→ ")}${formatToolCall(item.name, item.args, fg)}\n`;
+    }
+    return text.trimEnd();
+}
+
+interface CallArgs {
+    agent?: string;
+    task?: string;
+    tasks?: { agent: string; task: string }[];
+    chain?: { agent: string; task: string }[];
+}
+
+export function renderCall(args: CallArgs, theme: Theme): Text {
+    const title = theme.fg("toolTitle", theme.bold("subagent "));
+    const preview = (t: string, n: number) => (t.length > n ? `${t.slice(0, n)}...` : t);
+    if (args.chain && args.chain.length > 0) {
+        let text = title + theme.fg("accent", `chain (${args.chain.length} steps)`);
+        args.chain.slice(0, 3).forEach((step, i) => {
+            text += `\n  ${theme.fg("muted", `${i + 1}.`)} ${theme.fg("accent", step.agent)}${theme.fg("dim", ` ${preview(step.task.replace(/\{previous\}/g, "").trim(), 40)}`)}`;
+        });
+        if (args.chain.length > 3) text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
+        return new Text(text, 0, 0);
+    }
+    if (args.tasks && args.tasks.length > 0) {
+        let text = title + theme.fg("accent", `parallel (${args.tasks.length} tasks)`);
+        for (const t of args.tasks.slice(0, 3)) text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview(t.task, 40)}`)}`;
+        if (args.tasks.length > 3) text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`;
+        return new Text(text, 0, 0);
+    }
+    return new Text(`${title}${theme.fg("accent", args.agent ?? "...")}\n  ${theme.fg("dim", args.task ? preview(args.task, 60) : "...")}`, 0, 0);
+}
+
+function renderOne(r: RunResult, theme: Theme, expanded: boolean, label: string): Container | Text {
+    const items = displayItems(r.messages);
+    const output = finalOutput(r.messages);
+    const fg: Fg = (c, t) => theme.fg(c, t);
+    if (expanded) {
+        const c = new Container();
+        let header = `${statusIcon(r, theme)} ${theme.fg("toolTitle", theme.bold(label))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+        if (isFailed(r) && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+        c.addChild(new Text(header, 0, 0));
+        if (isFailed(r) && r.errorMessage) c.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
+        c.addChild(new Spacer(1));
+        c.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
+        for (const item of items) {
+            if (item.type === "toolCall") c.addChild(new Text(`${theme.fg("muted", "→ ")}${formatToolCall(item.name, item.args, fg)}`, 0, 0));
+        }
+        if (output) {
+            c.addChild(new Spacer(1));
+            c.addChild(new Markdown(output.trim(), 0, 0, getMarkdownTheme()));
+        } else if (items.length === 0) {
+            c.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
+        }
+        const usage = formatUsage(r.usage, r.model);
+        if (usage) c.addChild(new Text(theme.fg("dim", usage), 0, 0));
+        return c;
+    }
+    let text = `${statusIcon(r, theme)} ${theme.fg("toolTitle", theme.bold(label))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+    if (isFailed(r) && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+    else if (items.length === 0) text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`;
+    else {
+        text += `\n${renderItems(items, theme, false, COLLAPSED_ITEM_COUNT)}`;
+        if (items.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+    }
+    const usage = formatUsage(r.usage, r.model);
+    if (usage) text += `\n${theme.fg("dim", usage)}`;
+    return new Text(text, 0, 0);
+}
+
+export function renderResult(result: AgentToolResult<SubagentDetails>, expanded: boolean, theme: Theme): Container | Text {
+    const details = result.details;
+    if (!details || details.results.length === 0) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+    }
+    if (details.mode === "single") return renderOne(details.results[0], theme, expanded, details.results[0].agent);
+
+    const running = details.results.filter((r) => r.exitCode === -1).length;
+    const ok = details.results.filter((r) => r.exitCode !== -1 && !isFailed(r)).length;
+    const icon = running > 0 ? theme.fg("warning", "⏳") : ok === details.results.length ? theme.fg("success", "✓") : theme.fg("error", "✗");
+    const status = running > 0 ? `${details.results.length - running}/${details.results.length} done, ${running} running` : `${ok}/${details.results.length}`;
+    const header = `${icon} ${theme.fg("toolTitle", theme.bold(`${details.mode} `))}${theme.fg("accent", status)}`;
+
+    if (expanded && running === 0) {
+        const c = new Container();
+        c.addChild(new Text(header, 0, 0));
+        for (const r of details.results) {
+            c.addChild(new Spacer(1));
+            c.addChild(renderOne(r, theme, true, r.step !== undefined ? `Step ${r.step}: ${r.agent}` : r.agent));
+        }
+        const total = formatUsage(aggregateUsage(details.results));
+        if (total) {
+            c.addChild(new Spacer(1));
+            c.addChild(new Text(theme.fg("dim", `Total: ${total}`), 0, 0));
+        }
+        return c;
+    }
+    let text = header;
+    for (const r of details.results) {
+        const items = displayItems(r.messages);
+        text += `\n\n${theme.fg("muted", r.step !== undefined ? `─── Step ${r.step}: ` : "─── ")}${theme.fg("accent", r.agent)} ${statusIcon(r, theme)}`;
+        text += items.length === 0 ? `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}` : `\n${renderItems(items, theme, false, 5)}`;
+    }
+    if (running === 0) {
+        const total = formatUsage(aggregateUsage(details.results));
+        if (total) text += `\n\n${theme.fg("dim", `Total: ${total}`)}`;
+    }
+    if (!expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+    return new Text(text, 0, 0);
+}

package/extensions/specialist-gate/config.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { SpecialistEntry, SpecialistsConfig } from "./types.ts";
+
+export interface ConfigLoadResult {
+    config: SpecialistsConfig | null;
+    configPath: string;
+    errors: string[];
+}
+
+export function configPath(): string {
+    const dir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+    return join(dir, "specialists.json");
+}
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+
+function validateEntry(raw: unknown, errors: string[], where: string): SpecialistEntry | null {
+    if (typeof raw !== "object" || raw === null) {
+        errors.push(`${where}: entry is not an object`);
+        return null;
+    }
+    const r = raw as Record<string, unknown>;
+    const agent = r.agent;
+    const tool = r.tool;
+    const service = r.service;
+    const timeoutMs = r.timeoutMs;
+    if (typeof agent !== "string" || agent.length === 0) {
+        errors.push(`${where}: missing 'agent'`);
+        return null;
+    }
+    if (typeof tool !== "string" || !NAME.test(tool)) {
+        errors.push(`${where}: 'tool' must match ${NAME}`);
+        return null;
+    }
+    if (typeof service !== "string" || !NAME.test(service)) {
+        errors.push(`${where}: 'service' must match ${NAME}`);
+        return null;
+    }
+    if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        errors.push(`${where}: 'timeoutMs' must be a positive integer`);
+        return null;
+    }
+    return { agent, tool, service, timeoutMs };
+}
+
+export function validateConfig(raw: unknown, errors: string[]): SpecialistsConfig | null {
+    if (typeof raw !== "object" || raw === null) {
+        errors.push("config root is not an object");
+        return null;
+    }
+    const r = raw as Record<string, unknown>;
+    if (typeof r.entry !== "string" || !r.entry.startsWith("/")) {
+        errors.push("'entry' must be an absolute path");
+        return null;
+    }
+    if (typeof r.user !== "string" || !NAME.test(r.user)) {
+        errors.push(`'user' must match ${NAME}`);
+        return null;
+    }
+    if (!Array.isArray(r.specialists)) {
+        errors.push("'specialists' must be an array");
+        return null;
+    }
+    const specialists: SpecialistEntry[] = [];
+    r.specialists.forEach((item, i) => {
+        const entry = validateEntry(item, errors, `specialists[${i}]`);
+        if (entry) specialists.push(entry);
+    });
+    return { entry: r.entry, user: r.user, specialists };
+}
+
+export function loadConfig(): ConfigLoadResult {
+    const path = configPath();
+    const errors: string[] = [];
+    if (!existsSync(path)) return { config: null, configPath: path, errors };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+        return { config: validateConfig(parsed, errors), configPath: path, errors };
+    } catch (err) {
+        errors.push(`invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return { config: null, configPath: path, errors };
+    }
+}

package/extensions/specialist-gate/index.test.ts

@@ -0,0 +1,176 @@
+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>;
+
+interface RegisteredTool {
+    name: string;
+    execute: (id: string, input: { args: string[] }, signal?: AbortSignal) => Promise<{ content: { text: string }[] }>;
+}
+
+interface CapturedPi {
+    handlers: Record<string, Handler>;
+    tools: Map<string, RegisteredTool>;
+    exec: ReturnType<typeof vi.fn>;
+    on: (event: string, handler: Handler) => void;
+    registerTool: (tool: RegisteredTool) => void;
+    registerCommand: () => void;
+}
+
+function makePi(): CapturedPi {
+    const handlers: Record<string, Handler> = {};
+    const tools = new Map<string, RegisteredTool>();
+    return {
+        handlers,
+        tools,
+        exec: vi.fn().mockResolvedValue({ stdout: '{"ok":true}\n', stderr: "", code: 0, killed: false }),
+        on: (event, handler) => {
+            handlers[event] = handler;
+        },
+        registerTool: (tool) => {
+            tools.set(tool.name, tool);
+        },
+        registerCommand: () => {},
+    };
+}
+
+const config = {
+    entry: "/usr/local/bin/specialist-cli",
+    user: "specialist",
+    specialists: [
+        { agent: "astro.arcane", tool: "arcane", service: "arcane", timeoutMs: 1000 },
+        { agent: "astro.network", tool: "network", service: "network", timeoutMs: 1000 },
+    ],
+};
+
+describe("specialist-gate", () => {
+    let root: string;
+    const originalDir = process.env.PI_CODING_AGENT_DIR;
+    const originalAgent = process.env.ASTRO_SUBAGENT_AGENT;
+
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "spg-"));
+        process.env.PI_CODING_AGENT_DIR = root;
+        delete process.env.ASTRO_SUBAGENT_AGENT;
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+        process.env.PI_CODING_AGENT_DIR = originalDir;
+        if (originalAgent === undefined) delete process.env.ASTRO_SUBAGENT_AGENT;
+        else process.env.ASTRO_SUBAGENT_AGENT = originalAgent;
+    });
+
+    async function load(cfg?: unknown, agent?: string): Promise<CapturedPi> {
+        if (cfg !== undefined) {
+            mkdirSync(root, { recursive: true });
+            writeFileSync(join(root, "specialists.json"), typeof cfg === "string" ? cfg : JSON.stringify(cfg), "utf-8");
+        }
+        if (agent) process.env.ASTRO_SUBAGENT_AGENT = agent;
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        return pi;
+    }
+
+    const ctx = { ui: { notify: vi.fn() } };
+
+    it("registers no tool without a config file", async () => {
+        const pi = await load(undefined, "astro.arcane");
+        expect(pi.tools.size).toBe(0);
+    });
+
+    it("registers no tool outside a specialist child", async () => {
+        const pi = await load(config);
+        expect(pi.tools.size).toBe(0);
+    });
+
+    it("registers only the matching specialist's tool in its child", async () => {
+        const pi = await load(config, "astro.arcane");
+        expect([...pi.tools.keys()]).toEqual(["arcane"]);
+    });
+
+    it("runs the entry point through sudo with args after --", async () => {
+        const pi = await load(config, "astro.arcane");
+        const tool = pi.tools.get("arcane");
+        if (!tool) throw new Error("tool missing");
+        const result = await tool.execute("id", { args: ["projects", "list", "--limit", "5"] });
+        expect(pi.exec).toHaveBeenCalledWith(
+            "sudo",
+            ["-n", "-u", "specialist", "-H", "/usr/local/bin/specialist-cli", "arcane", "--caller", "astro.arcane", "--", "projects", "list", "--limit", "5"],
+            expect.objectContaining({ timeout: 1000 }),
+        );
+        expect(result.content[0].text).toBe('{"ok":true}');
+    });
+
+    it("throws with stderr when the entry point fails", async () => {
+        const pi = await load(config, "astro.arcane");
+        pi.exec.mockResolvedValueOnce({ stdout: "", stderr: "unknown subcommand", code: 2, killed: false });
+        const tool = pi.tools.get("arcane");
+        if (!tool) throw new Error("tool missing");
+        await expect(tool.execute("id", { args: ["nope"] })).rejects.toThrow(/code 2[\s\S]*unknown subcommand/);
+    });
+
+    it("blocks bash commands that reach the specialist CLIs", async () => {
+        const pi = await load(config);
+        for (const command of [
+            "arcane-cli projects list",
+            "sudo -u specialist ls",
+            "/usr/local/bin/specialist-cli arcane -- x",
+            "node ~/.specialists/bin/network-run sites",
+        ]) {
+            const decision = await pi.handlers.tool_call({ toolName: "bash", input: { command } }, ctx);
+            expect(decision, command).toEqual(expect.objectContaining({ block: true }));
+        }
+    });
+
+    it("does not block unrelated bash commands", async () => {
+        const pi = await load(config);
+        const decision = await pi.handlers.tool_call({ toolName: "bash", input: { command: "git push --dry-run" } }, ctx);
+        expect(decision).toBeUndefined();
+    });
+
+    it("blocks reads, writes, and edits under the specialist home", async () => {
+        const pi = await load(config);
+        for (const toolName of ["read", "write", "edit"]) {
+            const decision = await pi.handlers.tool_call(
+                { toolName, input: { path: "/Users/specialist/.specialists/secrets/arcane/ZITADEL_KEY_JSON" } },
+                ctx,
+            );
+            expect(decision, toolName).toEqual(expect.objectContaining({ block: true }));
+        }
+        const ok = await pi.handlers.tool_call({ toolName: "read", input: { path: "/Users/specialist-notes.md" } }, ctx);
+        expect(ok).toBeUndefined();
+    });
+
+    it("keeps the blocks with defaults when the config is invalid", async () => {
+        const pi = await load("{not json");
+        const decision = await pi.handlers.tool_call({ toolName: "bash", input: { command: "arcane-cli --help" } }, ctx);
+        expect(decision).toEqual(expect.objectContaining({ block: true }));
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("invalid JSON"), "warning");
+    });
+
+    it("rejects malformed entries but keeps valid ones", async () => {
+        const { validateConfig } = await import("./config.ts");
+        const errors: string[] = [];
+        const cfg = validateConfig(
+            {
+                entry: "/usr/local/bin/specialist-cli",
+                user: "specialist",
+                specialists: [
+                    { agent: "astro.arcane", tool: "arcane", service: "arcane", timeoutMs: 10 },
+                    { agent: "astro.bad", tool: "Bad Tool", service: "bad", timeoutMs: 10 },
+                    { agent: "astro.slow", tool: "slow", service: "slow", timeoutMs: -1 },
+                ],
+            },
+            errors,
+        );
+        expect(cfg?.specialists.map((s) => s.tool)).toEqual(["arcane"]);
+        expect(errors).toHaveLength(2);
+        expect(validateConfig({ entry: "relative/path", user: "specialist", specialists: [] }, errors)).toBeNull();
+    });
+});

package/extensions/specialist-gate/index.ts

@@ -0,0 +1,146 @@
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { loadConfig } from "./config.ts";
+import { AGENT_ENV } from "../astro-subagents/child.ts";
+import type { SpecialistEntry, SpecialistsConfig } from "./types.ts";
+
+/** Set by astro-subagents on every child session it spawns. */
+export const CHILD_AGENT_ENV = AGENT_ENV;
+
+const DEFAULT_USER = "specialist";
+const FIXED_COMMAND_MARKERS = ["specialist-cli", "arcane-cli"];
+
+export interface Guard {
+    user: string;
+    commandMarkers: string[];
+    protectedRoot: string;
+}
+
+export function buildGuard(config: SpecialistsConfig | null): Guard {
+    const user = config?.user ?? DEFAULT_USER;
+    const markers = new Set(FIXED_COMMAND_MARKERS);
+    markers.add(`-u ${user}`);
+    markers.add(`su ${user}`);
+    for (const entry of config?.specialists ?? []) markers.add(`${entry.service}-run`);
+    return { user, commandMarkers: [...markers], protectedRoot: `/Users/${user}` };
+}
+
+export function blockedCommandMarker(command: string, guard: Guard): string | null {
+    for (const marker of guard.commandMarkers) {
+        if (command.includes(marker)) return marker;
+    }
+    return null;
+}
+
+export function isProtectedPath(path: string, guard: Guard): boolean {
+    return path === guard.protectedRoot || path.startsWith(`${guard.protectedRoot}/`);
+}
+
+function delegateHint(config: SpecialistsConfig | null): string {
+    const names = (config?.specialists ?? []).map((s) => s.agent);
+    return names.length > 0 ? `Delegate to a specialist agent (${names.join(", ")}).` : "Delegate to a specialist agent.";
+}
+
+function pathsOf(event: ToolCallEvent): string[] {
+    const input = event.input as Record<string, unknown>;
+    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);
+            }
+        }
+    }
+    return paths;
+}
+
+export function decide(
+    event: ToolCallEvent,
+    guard: Guard,
+    config: SpecialistsConfig | null,
+): { block: true; reason: string } | undefined {
+    if (event.toolName === "bash") {
+        const command = (event.input as { command?: string }).command ?? "";
+        const marker = blockedCommandMarker(command, guard);
+        if (marker) {
+            return { block: true, reason: `specialist-gate: "${marker}" is reserved for specialists. ${delegateHint(config)}` };
+        }
+        return undefined;
+    }
+    if (event.toolName === "read" || event.toolName === "write" || event.toolName === "edit") {
+        for (const p of pathsOf(event)) {
+            if (isProtectedPath(p, guard)) {
+                return {
+                    block: true,
+                    reason: `specialist-gate: ${guard.protectedRoot} holds specialist credentials. ${delegateHint(config)}`,
+                };
+            }
+        }
+    }
+    return undefined;
+}
+
+export function entryArgs(config: SpecialistsConfig, entry: SpecialistEntry, args: string[]): string[] {
+    return ["-n", "-u", config.user, "-H", config.entry, entry.service, "--caller", entry.agent, "--", ...args];
+}
+
+const params = Type.Object({
+    args: Type.Array(Type.String(), {
+        description: "Subcommand and arguments for the specialist CLI, one array element per argument.",
+    }),
+});
+
+function registerSpecialistTool(pi: ExtensionAPI, config: SpecialistsConfig, entry: SpecialistEntry): void {
+    pi.registerTool({
+        name: entry.tool,
+        label: `Specialist: ${entry.service}`,
+        description: `Runs the ${entry.service} specialist CLI. Pass the subcommand and its arguments as an array. Output is JSON on success; errors carry the CLI's stderr.`,
+        promptGuidelines: [
+            `Use \`${entry.tool}\` for every operation in the ${entry.service} area. It is the only path to that service.`,
+            `Start with \`${entry.tool}\` and args ["--help"] when unsure which subcommands exist.`,
+        ],
+        parameters: params,
+        async execute(_toolCallId, input, signal) {
+            const result = await pi.exec("sudo", entryArgs(config, entry, input.args), {
+                signal,
+                timeout: entry.timeoutMs,
+            });
+            if (result.code !== 0) {
+                const detail = result.stderr.trim() || result.stdout.trim();
+                throw new Error(`${entry.service} specialist exited with code ${result.code}${detail ? `\n${detail}` : ""}`);
+            }
+            return { content: [{ type: "text", text: result.stdout.trim() || "(no output)" }], details: {} };
+        },
+    });
+}
+
+export default function specialistGateExtension(pi: ExtensionAPI): void {
+    const loaded = loadConfig();
+    const guard = buildGuard(loaded.config);
+    const childAgent = process.env[CHILD_AGENT_ENV];
+    const mine = childAgent ? (loaded.config?.specialists.find((s) => s.agent === childAgent) ?? null) : null;
+
+    if (loaded.config && mine) registerSpecialistTool(pi, loaded.config, mine);
+
+    pi.on("tool_call", async (event: ToolCallEvent) => decide(event, guard, loaded.config));
+
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        for (const error of loaded.errors) ctx.ui.notify(`specialist-gate: ${loaded.configPath}: ${error}`, "warning");
+        if (mine) ctx.ui.notify(`specialist-gate: ${mine.agent} has tool \`${mine.tool}\``, "info");
+    });
+
+    pi.registerCommand("specialists", {
+        description: "Show specialist-gate status",
+        handler: async (_args, ctx) => {
+            const lines = [
+                `config: ${loaded.configPath}${loaded.config ? "" : " (absent or invalid)"}`,
+                `protected: ${guard.protectedRoot}`,
+                `blocked bash markers: ${guard.commandMarkers.join(", ")}`,
+                `this session: ${mine ? `${mine.agent} → ${mine.tool}` : "no specialist tool"}`,
+            ];
+            ctx.ui.notify(lines.join("\n"), "info");
+        },
+    });
+}

package/extensions/specialist-gate/types.ts

@@ -0,0 +1,17 @@
+export interface SpecialistEntry {
+    /** Runtime agent name as pi-subagents reports it, e.g. `astro.arcane`. */
+    agent: string;
+    /** Tool name registered in that agent's session. */
+    tool: string;
+    /** Service argument passed to the entry point. */
+    service: string;
+    timeoutMs: number;
+}
+
+export interface SpecialistsConfig {
+    /** Root-owned sudo entry point, e.g. `/usr/local/bin/specialist-cli`. */
+    entry: string;
+    /** macOS user that owns keys and CLIs. */
+    user: string;
+    specialists: SpecialistEntry[];
+}