agent-tempo 1.3.1 → 1.4.0

package/dist/pi/probe.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_NODE_FLOOR = exports.PI_VERSION_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = void 0;
+exports.probePi = probePi;
+exports.meetsVersionFloor = meetsVersionFloor;
+exports.probeCopilotPiPreflight = probeCopilotPiPreflight;
+/**
+ * Pi dependency preflight — mirrors the opencode / claude-api optional-dep gate.
+ *
+ * `@earendil-works/pi-coding-agent` (and `@earendil-works/pi-ai`) are OPTIONAL
+ * dependencies requiring Node 22.19+. The extension only runs INSIDE Pi, so the
+ * runtime guarantees Pi is present — this probe exists for the headless path and
+ * for a clear, actionable error if someone wires the extension where Pi isn't
+ * installed.
+ *
+ * Uses `probeSdkInstall` (filesystem walk) rather than `require.resolve` because
+ * Pi packages ship ESM-only `exports` maps with no CJS-resolvable entry.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const sdk_probe_1 = require("../utils/sdk-probe");
+/** Canonical Pi package (the npm `@mariozechner/...` name is an alias). */
+exports.PI_PACKAGE = '@earendil-works/pi-coding-agent';
+/** Pi's model/typing helpers (`StringEnum`, providers). */
+exports.PI_AI_PACKAGE = '@earendil-works/pi-ai';
+/** Tested-pinned Pi version — drift is a maintainer decision (D6). */
+exports.TESTED_PI_VERSION = '~0.78';
+/**
+ * Minimum Pi version the integration requires. 0.78.0 covers the Pi fixes the
+ * cue-pump + headless paths rely on (#2860 / #5080 / #5115). Bumping this is a
+ * D6 maintainer decision; the headless/Copilot pre-flight hard-fails below it.
+ */
+exports.PI_VERSION_FLOOR = '0.78.0';
+/** Node floor imposed by the Pi packages (NOT by typebox or agent-tempo core). */
+exports.PI_NODE_FLOOR = '22.19.0';
+/**
+ * Check whether the Pi runtime packages are installed. Returns a structured
+ * result so callers choose whether to warn or hard-fail (the extension warns;
+ * a headless spawner would hard-fail).
+ */
+function probePi() {
+    if (!(0, sdk_probe_1.probeSdkInstall)(exports.PI_PACKAGE)) {
+        return {
+            available: false,
+            reason: `${exports.PI_PACKAGE} is not installed.\n` +
+                `Install it with: npm install -g ${exports.PI_PACKAGE}\n` +
+                `(requires Node >= ${exports.PI_NODE_FLOOR}).`,
+        };
+    }
+    return { available: true };
+}
+/**
+ * Pure semver FLOOR check: is `installed` >= `floor`? Compares major, then
+ * minor, then patch (a missing patch defaults to 0). Any pre-release/build
+ * suffix (`-beta`, `+sha`) is ignored — a pre-release of a version at/above the
+ * floor counts as meeting it. An unparseable `installed` returns `false`
+ * (conservative: unknown version is treated as below the floor).
+ */
+function meetsVersionFloor(installed, floor = exports.PI_VERSION_FLOOR) {
+    const parse = (v) => {
+        const m = v.trim().match(/^v?(\d+)\.(\d+)(?:\.(\d+))?/);
+        if (!m)
+            return [-1, -1, -1];
+        return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+    };
+    const [iMaj, iMin, iPat] = parse(installed);
+    if (iMaj < 0)
+        return false; // unparseable → below floor
+    const [fMaj, fMin, fPat] = parse(floor);
+    if (iMaj !== fMaj)
+        return iMaj > fMaj;
+    if (iMin !== fMin)
+        return iMin > fMin;
+    return iPat >= fPat;
+}
+/** Default `~/.pi/agent/auth.json` presence check. */
+function defaultAuthFileExists() {
+    return (0, fs_1.existsSync)((0, path_1.join)((0, os_1.homedir)(), '.pi', 'agent', 'auth.json'));
+}
+/**
+ * Hard pre-flight for recruiting a Copilot-backed Pi player (headless). Three
+ * gates, each with an actionable, `force: true`-bypassable error:
+ *   1. The Pi optional deps (`@earendil-works/pi-coding-agent` + `pi-ai`) are
+ *      installed.
+ *   2. The Pi SDK version meets {@link PI_VERSION_FLOOR}.
+ *   3. Copilot auth is present — either `COPILOT_GITHUB_TOKEN` in the env or a
+ *      mounted `~/.pi/agent/auth.json`.
+ *
+ * Mirrors the opencode / claude-code-headless recruit pre-flights. Returns a
+ * {@link PiProbeResult} so the caller (recruit) chooses warn vs hard-fail.
+ */
+function probeCopilotPiPreflight(deps = {}) {
+    const isInstalled = deps.isInstalled ?? ((pkg) => (0, sdk_probe_1.probeSdkInstall)(pkg));
+    const installedVersion = deps.installedVersion ?? ((pkg) => (0, sdk_probe_1.readSdkPackageVersion)(pkg));
+    const env = deps.env ?? process.env;
+    const authFileExists = deps.authFileExists ?? defaultAuthFileExists;
+    // 1. Optional Pi deps present.
+    const missing = [exports.PI_PACKAGE, exports.PI_AI_PACKAGE].filter((pkg) => !isInstalled(pkg));
+    if (missing.length > 0) {
+        return {
+            available: false,
+            reason: `Copilot-via-Pi requires the Pi optional dependencies (missing: ${missing.join(', ')}).\n` +
+                `Install with: npm install -g ${exports.PI_PACKAGE} ${exports.PI_AI_PACKAGE} (requires Node >= ${exports.PI_NODE_FLOOR}).\n` +
+                `Or recruit with force: true to bypass this pre-flight.`,
+        };
+    }
+    // 2. Version floor.
+    const version = installedVersion(exports.PI_PACKAGE);
+    if (!version) {
+        return {
+            available: false,
+            reason: `Could not read ${exports.PI_PACKAGE} version to verify the >= ${exports.PI_VERSION_FLOOR} floor.\n` +
+                `Reinstall ${exports.PI_PACKAGE}, or recruit with force: true to bypass.`,
+        };
+    }
+    if (!meetsVersionFloor(version, exports.PI_VERSION_FLOOR)) {
+        return {
+            available: false,
+            reason: `${exports.PI_PACKAGE} ${version} is below the required >= ${exports.PI_VERSION_FLOOR} floor ` +
+                `(covers Pi #2860/#5080/#5115).\n` +
+                `Upgrade with: npm install -g ${exports.PI_PACKAGE}@latest, or recruit with force: true to bypass.`,
+        };
+    }
+    // 3. Copilot auth.
+    if (!env.COPILOT_GITHUB_TOKEN && !authFileExists()) {
+        return {
+            available: false,
+            reason: `Copilot auth not found. Set COPILOT_GITHUB_TOKEN, or run \`pi /login\` (GitHub Copilot) ` +
+                `to write ~/.pi/agent/auth.json.\n` +
+                `Or recruit with force: true to bypass this pre-flight.`,
+        };
+    }
+    // 4. Model indexability (catch-early; runs only when BOTH the requested model
+    //    and a resolver are supplied — A4 injects pi-ai's getModel). Pi's Copilot
+    //    model set is compiled at build time from models.dev, so a model on the
+    //    user's subscription but unindexed resolves to `undefined` (NOT a throw,
+    //    NOT null — empirically confirmed). Fail the recruit cleanly here rather
+    //    than spawning a process getModel kills at the headless entry. A4's
+    //    getModel backstop covers the skip cases (no resolver / session-only).
+    if (deps.requestedModel && deps.resolveModel) {
+        const { provider, model } = deps.requestedModel;
+        if (deps.resolveModel(provider, model) === undefined) {
+            return {
+                available: false,
+                reason: `model "${provider}/${model}" is not in Pi's model index (getModel returned undefined).\n` +
+                    `Run \`pi --list-models\` for valid ids; the Copilot set is compiled from models.dev, ` +
+                    `so a model on your subscription but unindexed is rejected (Pi #4599/#2891).\n` +
+                    `Or recruit with force: true to bypass this pre-flight.`,
+            };
+        }
+    }
+    return { available: true };
+}

