macro-agent 0.1.12 → 0.2.0

package/dist/dispatch/mail-inbound-reuse-consumer.js

@@ -0,0 +1,325 @@
+/**
+ * Mail-Inbound Reuse Consumer
+ *
+ * Receives hub-driven `x-dispatch/work` envelopes addressed to **non-sidecar**
+ * agents — long-lived team workers, coordinators, etc. — and drives them
+ * through the dispatch turn using their existing session, then posts the
+ * summary back as a mail turn.
+ *
+ * Mirrors `mail-inbound-consumer.ts` but with three semantic differences:
+ *
+ *   1. Filters envelopes addressed to ANY non-sidecar agent (the existing
+ *      consumer filters for the dispatcher recipient).
+ *   2. Does **not** spawn — it drives the existing agent's session via
+ *      `agentManager.prompt(agentId, prompt)` and watches for `done()` in
+ *      the update stream.
+ *   3. Tracks `inflightDispatches` per agentId. A second envelope arriving
+ *      while the same agent is already processing a dispatch is rejected
+ *      with `recipient_busy` so the orchestrator can retry against another
+ *      agent (or fall back to fresh-spawn). Reject is **dispatch-scoped**
+ *      — non-dispatch work on the agent (peer messages, user chat) does
+ *      NOT trigger the busy reject; that work stacks naturally.
+ *
+ * Reply path: captures `args.summary` from the done() tool call's rawInput
+ * directly off the update stream, so it works for both parented and
+ * parentless target agents (the parented branch in `handlers-v2` does NOT
+ * stash `_lastSummary` — only parentless agents do — but we don't need
+ * that path because we observe done() in-stream).
+ *
+ * @module dispatch/mail-inbound-reuse-consumer
+ */
+import { collapsePermissionsForAutonomous, } from "./loadout-translation.js";
+import { setPermissionOverlay, clearPermissionOverlay, } from "./permission-overlay.js";
+const SEEN_TASK_TTL_MS = 60 * 60 * 1000;
+/**
+ * Wire the mail-inbound reuse consumer.
+ *
+ * Returns a `stop()` handle that detaches the inbox listener.
+ */
+export function createMailInboundReuseConsumer(opts) {
+    const { dispatcherAgentId, inboxEvents, agentManager, agentStore, getSidecar, log = (msg) => console.log(msg), } = opts;
+    // agentId → inflight dispatch state. Used both to gate concurrent
+    // dispatches against the same agent and to look up the conversation
+    // when posting the reply.
+    const inflightDispatches = new Map();
+    // taskId → expiresAt: idempotency guard mirroring mail-inbound-consumer.
+    const seenTaskIds = new Map();
+    function pruneSeenTaskIds() {
+        const now = Date.now();
+        for (const [id, expiresAt] of seenTaskIds) {
+            if (expiresAt <= now)
+                seenTaskIds.delete(id);
+        }
+    }
+    let droppedMalformedCount = 0;
+    let busyRejectCount = 0;
+    log(`[mail-inbound-reuse] Consumer ready — listening for x-dispatch/work envelopes ` +
+        `addressed to non-sidecar agents (sidecar=${dispatcherAgentId})`);
+    const onMessage = (event) => {
+        // Only handle envelopes addressed to NON-sidecar agents. Sidecar
+        // envelopes are owned by mail-inbound-consumer (fresh-spawn).
+        if (event.agentId === dispatcherAgentId)
+            return;
+        const content = event.message?.content;
+        if (content?.schema !== "x-dispatch/work")
+            return;
+        const data = content.data;
+        if (!data?.taskId) {
+            droppedMalformedCount++;
+            log(`[mail-inbound-reuse] Dropping malformed envelope (no taskId, total=${droppedMalformedCount})`);
+            return;
+        }
+        const taskId = data.taskId;
+        pruneSeenTaskIds();
+        const seenExpiresAt = seenTaskIds.get(taskId);
+        if (seenExpiresAt !== undefined && seenExpiresAt > Date.now()) {
+            // Re-delivery within dedup window — silently drop.
+            return;
+        }
+        seenTaskIds.set(taskId, Date.now() + SEEN_TASK_TTL_MS);
+        const targetAgentId = event.agentId;
+        const conversationId = content._conversationId ?? null;
+        const prompt = data.prompt ?? data.content ?? "";
+        // Resolve target — must be a known, non-stopped agent.
+        const targetRecord = agentStore.getAgent(targetAgentId);
+        if (!targetRecord) {
+            log(`[mail-inbound-reuse] Unknown target agent ${targetAgentId} for taskId=${taskId} — dropping`);
+            void postReplyTurn(conversationId, targetAgentId, {
+                status: "agent_unavailable",
+                reason: `Agent ${targetAgentId} not registered on this swarm`,
+            });
+            return;
+        }
+        if (targetRecord.state === "stopped" || targetRecord.state === "failed") {
+            log(`[mail-inbound-reuse] Target agent ${targetAgentId} state=${targetRecord.state} — dropping taskId=${taskId}`);
+            void postReplyTurn(conversationId, targetAgentId, {
+                status: "agent_unavailable",
+                reason: `Agent ${targetAgentId} state=${targetRecord.state}`,
+            });
+            return;
+        }
+        // In-flight check — only reject when this same agent is already
+        // processing another tracked dispatch. Non-dispatch work (peer chat,
+        // user prompts) does not block; promptUntilDone-style serial stacking
+        // handles that.
+        const existing = inflightDispatches.get(targetAgentId);
+        if (existing) {
+            busyRejectCount++;
+            log(`[mail-inbound-reuse] recipient_busy — agent=${targetAgentId} already processing ` +
+                `dispatch=${existing.dispatchId}; rejecting taskId=${taskId}`);
+            void postReplyTurn(conversationId, targetAgentId, {
+                status: "recipient_busy",
+                reason: `Agent ${targetAgentId} is processing dispatch ${existing.dispatchId}`,
+            });
+            return;
+        }
+        log(`[mail-inbound-reuse] Driving dispatch taskId=${taskId} on existing agent=${targetAgentId} ` +
+            `conv=${conversationId ?? "(none)"}`);
+        inflightDispatches.set(targetAgentId, {
+            dispatchId: taskId,
+            conversationId,
+            startedAt: Date.now(),
+        });
+        // Drive the agent's existing session via raw `prompt()` rather than
+        // `promptUntilDone` because the latter auto-terminates the agent on
+        // done() — fatal for long-lived workers we want to reuse. We watch
+        // the update stream ourselves for the done() tool call and capture
+        // the summary inline.
+        void driveDispatch(targetAgentId, taskId, prompt, conversationId, data.loadout).finally(() => {
+            inflightDispatches.delete(targetAgentId);
+            // Always clear the permission overlay, even if driveDispatch
+            // didn't set one — keeps the registry tidy and defends against
+            // a future code path that sets one but skips its own cleanup.
+            clearPermissionOverlay(targetAgentId);
+        });
+    };
+    async function driveDispatch(targetAgentId, taskId, prompt, conversationId, loadout) {
+        // Apply the dispatch's loadout permissions as a runtime overlay
+        // for the duration of this prompt drive. The PreToolUse hook
+        // installed at spawn-time consults the overlay registry per tool
+        // call and denies calls that match the loadout's deny rules.
+        // `fullAutonomous: true` because mail-inbound workers have no
+        // human in the loop — `ask` rules collapse to `allow`. Cleared
+        // unconditionally in `finally` so a crash mid-prompt doesn't
+        // leave a stale overlay on the agent.
+        const overlay = collapsePermissionsForAutonomous(loadout?.permissions, 
+        /* fullAutonomous */ true);
+        if (overlay) {
+            setPermissionOverlay(targetAgentId, overlay);
+            log(`[mail-inbound-reuse] Applied permission overlay for agent=${targetAgentId} ` +
+                `taskId=${taskId} (deny=${overlay.deny.length} allow=${overlay.allow.length})`);
+        }
+        let summary;
+        let status;
+        let doneSeen = false;
+        let promptError;
+        try {
+            for await (const update of agentManager.prompt(targetAgentId, prompt)) {
+                const captured = captureDoneCall(update);
+                if (captured) {
+                    doneSeen = true;
+                    if (captured.summary)
+                        summary = captured.summary;
+                    if (captured.status)
+                        status = captured.status;
+                }
+            }
+        }
+        catch (err) {
+            promptError = err;
+            log(`[mail-inbound-reuse] prompt() threw for agent=${targetAgentId} taskId=${taskId}: ` +
+                `${promptError.message ?? String(promptError)}`);
+        }
+        // Fallback: read `_lastSummary` from agentStore. The done() handler
+        // persists this for in-flight agents (Phase 2C) so the reply path
+        // is reliable even when the prompt iterator's update stream raced
+        // the ACP connection close. Covers:
+        //   - prompt() threw before yielding the done() update (catch above)
+        //   - inline capture saw done() but `args.summary` was empty
+        //   - iterator yielded but our captureDoneCall missed (shape drift)
+        if (!summary) {
+            try {
+                const record = agentStore.getAgent(targetAgentId);
+                const fallback = record?.metadata?._lastSummary;
+                if (typeof fallback === "string" && fallback.length > 0) {
+                    summary = fallback;
+                    doneSeen = true;
+                    log(`[mail-inbound-reuse] Recovered summary from _lastSummary fallback for agent=${targetAgentId} taskId=${taskId}`);
+                }
+            }
+            catch {
+                /* best effort — store may be closing during shutdown */
+            }
+        }
+        // Post reply: prefer real summary, fall back to status notes when
+        // we genuinely have nothing.
+        if (summary) {
+            void postReplyTurn(conversationId, targetAgentId, summary).then(() => {
+                // Clear the persisted summary so it doesn't replay if the same
+                // agentId is dispatched again. Best-effort.
+                try {
+                    const existing = agentStore.getAgent(targetAgentId)?.metadata ?? {};
+                    const { _lastSummary: _drop, ...rest } = existing;
+                    void _drop;
+                    agentStore.updateAgent(targetAgentId, { metadata: rest });
+                }
+                catch {
+                    /* best effort */
+                }
+            });
+            return;
+        }
+        if (promptError) {
+            void postReplyTurn(conversationId, targetAgentId, {
+                status: "failed",
+                reason: `Prompt failed: ${promptError.message ?? String(promptError)}`,
+            });
+            return;
+        }
+        if (!doneSeen) {
+            log(`[mail-inbound-reuse] Agent ${targetAgentId} finished prompt without calling done() ` +
+                `for taskId=${taskId} — posting "incomplete" reply`);
+            void postReplyTurn(conversationId, targetAgentId, {
+                status: "incomplete",
+                reason: "Agent did not call done() within the prompt cycle",
+            });
+            return;
+        }
+        void postReplyTurn(conversationId, targetAgentId, `Dispatch ${taskId} ${status ?? "completed"} (no summary)`);
+    }
+    /**
+     * Detect a `done()` tool-call update and extract `{ status, summary }`
+     * from rawInput. Mirrors `promptUntilDone`'s detection logic but also
+     * captures `summary` (which the AgentManager's loop discards).
+     */
+    function captureDoneCall(update) {
+        const u = update;
+        const sessionUpdate = u.sessionUpdate;
+        const title = u.title;
+        const isDoneToolCall = (sessionUpdate === "tool_call" || sessionUpdate === "tool_call_update") &&
+            typeof title === "string" &&
+            title.endsWith("__done");
+        if (!isDoneToolCall) {
+            // Older fallback shape.
+            if (u.type === "result" &&
+                u.subtype === "tool_result" &&
+                u.toolName === "done") {
+                const result = u.result;
+                if (result) {
+                    return { status: result.status, summary: result.summary };
+                }
+            }
+            return null;
+        }
+        let input;
+        try {
+            const raw = u.rawInput;
+            if (typeof raw === "string") {
+                input = JSON.parse(raw);
+            }
+            else if (raw && typeof raw === "object") {
+                input = raw;
+            }
+            else if (u.input && typeof u.input === "object") {
+                input = u.input;
+            }
+        }
+        catch {
+            // rawInput not yet parseable (multi-update tool call); ignore.
+        }
+        if (!input)
+            return null;
+        return { status: input.status, summary: input.summary };
+    }
+    async function postReplyTurn(conversationId, fromAgentId, content) {
+        if (!conversationId) {
+            log(`[mail-inbound-reuse] No conversationId — reply for ${fromAgentId} dropped: ` +
+                `${typeof content === "string" ? content.slice(0, 80) : content.status}`);
+            return;
+        }
+        const sidecar = getSidecar();
+        if (!sidecar?.postMailTurn) {
+            log(`[mail-inbound-reuse] No sidecar/postMailTurn — reply turn dropped`);
+            return;
+        }
+        const body = typeof content === "string" ? content : JSON.stringify(content);
+        try {
+            await sidecar.postMailTurn(conversationId, fromAgentId, body);
+        }
+        catch (err) {
+            log(`[mail-inbound-reuse] postMailTurn failed for ${fromAgentId}: ` +
+                `${err.message ?? String(err)}`);
+        }
+    }
+    inboxEvents.on("inbox.message", onMessage);
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            try {
+                if (inboxEvents.off) {
+                    inboxEvents.off("inbox.message", onMessage);
+                }
+                else if (inboxEvents.removeListener) {
+                    inboxEvents.removeListener("inbox.message", onMessage);
+                }
+            }
+            catch {
+                // best effort
+            }
+            log(`[mail-inbound-reuse] Consumer stopped`);
+        },
+        stats() {
+            pruneSeenTaskIds();
+            return {
+                droppedMalformed: droppedMalformedCount,
+                seenTaskIds: seenTaskIds.size,
+                busyRejects: busyRejectCount,
+                inflightCount: inflightDispatches.size,
+            };
+        },
+    };
+}
+//# sourceMappingURL=mail-inbound-reuse-consumer.js.map