package/dist/pi/render-tools.d.ts

@@ -0,0 +1,17 @@
+import type { TempoToolDescriptor, TempoToolResult } from '../tools/descriptor';
+import type { ExtensionAPI, PiToolResult } from './pi-types';
+/**
+ * Map a neutral {@link TempoToolResult} onto Pi's `AgentToolResult` shape.
+ *
+ * Phase 0 confirmed Pi's result is `{ output, isError }` for a non-streaming
+ * tool (D12). The neutral `{ text, isError? }` maps directly: `text → output`,
+ * `isError` passes through.
+ */
+export declare function toPiResult(r: TempoToolResult): PiToolResult;
+/**
+ * Register every descriptor onto the Pi extension API. The TypeBox schema is
+ * derived per-tool from the zod shape; an unsupported zod construct throws
+ * `UnsupportedZodFeatureError` from the converter (fail-loud — D1), surfacing
+ * the offending `tool.field` so the parity test points at the exact site.
+ */
+export declare function renderToPi(pi: ExtensionAPI, descriptors: TempoToolDescriptor[]): void;

package/dist/pi/render-tools.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPiResult = toPiResult;
+exports.renderToPi = renderToPi;
+/**
+ * Pi front-end renderer — registers transport-neutral tool descriptors onto a
+ * Pi `ExtensionAPI` (the counterpart to `renderToMcp` in src/tools/descriptor.ts).
+ *
+ * The MCP renderer passes the zod param shape to `server.tool` raw; here we
+ * DERIVE a TypeBox schema from the same zod shape via the converter
+ * (`zod-to-typebox.ts`). zod stays the single source of truth — no dual-define,
+ * no drift. The CI parity test (test/pi-tool-parity.test.ts) asserts the MCP
+ * and Pi front-ends register the identical tool set with identical required
+ * params.
+ *
+ * OUTBOX-COMPLIANCE INVARIANT (load-bearing): `renderToPi` reuses the
+ * descriptor's `handler` VERBATIM — it never reimplements tool logic. The
+ * handler still routes through `handle.executeUpdate(submitOutboxUpdate, …)` on
+ * the player's OWN workflow handle. The Pi extension's WorkflowClient builds
+ * only that handle; there is ZERO `.signal()` to peer workflows.
+ *
+ * Determinism note: client-side only. src/pi imports the descriptor type FROM
+ * src/tools; never the reverse.
+ */
+const zod_to_typebox_1 = require("./zod-to-typebox");
+/**
+ * Map a neutral {@link TempoToolResult} onto Pi's `AgentToolResult` shape.
+ *
+ * Phase 0 confirmed Pi's result is `{ output, isError }` for a non-streaming
+ * tool (D12). The neutral `{ text, isError? }` maps directly: `text → output`,
+ * `isError` passes through.
+ */
+function toPiResult(r) {
+    return r.isError ? { output: r.text, isError: true } : { output: r.text };
+}
+/**
+ * Register every descriptor onto the Pi extension API. The TypeBox schema is
+ * derived per-tool from the zod shape; an unsupported zod construct throws
+ * `UnsupportedZodFeatureError` from the converter (fail-loud — D1), surfacing
+ * the offending `tool.field` so the parity test points at the exact site.
+ */
+function renderToPi(pi, descriptors) {
+    for (const d of descriptors) {
+        pi.registerTool({
+            name: d.name,
+            description: d.description,
+            parameters: (0, zod_to_typebox_1.zodShapeToTypeBox)(d.params, d.name),
+            execute: async (args) => toPiResult(await d.handler(args)),
+        });
+    }
+}

package/dist/pi/reset-pump.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reset pump (3d D14) — polls the session workflow's single-slot pending reset
+ * and performs a CLEAN-WIPE on the live Pi session, then acks it. Sibling to
+ * {@link CuePump}: Pi has no reverse-RPC from Temporal, so reset (an operator/
+ * conductor CONTROL op — it bypasses the MD-G tool gate) is delivered by polling
+ * `pendingReset` and acking via the race-safe `ackReset(resetId)` (the workflow
+ * clears the slot only if the id still matches, so a newer reset landing during
+ * the wipe is preserved for the next tick).
+ *
+ * D14 (maintainer-ruled): reset = clean-wipe via Pi `session.newSession()` (fresh
+ * context, NO replay). Seeded reset is a separate concern (`restart` +
+ * `loadFromState`), so a `fresh:false` here is defensively logged + acked (never
+ * silently wiped) — the reset tool only ever sends `fresh:true` today.
+ */
+import type { PendingReset } from '../types';
+import type { PiAgentSession } from './pi-types';
+/** Source of the pending reset + ack — satisfied by `PiWorkflowClient`. */
+export interface ResetSource {
+    fetchPendingReset(): Promise<PendingReset | null>;
+    ackReset(resetId: string): Promise<void>;
+}
+/** Resolves the CURRENT live Pi session at wipe time (re-acquired each tick — D11). */
+export type SessionResolver = () => PiAgentSession | null;
+export interface ResetPumpOptions {
+    source: ResetSource;
+    resolveSession: SessionResolver;
+    /** Poll interval (ms). */
+    intervalMs?: number;
+}
+export declare class ResetPump {
+    private readonly source;
+    private readonly resolveSession;
+    private readonly intervalMs;
+    private timer;
+    private draining;
+    constructor(opts: ResetPumpOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * One poll cycle: fetch the pending reset; if present + a live session is
+     * attached, perform the wipe and ack. Re-entrancy guarded so a slow tick never
+     * overlaps the next interval. Public for unit tests to drive directly.
+     */
+    tick(): Promise<void>;
+    /** Wipe (D14 clean-wipe) + deliver the "context wiped" notice. */
+    private performReset;
+}

package/dist/pi/reset-pump.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResetPump = void 0;
+const DEFAULT_POLL_MS = 1_000;
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+class ResetPump {
+    source;
+    resolveSession;
+    intervalMs;
+    timer = null;
+    draining = false;
+    constructor(opts) {
+        this.source = opts.source;
+        this.resolveSession = opts.resolveSession;
+        this.intervalMs = opts.intervalMs ?? DEFAULT_POLL_MS;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.tick().catch((err) => log('reset-pump tick failed:', err));
+        }, this.intervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * One poll cycle: fetch the pending reset; if present + a live session is
+     * attached, perform the wipe and ack. Re-entrancy guarded so a slow tick never
+     * overlaps the next interval. Public for unit tests to drive directly.
+     */
+    async tick() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            const pr = await this.source.fetchPendingReset();
+            if (!pr)
+                return;
+            const session = this.resolveSession();
+            if (!session)
+                return; // no live session yet — leave it pending; next tick retries
+            await this.performReset(session, pr);
+            await this.source.ackReset(pr.resetId);
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    /** Wipe (D14 clean-wipe) + deliver the "context wiped" notice. */
+    async performReset(session, pr) {
+        if (!pr.fresh) {
+            // D14: reset is clean-wipe ONLY. A seeded reset would be restart+loadFromState
+            // (not this path). Don't guess — log + fall through to ack (clear the slot).
+            log(`reset ${pr.resetId}: fresh=false — no wipe (seeded reset is restart's job)`);
+            return;
+        }
+        if (typeof session.newSession !== 'function') {
+            log(`reset ${pr.resetId}: session.newSession() unavailable — skipping wipe (will still ack)`);
+            return;
+        }
+        await session.newSession(); // clean-wipe: fresh context, no replay
+        const by = pr.requestedBy ? ` (requested by ${pr.requestedBy})` : '';
+        const notice = `[reset] context wiped — fresh start${by}.${pr.reason ? ` reason: ${pr.reason}` : ''}`;
+        log(notice);
+        // Surface the notice INTO the fresh session (after the wipe, so it survives),
+        // non-triggering so it doesn't kick off an unsolicited turn — the agent reads
+        // it on its next cue.
+        try {
+            await session.sendCustomMessage({ customType: 'system', content: notice, display: true }, { deliverAs: 'followUp', triggerTurn: false });
+        }
+        catch (err) {
+            log(`reset ${pr.resetId}: notice injection failed (non-fatal):`, err);
+        }
+    }
+}
+exports.ResetPump = ResetPump;

package/dist/pi/tool-capability.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tool capability classifier (3d / MD-C) — a PURE function mapping a tool name
+ * to its risk class. The 3d operator gate and the MD-C headless tool-access
+ * posture consume it; this module owns the MECHANISM, tempo-security owns the
+ * CONTENT (the name-sets below) and signs off on it.
+ *
+ *   - `'exec'`       — shell / arbitrary-code execution. HARD-BLOCKED when the
+ *                      headless tool-access policy is `restricted` (MD-C). The
+ *                      highest-danger class.
+ *   - `'high-blast'` — destructive or exfiltration-capable actions (file writes,
+ *                      network fetch, ensemble mutation). Allowed unsupervised,
+ *                      but routed to the OPERATOR GATE when an operator is armed.
+ *   - `'low-risk'`   — read-only / coordination. Always bypasses the gate.
+ *
+ * UNKNOWN tool names default to {@link UNKNOWN_DEFAULT} — a FAIL-SAFE choice
+ * (`'high-blast'`: never silently bypass a tool we don't recognize; gate it when
+ * an operator is armed). Whether an unknown tool should instead hard-block
+ * (`'exec'`) is a tempo-security posture call — see the cue to security.
+ *
+ * Matching is CASE-INSENSITIVE on the trimmed tool name. Pi's `tool_call`
+ * `toolName` is a bare string (built-ins like `bash`/`read`/`edit`/`write`/`grep`
+ * plus the natively-registered agent-tempo MCP tools), so we normalize before
+ * lookup.
+ *
+ * ⚠️ NAME-SET OWNERSHIP: the three Sets are tempo-security's posture content.
+ * They are a STARTER set (conductor's examples + Pi built-ins + the agent-tempo
+ * coordination/mutation tools) pending security's authoritative sign-off; amend
+ * the Set membership without touching the mechanism. The classifier behavior
+ * (and its tests) are keyed on representative names that won't move.
+ */
+/** Risk class for a tool, consumed by the 3d gate + MD-C policy. */
+export type ToolCapability = 'exec' | 'high-blast' | 'low-risk';
+/** Fail-safe class for an unrecognized tool name (never bypass the unknown). */
+export declare const UNKNOWN_DEFAULT: ToolCapability;
+/**
+ * Shell / arbitrary-code execution — hard-blocked at `restricted` (MD-C).
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ *
+ * CANONICAL exec denylist (single source of truth). The F1 refactor (3d) made
+ * `src/pi/extension.ts` import this set via `classify(name) === 'exec'` and
+ * REMOVED its former local `SHELL_TOOL_NAMES` — so the live restricted-mode gate
+ * now hard-blocks the full set including `powershell`/`pwsh`/`cmd`/`run` (the gap
+ * the old local list left open). Never re-declare a shell denylist elsewhere.
+ */
+export declare const EXEC_TOOLS: ReadonlySet<string>;
+/**
+ * Destructive / exfiltration-capable — gated when an operator is armed.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+export declare const HIGH_BLAST_TOOLS: ReadonlySet<string>;
+/**
+ * Read-only / coordination — always bypasses the gate.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+export declare const LOW_RISK_TOOLS: ReadonlySet<string>;
+/**
+ * Classify a tool name into its risk class. Pure + case-insensitive; unknown
+ * names fall through to {@link UNKNOWN_DEFAULT} (fail-safe — never bypass).
+ */
+export declare function classify(toolName: string): ToolCapability;

package/dist/pi/tool-capability.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Tool capability classifier (3d / MD-C) — a PURE function mapping a tool name
+ * to its risk class. The 3d operator gate and the MD-C headless tool-access
+ * posture consume it; this module owns the MECHANISM, tempo-security owns the
+ * CONTENT (the name-sets below) and signs off on it.
+ *
+ *   - `'exec'`       — shell / arbitrary-code execution. HARD-BLOCKED when the
+ *                      headless tool-access policy is `restricted` (MD-C). The
+ *                      highest-danger class.
+ *   - `'high-blast'` — destructive or exfiltration-capable actions (file writes,
+ *                      network fetch, ensemble mutation). Allowed unsupervised,
+ *                      but routed to the OPERATOR GATE when an operator is armed.
+ *   - `'low-risk'`   — read-only / coordination. Always bypasses the gate.
+ *
+ * UNKNOWN tool names default to {@link UNKNOWN_DEFAULT} — a FAIL-SAFE choice
+ * (`'high-blast'`: never silently bypass a tool we don't recognize; gate it when
+ * an operator is armed). Whether an unknown tool should instead hard-block
+ * (`'exec'`) is a tempo-security posture call — see the cue to security.
+ *
+ * Matching is CASE-INSENSITIVE on the trimmed tool name. Pi's `tool_call`
+ * `toolName` is a bare string (built-ins like `bash`/`read`/`edit`/`write`/`grep`
+ * plus the natively-registered agent-tempo MCP tools), so we normalize before
+ * lookup.
+ *
+ * ⚠️ NAME-SET OWNERSHIP: the three Sets are tempo-security's posture content.
+ * They are a STARTER set (conductor's examples + Pi built-ins + the agent-tempo
+ * coordination/mutation tools) pending security's authoritative sign-off; amend
+ * the Set membership without touching the mechanism. The classifier behavior
+ * (and its tests) are keyed on representative names that won't move.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOW_RISK_TOOLS = exports.HIGH_BLAST_TOOLS = exports.EXEC_TOOLS = exports.UNKNOWN_DEFAULT = void 0;
+exports.classify = classify;
+/** Fail-safe class for an unrecognized tool name (never bypass the unknown). */
+exports.UNKNOWN_DEFAULT = 'high-blast';
+/**
+ * Shell / arbitrary-code execution — hard-blocked at `restricted` (MD-C).
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ *
+ * CANONICAL exec denylist (single source of truth). The F1 refactor (3d) made
+ * `src/pi/extension.ts` import this set via `classify(name) === 'exec'` and
+ * REMOVED its former local `SHELL_TOOL_NAMES` — so the live restricted-mode gate
+ * now hard-blocks the full set including `powershell`/`pwsh`/`cmd`/`run` (the gap
+ * the old local list left open). Never re-declare a shell denylist elsewhere.
+ */
+exports.EXEC_TOOLS = new Set([
+    'bash',
+    'shell',
+    'exec',
+    'sh',
+    'powershell',
+    'pwsh',
+    'cmd',
+    'run',
+    'process',
+    'command',
+    'run_command',
+]);
+/**
+ * Destructive / exfiltration-capable — gated when an operator is armed.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+exports.HIGH_BLAST_TOOLS = new Set([
+    // Pi built-in mutating tools.
+    'write',
+    'edit',
+    'multiedit',
+    // Network exfiltration surface (arbitrary HTTP incl. POST). NOTE: `websearch`
+    // is LOW_RISK (read-only results) — only the fetch/browse family gates.
+    'webfetch',
+    'web_fetch',
+    'fetch',
+    'http_request',
+    'browser',
+    // agent-tempo tools that mutate the ensemble / spawn / tear down / control peers.
+    'recruit',
+    'destroy',
+    'restart',
+    'migrate',
+    'shutdown',
+    'release', // releases a held player — state change on a peer
+    'broadcast', // fans out to ALL players (amplification)
+    'schedule', // creates a durable autonomous trigger (unschedule is LOW_RISK)
+    'pause',
+    'play',
+    'restore', // re-spawns a detached player (process spawn)
+    // State / artifact destruction (irreversible).
+    'save_state',
+    'clear_state',
+    'coat_check_evict',
+    // Lineup spawn (full ensemble from YAML; save_lineup is LOW_RISK).
+    'load_lineup',
+    // Git state + disk mutation.
+    'worktree',
+    'stage',
+    'cancel_stage', // discards staged work (irreversible)
+    // Quality gates that block/unblock ensemble workflow progress.
+    'quality_gate',
+    'evaluate_gate',
+    // Drive/file mutation.
+    'copy_file',
+]);
+/**
+ * Read-only / coordination — always bypasses the gate.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+exports.LOW_RISK_TOOLS = new Set([
+    // Pi built-in read tools.
+    'read',
+    'grep',
+    'glob',
+    'ls',
+    // Read-only web search (no arbitrary POST — distinct from the web_fetch family).
+    'websearch',
+    'web_search',
+    // agent-tempo read-only / status / messaging coordination tools.
+    'cue',
+    'report',
+    'recall',
+    'listen',
+    'ensemble',
+    'who_am_i',
+    'set_name',
+    'set_part',
+    'set_ensemble_description', // metadata only, no blast radius
+    'hosts',
+    'attachment_info',
+    'agent_types',
+    'schedules',
+    'stages',
+    'gates',
+    // Read-only state / coat-check (coat_check_put is bounded 32KB + TTL'd + visible).
+    'fetch_state',
+    'coat_check_put',
+    'coat_check_get',
+    'coat_check_list',
+    // Removes a future trigger — blast was at schedule-time, not here.
+    'unschedule',
+    // Writes the coordinator YAML (not arbitrary file write; blast is at load_lineup).
+    'save_lineup',
+]);
+/**
+ * Classify a tool name into its risk class. Pure + case-insensitive; unknown
+ * names fall through to {@link UNKNOWN_DEFAULT} (fail-safe — never bypass).
+ */
+function classify(toolName) {
+    const name = toolName.trim().toLowerCase();
+    if (exports.EXEC_TOOLS.has(name))
+        return 'exec';
+    if (exports.HIGH_BLAST_TOOLS.has(name))
+        return 'high-blast';
+    if (exports.LOW_RISK_TOOLS.has(name))
+        return 'low-risk';
+    return exports.UNKNOWN_DEFAULT;
+}