package/dist/dispatch/mail-inbound-reuse-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-inbound-reuse-consumer.js","sourceRoot":"","sources":["../../src/dispatch/mail-inbound-reuse-consumer.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/permission-evaluator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Permission Evaluator
+ *
+ * Pure function: given a tool call (name + input) and an overlay's
+ * permission rules, decide whether to deny, allow, or pass-through.
+ * Used by the `PreToolUse` hook installed at spawn time to enforce
+ * dispatch-supplied loadout permissions on a running session.
+ *
+ * Rule format (matches Claude Agent SDK convention):
+ *
+ *     <ToolName>                  — match any call to this tool
+ *     <ToolName>(<glob-pattern>)  — match calls whose primary input
+ *                                    field matches the glob pattern
+ *
+ * The "primary input field" is tool-specific:
+ *
+ *   Bash         → input.command
+ *   Read         → input.file_path
+ *   Write        → input.file_path
+ *   Edit         → input.file_path
+ *   Grep         → input.pattern
+ *   <other>      → no field-level match; rule must be bare `<ToolName>`
+ *
+ * Glob: `*` matches any sequence of characters (no path-segment
+ * distinction). Other regex specials are escaped.
+ *
+ * Decision precedence:
+ *
+ *   1. If any rule in `deny` matches → 'deny'
+ *   2. Else if any rule in `allow` matches → 'allow'
+ *   3. Else → 'pass-through' (let the session's static rules decide)
+ *
+ * `ask` rules are not evaluated here — the consumer is expected to
+ * collapse `ask` to either `allow` or `deny` before setting the
+ * overlay (via `collapsePermissionsForAutonomous` based on the
+ * spawn's `fullAutonomous` flag). The evaluator sees only collapsed
+ * `allow` and `deny` lists.
+ *
+ * @module dispatch/permission-evaluator
+ */
+import type { OverlayPermissions } from "./permission-overlay.js";
+export interface PermissionDecision {
+    decision: "allow" | "deny" | "pass-through";
+    matchedRule?: string;
+    matchedField?: string;
+}
+/**
+ * Evaluate a single tool call against an overlay's permission rules.
+ *
+ * Returns `'pass-through'` (the default) when no rule matches — the
+ * caller should fall back to the session's static permission rules
+ * for the final decision.
+ */
+export declare function evaluatePermission(toolName: string, toolInput: unknown, overlay: OverlayPermissions): PermissionDecision;
+interface RuleMatch {
+    matched: boolean;
+    field?: string;
+}
+/**
+ * Test a single rule against a tool call. Returns whether the rule
+ * matched and which input field (if any) was tested.
+ *
+ * Exported only for testability; production callers should use
+ * `evaluatePermission`.
+ */
+export declare function matchRule(rule: string, toolName: string, toolInput: unknown): RuleMatch;
+export {};
+//# sourceMappingURL=permission-evaluator.d.ts.map

package/dist/dispatch/permission-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-evaluator.d.ts","sourceRoot":"","sources":["../../src/dispatch/permission-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,cAAc,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,kBAAkB,GAC1B,kBAAkB,CAyBpB;AAED,UAAU,SAAS;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,GACjB,SAAS,CA4BX"}

package/dist/dispatch/permission-evaluator.js

@@ -0,0 +1,159 @@
+/**
+ * Permission Evaluator
+ *
+ * Pure function: given a tool call (name + input) and an overlay's
+ * permission rules, decide whether to deny, allow, or pass-through.
+ * Used by the `PreToolUse` hook installed at spawn time to enforce
+ * dispatch-supplied loadout permissions on a running session.
+ *
+ * Rule format (matches Claude Agent SDK convention):
+ *
+ *     <ToolName>                  — match any call to this tool
+ *     <ToolName>(<glob-pattern>)  — match calls whose primary input
+ *                                    field matches the glob pattern
+ *
+ * The "primary input field" is tool-specific:
+ *
+ *   Bash         → input.command
+ *   Read         → input.file_path
+ *   Write        → input.file_path
+ *   Edit         → input.file_path
+ *   Grep         → input.pattern
+ *   <other>      → no field-level match; rule must be bare `<ToolName>`
+ *
+ * Glob: `*` matches any sequence of characters (no path-segment
+ * distinction). Other regex specials are escaped.
+ *
+ * Decision precedence:
+ *
+ *   1. If any rule in `deny` matches → 'deny'
+ *   2. Else if any rule in `allow` matches → 'allow'
+ *   3. Else → 'pass-through' (let the session's static rules decide)
+ *
+ * `ask` rules are not evaluated here — the consumer is expected to
+ * collapse `ask` to either `allow` or `deny` before setting the
+ * overlay (via `collapsePermissionsForAutonomous` based on the
+ * spawn's `fullAutonomous` flag). The evaluator sees only collapsed
+ * `allow` and `deny` lists.
+ *
+ * @module dispatch/permission-evaluator
+ */
+/**
+ * Tool-name → primary input field name. Add entries as needed for
+ * additional tools. Tools not listed have no field-level matching;
+ * only bare `<ToolName>` rules apply.
+ */
+const PRIMARY_INPUT_FIELD = {
+    Bash: "command",
+    Read: "file_path",
+    Write: "file_path",
+    Edit: "file_path",
+    MultiEdit: "file_path",
+    Grep: "pattern",
+    Glob: "pattern",
+    NotebookRead: "notebook_path",
+    NotebookEdit: "notebook_path",
+};
+/**
+ * Evaluate a single tool call against an overlay's permission rules.
+ *
+ * Returns `'pass-through'` (the default) when no rule matches — the
+ * caller should fall back to the session's static permission rules
+ * for the final decision.
+ */
+export function evaluatePermission(toolName, toolInput, overlay) {
+    // Deny rules win over allow.
+    for (const rule of overlay.deny ?? []) {
+        const match = matchRule(rule, toolName, toolInput);
+        if (match.matched) {
+            return {
+                decision: "deny",
+                matchedRule: rule,
+                ...(match.field ? { matchedField: match.field } : {}),
+            };
+        }
+    }
+    for (const rule of overlay.allow ?? []) {
+        const match = matchRule(rule, toolName, toolInput);
+        if (match.matched) {
+            return {
+                decision: "allow",
+                matchedRule: rule,
+                ...(match.field ? { matchedField: match.field } : {}),
+            };
+        }
+    }
+    return { decision: "pass-through" };
+}
+/**
+ * Test a single rule against a tool call. Returns whether the rule
+ * matched and which input field (if any) was tested.
+ *
+ * Exported only for testability; production callers should use
+ * `evaluatePermission`.
+ */
+export function matchRule(rule, toolName, toolInput) {
+    const parsed = parseRule(rule);
+    if (!parsed)
+        return { matched: false };
+    if (parsed.toolName !== toolName)
+        return { matched: false };
+    // No pattern → any call to this tool matches.
+    if (parsed.pattern === undefined)
+        return { matched: true };
+    // Empty pattern (`Bash()`) — also any call to this tool. Conservative.
+    if (parsed.pattern === "")
+        return { matched: true };
+    const fieldName = PRIMARY_INPUT_FIELD[toolName];
+    if (!fieldName) {
+        // No primary field defined for this tool → can't match a pattern.
+        // Pattern-bearing rules for unknown tools never match (skip).
+        return { matched: false };
+    }
+    const fieldValue = readField(toolInput, fieldName);
+    if (typeof fieldValue !== "string") {
+        return { matched: false };
+    }
+    const re = globToRegex(parsed.pattern);
+    return {
+        matched: re.test(fieldValue),
+        field: fieldName,
+    };
+}
+function parseRule(rule) {
+    // Tool names allow letters/digits/underscores AND hyphens — MCP tools use
+    // hyphens in their server prefix (e.g., `mcp__agent-inbox__list_agents`).
+    const m = rule.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?:\((.*)\))?$/);
+    if (!m)
+        return null;
+    const [, toolName, pattern] = m;
+    if (pattern === undefined) {
+        return { toolName: toolName };
+    }
+    return { toolName: toolName, pattern };
+}
+function readField(input, field) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    return input[field];
+}
+/**
+ * Convert a Claude permission glob into a regex. Only `*` is special;
+ * everything else is treated as a literal. The result is anchored
+ * (`^...$`) for whole-string matching.
+ */
+function globToRegex(pattern) {
+    let out = "^";
+    for (const ch of pattern) {
+        if (ch === "*") {
+            out += ".*";
+        }
+        else {
+            // Escape regex specials.
+            out += ch.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    out += "$";
+    return new RegExp(out);
+}
+//# sourceMappingURL=permission-evaluator.js.map

package/dist/dispatch/permission-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-evaluator.js","sourceRoot":"","sources":["../../src/dispatch/permission-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/permission-overlay.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Permission Overlay Registry
+ *
+ * Process-singleton map of `agentId → Permissions` for in-flight
+ * dispatches. The `PreToolUse` hook installed at spawn time consults
+ * this registry on every tool call. Dispatch consumers (e.g., the
+ * mail-inbound-reuse-consumer) set the overlay when claiming an
+ * in-flight dispatch and clear it on resolution.
+ *
+ * Why a registry rather than a per-spawn argument:
+ *   - The session is created with permissive rules at boot. The
+ *     dispatch's narrower deny rules need to apply at *call time*, not
+ *     at spawn time, because the agent already exists when the dispatch
+ *     arrives. The hook closure captures `agentId` and reads the
+ *     registry per-call so updates propagate without recreating the
+ *     session.
+ *
+ * Semantics:
+ *   - Intersection-only: the overlay can ADD denies to a session but
+ *     cannot grant new allows. If the session was spawned with broad
+ *     permissions and the overlay says `allow: [Read]`, the session's
+ *     other tools still work — the overlay only tightens.
+ *   - Single overlay per agent: `mail-inbound-reuse-consumer` already
+ *     enforces one in-flight dispatch per agent (`recipient_busy`
+ *     reject), so overwriting is safe.
+ *
+ * @module dispatch/permission-overlay
+ */
+export interface OverlayPermissions {
+    allow?: string[];
+    deny?: string[];
+    ask?: string[];
+}
+/**
+ * Apply a permission overlay for an agent. Subsequent tool calls by
+ * that agent flow through the `PreToolUse` hook, which consults this
+ * registry. Overwrites any prior overlay for the same agent.
+ */
+export declare function setPermissionOverlay(agentId: string, perms: OverlayPermissions): void;
+/**
+ * Remove the active overlay for an agent. Subsequent tool calls fall
+ * back to the session's static permission rules.
+ */
+export declare function clearPermissionOverlay(agentId: string): void;
+/**
+ * Read the current overlay for an agent. Returns `undefined` when no
+ * overlay is in effect — the hook treats that as pass-through.
+ */
+export declare function getPermissionOverlay(agentId: string): OverlayPermissions | undefined;
+/**
+ * Clear all overlays. Used as defense-in-depth when a fresh consumer
+ * starts (process startup); also exposed for test isolation.
+ */
+export declare function clearAllPermissionOverlays(): void;
+/**
+ * Test helper — alias for `clearAllPermissionOverlays`. Kept distinct
+ * so it's grep-able for "test-only" cleanup paths.
+ */
+export declare function _resetForTest(): void;
+/**
+ * Test helper — number of overlays currently active.
+ */
+export declare function _sizeForTest(): number;
+//# sourceMappingURL=permission-overlay.d.ts.map

package/dist/dispatch/permission-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-overlay.d.ts","sourceRoot":"","sources":["../../src/dispatch/permission-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC"}