macro-agent 0.1.12 → 0.2.1

package/src/agent/__tests__/agent-manager-v2.permissions.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Unit tests for AgentManagerV2's permission + fullAutonomous spawn-config
+ * wiring. Pins the contract that `SpawnAgentOptions.permissions` is forwarded
+ * to `agentMeta.claudeCode.options.settings.permissions` on the Claude Code
+ * session, and that `ask` rules collapse based on `fullAutonomous`.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// IMPORTANT: vi.mock must run before agent-manager-v2 imports acp-factory.
+//
+// We intercept handle.createSession with a spy so each test can read back the
+// `agentMeta` argument and assert against it. Re-using a mock fn means the
+// first .mock.calls[0] always points to the most recent spawn() call.
+const createSessionSpy = vi.fn();
+
+vi.mock("acp-factory", () => ({
+  AgentFactory: {
+    spawn: vi.fn().mockResolvedValue({
+      createSession: (...args: unknown[]) => {
+        createSessionSpy(...args);
+        return Promise.resolve({
+          id: "provider-session-1",
+          prompt: vi.fn().mockReturnValue({
+            [Symbol.asyncIterator]: () => ({
+              next: () => Promise.resolve({ done: true, value: undefined }),
+            }),
+          }),
+          forkWithFlush: vi.fn().mockResolvedValue({ id: "forked-session-1" }),
+        });
+      },
+      loadSession: vi.fn().mockResolvedValue({
+        id: "loaded-session-1",
+        prompt: vi.fn().mockReturnValue({
+          [Symbol.asyncIterator]: () => ({
+            next: () => Promise.resolve({ done: true, value: undefined }),
+          }),
+        }),
+      }),
+      close: vi.fn().mockResolvedValue(undefined),
+      isRunning: vi.fn().mockReturnValue(true),
+    }),
+  },
+}));
+
+import { createAgentManagerV2 } from "../agent-manager-v2.js";
+import { AgentStore } from "../agent-store.js";
+import type { AgentManager } from "../agent-manager.js";
+import type { InboxAdapter, TasksAdapter } from "../../adapters/types.js";
+
+function createMockInboxAdapter(): InboxAdapter {
+  return {
+    registerAgent: vi.fn().mockResolvedValue(undefined),
+    deregisterAgent: vi.fn().mockResolvedValue(undefined),
+    send: vi.fn().mockResolvedValue("msg-1"),
+    onDelivery: vi.fn(),
+    offDelivery: vi.fn(),
+    checkInbox: vi.fn().mockResolvedValue([]),
+    readThread: vi.fn().mockResolvedValue([]),
+    setSignalFilter: vi.fn(),
+    setEmissionValidator: vi.fn(),
+    socketPath: "/tmp/test-inbox.sock",
+    stop: vi.fn().mockResolvedValue(undefined),
+  } as unknown as InboxAdapter;
+}
+
+function createMockTasksAdapter(): TasksAdapter {
+  return {
+    createTask: vi.fn().mockResolvedValue("ot-task-1"),
+    assignTask: vi.fn().mockResolvedValue(undefined),
+    transitionTask: vi.fn().mockResolvedValue(undefined),
+    getTask: vi.fn().mockResolvedValue({ id: "t-1", title: "test", status: "open" }),
+    queryReady: vi.fn().mockResolvedValue([]),
+    listTasks: vi.fn().mockResolvedValue([]),
+    addBlocker: vi.fn().mockResolvedValue(undefined),
+    removeBlocker: vi.fn().mockResolvedValue(undefined),
+    claimTask: vi.fn().mockResolvedValue(null),
+    unclaimTask: vi.fn().mockResolvedValue(undefined),
+    listClaimable: vi.fn().mockResolvedValue([]),
+    connect: vi.fn().mockResolvedValue(undefined),
+    disconnect: vi.fn(),
+    connected: true,
+  } as unknown as TasksAdapter;
+}
+
+/**
+ * Read back the second argument to handle.createSession from the most recent
+ * spawn() call. Returns the `agentMeta` field if present.
+ */
+function readLastSpawnAgentMeta(): Record<string, unknown> | undefined {
+  const calls = createSessionSpy.mock.calls;
+  expect(calls.length).toBeGreaterThan(0);
+  const lastCall = calls[calls.length - 1];
+  // createSession(cwd, options)
+  const sessionOpts = lastCall[1] as Record<string, unknown> | undefined;
+  return sessionOpts?.agentMeta as Record<string, unknown> | undefined;
+}
+
+describe("AgentManagerV2 permissions + fullAutonomous spawn config", () => {
+  let agentStore: AgentStore;
+  let inboxAdapter: InboxAdapter;
+  let tasksAdapter: TasksAdapter;
+  let manager: AgentManager;
+
+  beforeEach(() => {
+    createSessionSpy.mockClear();
+    agentStore = new AgentStore(":memory:");
+    inboxAdapter = createMockInboxAdapter();
+    tasksAdapter = createMockTasksAdapter();
+    manager = createAgentManagerV2(agentStore, inboxAdapter, tasksAdapter, {
+      defaultCwd: "/tmp/test",
+    });
+  });
+
+  afterEach(async () => {
+    await manager.close();
+    agentStore.close();
+  });
+
+  it("permissions present + fullAutonomous: true → ask rules collapse into allow", async () => {
+    await manager.spawn({
+      task: "Test",
+      role: "worker",
+      permissions: {
+        deny: ["Bash(rm -rf:*)"],
+        ask: ["Write(*.env)"],
+      },
+      fullAutonomous: true,
+    });
+
+    const agentMeta = readLastSpawnAgentMeta();
+    expect(agentMeta).toBeDefined();
+    const cc = agentMeta!.claudeCode as {
+      options: { settings?: { permissions?: Record<string, string[]> } };
+    };
+    const perms = cc.options.settings?.permissions;
+    expect(perms).toBeDefined();
+    expect(perms!.deny).toContain("Bash(rm -rf:*)");
+    // fullAutonomous: true → ask collapses into allow
+    expect(perms!.allow).toContain("Write(*.env)");
+    // ask should NOT also be a literal field
+    expect(perms!.ask).toBeUndefined();
+  });
+
+  it("permissions present + fullAutonomous: false → ask rules collapse into deny", async () => {
+    await manager.spawn({
+      task: "Test",
+      role: "worker",
+      permissions: {
+        deny: ["Bash(rm -rf:*)"],
+        ask: ["Write(*.env)"],
+      },
+      fullAutonomous: false,
+    });
+
+    const agentMeta = readLastSpawnAgentMeta();
+    expect(agentMeta).toBeDefined();
+    const cc = agentMeta!.claudeCode as {
+      options: { settings?: { permissions?: Record<string, string[]> } };
+    };
+    const perms = cc.options.settings?.permissions;
+    expect(perms).toBeDefined();
+    // Both original deny AND collapsed ask end up in deny
+    expect(perms!.deny).toContain("Bash(rm -rf:*)");
+    expect(perms!.deny).toContain("Write(*.env)");
+    expect(perms!.allow).toBeUndefined();
+    expect(perms!.ask).toBeUndefined();
+  });
+
+  it("no permissions → no agentMeta.claudeCode.options.settings.permissions", async () => {
+    await manager.spawn({
+      task: "Test",
+      role: "worker",
+    });
+
+    const agentMeta = readLastSpawnAgentMeta();
+    // agentMeta should be entirely absent (no settingSources, no settings)
+    if (agentMeta) {
+      const cc = agentMeta.claudeCode as
+        | { options: { settings?: { permissions?: unknown } } }
+        | undefined;
+      expect(cc?.options?.settings?.permissions).toBeUndefined();
+    }
+  });
+
+  it("isolatedSettings: true + permissions → both settingSources=[] AND settings.permissions present", async () => {
+    await manager.spawn({
+      task: "Test",
+      role: "worker",
+      isolatedSettings: true,
+      permissions: { deny: ["Bash(rm -rf:*)"] },
+      fullAutonomous: true,
+    });
+
+    const agentMeta = readLastSpawnAgentMeta();
+    expect(agentMeta).toBeDefined();
+    const cc = agentMeta!.claudeCode as {
+      options: {
+        settingSources?: unknown[];
+        settings?: { permissions?: Record<string, string[]> };
+      };
+    };
+    expect(cc.options.settingSources).toEqual([]);
+    expect(cc.options.settings?.permissions?.deny).toContain("Bash(rm -rf:*)");
+  });
+
+  it("permissions with all empty arrays → no settings.permissions key written", async () => {
+    await manager.spawn({
+      task: "Test",
+      role: "worker",
+      permissions: { allow: [], deny: [], ask: [] },
+      fullAutonomous: true,
+    });
+
+    const agentMeta = readLastSpawnAgentMeta();
+    // The spawn handler always writes a `settings` object when permissions are
+    // truthy, but with empty allow/deny it should NOT include the rule keys —
+    // i.e. settings.permissions has no `allow` and no `deny`.
+    if (agentMeta) {
+      const cc = agentMeta.claudeCode as {
+        options: { settings?: { permissions?: Record<string, string[]> } };
+      };
+      const perms = cc.options.settings?.permissions;
+      // perms is either undefined or an empty object — both acceptable.
+      // Critically: no allow/deny/ask arrays leak through with empty content.
+      if (perms) {
+        expect(perms.allow).toBeUndefined();
+        expect(perms.deny).toBeUndefined();
+        expect(perms.ask).toBeUndefined();
+      }
+    }
+  });
+});

package/src/agent/agent-manager-v2.ts

@@ -65,11 +65,61 @@ import { AgentTokenManager } from "../auth/token.js";
 import type { InboxAdapter } from "../adapters/types.js";
 import type { TasksAdapter } from "../adapters/types.js";
 import type { AgentManager, SpawnInterceptor } from "./agent-manager.js";
+import { getPermissionOverlay } from "../dispatch/permission-overlay.js";
+import { evaluatePermission } from "../dispatch/permission-evaluator.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Helper
 // ─────────────────────────────────────────────────────────────────
 
+/**
+ * Derive the canonical Claude Code tool name from a `permission_request`
+ * `toolCall` object.
+ *
+ * Why this is needed: claude-agent-acp's `toolInfoFromToolUse` mangles
+ * built-in tool names into display titles (e.g., `Read /tmp/x` instead of
+ * `Read`). MCP tools use their fully-qualified `mcp__server__tool` name as
+ * the title. The `kind` field (Claude SDK's tool category) is the
+ * cleanest signal for built-ins, with the input shape disambiguating
+ * within a category (e.g., `edit` covers Write/Edit/MultiEdit — we look
+ * at `old_string`/`edits` to pick which).
+ *
+ * Pure: no side effects; safe to call from the prompt iterator.
+ */
+function deriveToolName(toolCall: {
+  title?: string;
+  kind?: string;
+  rawInput?: unknown;
+} | undefined): string {
+  const title = toolCall?.title ?? "";
+  const kind = toolCall?.kind ?? "";
+  // MCP tools — title is the canonical name.
+  if (title.startsWith("mcp__")) return title.split(/\s/)[0] ?? "";
+  const input =
+    toolCall?.rawInput && typeof toolCall.rawInput === "object"
+      ? (toolCall.rawInput as Record<string, unknown>)
+      : {};
+  switch (kind) {
+    case "read":
+      return "Read";
+    case "execute":
+      return "Bash";
+    case "edit":
+      if ("edits" in input) return "MultiEdit";
+      if ("old_string" in input) return "Edit";
+      return "Write";
+    case "search":
+      return "path" in input ? "Grep" : "Glob";
+    case "think":
+      return "Task";
+    case "switch_mode":
+      return "ExitPlanMode";
+  }
+  // Fallback: first whitespace-delimited token of the title (Read/Write/
+  // Edit cases not caught above; built-ins newer than this matrix).
+  return title.split(/\s/)[0] ?? "";
+}
+
 function getSpawnCapability(childRole: string): Capability {
   const baseRole = childRole.split(".")[0];
   switch (baseRole) {
@@ -527,6 +577,7 @@ export function createAgentManagerV2(
       parent,
       cwd = defaultCwd,
       permissionMode = defaultPermissionMode,
+      askForAllTools = false,
       subscribeParent = true,
       topics = [],
       config: agentConfig,
@@ -624,7 +675,12 @@ export function createAgentManagerV2(
       created_at: now,
       started_at: now,
       config: agentConfig as Record<string, unknown>,
-      metadata: options.taskRef ? { task_ref: options.taskRef } : {},
+      metadata: {
+        ...(options.taskRef ? { task_ref: options.taskRef } : {}),
+        // Persist isolatedSettings so resume() applies the same agentMeta
+        // policy without needing the original SpawnAgentOptions.
+        ...(options.isolatedSettings ? { isolatedSettings: true } : {}),
+      },
     };
     agentStore.putAgent(agentRecord);
 
@@ -714,6 +770,57 @@ export function createAgentManagerV2(
         })) ?? []),
       ];
 
+      // Always-on subsystem MCP servers (the "trinity"). The macro-agent
+      // architecture docs describe agent-inbox + opentasks as separate MCP
+      // servers available to spawned workers, but until this entry block
+      // existed they were only reachable when host-level Claude plugins
+      // happened to have wired them. That left mail-inbound workers
+      // (`parent: null` + `isolatedSettings: true`) without inbox/tasks
+      // tools — see openhive-2 docs/LOADOUTS_DESIGN.md "Loadout-provided
+      // MCP servers" live finding 2026-05-03.
+      //
+      // Registering them here makes them per-spawn defaults independent
+      // of host configuration. Caller-supplied `agentConfig.mcpServers`
+      // remains additive (Option C / "hybrid"): the trinity is always
+      // there, callers can layer more on top.
+
+      // agent-inbox — exposes send_message, check_inbox, read_thread,
+      // list_agents via the InboxMcpProxy stdio bridge.
+      if (inboxAdapter.socketPath) {
+        const inboxProxyEntry = new URL(
+          "../../dist/cli/inbox-mcp-proxy.js",
+          import.meta.url,
+        ).pathname;
+        mcpServers.push({
+          name: "agent-inbox",
+          command: "node",
+          args: [inboxProxyEntry],
+          env: [
+            { name: "INBOX_SOCKET_PATH", value: inboxAdapter.socketPath },
+            { name: "MACRO_AGENT_ID", value: agentId },
+          ],
+        } as any);
+      }
+
+      // opentasks — exposes task, link, annotate, query via the
+      // `opentasks mcp` CLI subcommand. The package's dist/mcp/stdio.js
+      // is an exports-only module (no auto-start); the CLI's `mcp`
+      // subcommand is what actually wires StdioServerTransport. Conditional
+      // on tasksAdapter.connected — when the daemon isn't running, skip
+      // rather than mount a server that would fail at every tool call.
+      if (tasksAdapter.connected) {
+        const opentasksCliEntry = new URL(
+          "opentasks/dist/cli.js",
+          import.meta.url,
+        ).pathname;
+        mcpServers.push({
+          name: "opentasks",
+          command: "node",
+          args: [opentasksCliEntry, "mcp"],
+          env: [],
+        } as any);
+      }
+
       // Register minimem MCP server (agent-type independent — works for any MCP-capable agent)
       if (minimemConfig?.enabled) {
         mcpServers.push({
@@ -729,12 +836,98 @@ export function createAgentManagerV2(
         } as any);
       }
 
-      // Build agentMeta
-      let agentMeta: Record<string, any> | undefined;
-
-      if (permissionMode === "interactive") {
-        agentMeta = { claudeCode: { options: { settingSources: [] } } };
+      // Build agentMeta. Two layers:
+      //
+      //  1. `settingSources: []` — when the caller requests isolated
+      //     settings (mail-inbound dispatch workers via
+      //     SpawnAgentOptions.isolatedSettings), strip user/project/local
+      //     setting sources so the worker doesn't load the host's
+      //     claude-code-swarm / oh-my-claudecode / etc plugin MCP servers
+      //     — those plugins assume host-shaped environment (sockets,
+      //     daemons) and hang at session/new MCP-init when missing.
+      //     Interactive `multiagent` callers leave this false so their
+      //     installed plugins load normally.
+      //
+      //  2. `settings.permissions` — when the caller passes
+      //     SpawnAgentOptions.permissions (e.g., from a materialized
+      //     loadout), wire the rules inline via the Claude Agent SDK's
+      //     session-level settings pass-through. Verified live: `deny`
+      //     wins even over `permissionMode: "auto-approve"`. Inline
+      //     wiring avoids file collisions when concurrent workers share
+      //     a CWD (no `.claude/settings.json` written to disk).
+      //
+      //     SDK contract pinned by the boundary test in
+      //     `src/agent/__tests__/agent-manager-v2.permissions.test.ts` —
+      //     it captures the literal `agentMeta` argument passed to
+      //     `handle.createSession` and asserts both `settingSources: []`
+      //     AND `settings.permissions` are present together (the
+      //     interaction between filesystem-stripping and inline
+      //     reconciliation that the SDK's docs don't fully spell out).
+      //     If a future SDK version changes how `settings` reconciles
+      //     with empty `settingSources`, that test will catch it.
+      //
+      //     `ask` rules collapse based on `fullAutonomous`:
+      //       - fullAutonomous: true  → ask → allow (autonomous worker
+      //         opts to proceed when there's no human to answer)
+      //       - fullAutonomous: false → ask → deny (safe default;
+      //         autonomous workers shouldn't make judgment calls)
+      const claudeCodeOptions: Record<string, any> = {};
+      if (options.isolatedSettings || permissionMode === "interactive") {
+        claudeCodeOptions.settingSources = [];
       }
+      if (options.permissions) {
+        const { allow = [], deny = [], ask = [] } = options.permissions;
+        const finalAllow = options.fullAutonomous ? [...allow, ...ask] : [...allow];
+        const finalDeny = options.fullAutonomous ? [...deny] : [...deny, ...ask];
+        claudeCodeOptions.settings = {
+          permissions: {
+            ...(finalAllow.length ? { allow: finalAllow } : {}),
+            ...(finalDeny.length ? { deny: finalDeny } : {}),
+          },
+        };
+      }
+      // P3 spike: when an agent should funnel every tool call through the host
+      // (so the prompt-iterator handler can apply runtime overlays), set
+      // `ask: ['*']` on settings.permissions. The SDK then consults canUseTool
+      // for every tool, which emits `permission_request` session updates.
+      // Used for dispatch-target agents (mail+reuse, ACP+reuse) that need
+      // dynamic enforcement; chat agents and parented children stay on
+      // their session's static rules.
+      if (options.askForAllTools) {
+        const existingPerms =
+          claudeCodeOptions.settings?.permissions ?? {};
+        claudeCodeOptions.settings = {
+          ...claudeCodeOptions.settings,
+          permissions: {
+            ...existingPerms,
+            ask: ["*"],
+          },
+        };
+      }
+
+      // 3. Runtime permission overlay enforcement lives in the prompt
+      //    iterator (see `prompt()` below), NOT here at spawn time.
+      //
+      //    Background: an earlier design installed a Claude SDK PreToolUse
+      //    hook here that closed over the per-process permission-overlay
+      //    registry. That mechanism was verified broken: function callbacks
+      //    inside arrays don't survive JSON.stringify across the
+      //    macro-agent → claude-agent-acp stdio JSON-RPC boundary, so the
+      //    hook arrived as `null` at the SDK and silently no-op'd.
+      //
+      //    The current design uses ACP's `permission_request` session
+      //    update path instead. When an agent is spawned with
+      //    `askForAllTools: true` + `permissionMode: 'interactive'`, the
+      //    SDK consults `canUseTool` on every tool call, claude-agent-acp
+      //    converts that into a `client.requestPermission` call, and
+      //    acp-factory emits it as a `permission_request` session update.
+      //    The prompt iterator below intercepts those updates, evaluates
+      //    against the overlay, and responds via `respondPermission`.
+      //    See `docs/PERMISSION_OVERLAY_ACP_DESIGN.md` for the full design.
+
+      const agentMeta = Object.keys(claudeCodeOptions).length > 0
+        ? { claudeCode: { options: claudeCodeOptions } }
+        : undefined;
 
       // Build capabilities context + skill-tree loadout for system prompt
       // Matches cc-swarm's context injection pattern (role-aware, tool-specific)
@@ -1094,8 +1287,12 @@ export function createAgentManagerV2(
       },
     ];
 
+    // Strip user/project/local setting sources for isolated workers (the
+    // metadata flag is set at spawn time when SpawnAgentOptions.isolatedSettings
+    // was true) or interactive mode. See spawn() for the rationale.
+    const isIsolated = (record.metadata as Record<string, unknown> | undefined)?.isolatedSettings === true;
     const agentMeta =
-      permMode === "interactive"
+      isIsolated || permMode === "interactive"
         ? { claudeCode: { options: { settingSources: [] } } }
         : undefined;
 
@@ -1477,7 +1674,71 @@ export function createAgentManagerV2(
 
     activeSession.isPrompting = true;
     try {
-      yield* activeSession.session.prompt(message);
+      // Permission overlay enforcement — for agents in dispatch context
+      // (mail-inbound + ACP reuse targets), the dispatch consumer sets a
+      // per-agent overlay before driving prompt(). When set, `permission_request`
+      // session updates are intercepted here, evaluated against the overlay,
+      // and answered via `respondToPermission`. The update is NOT yielded
+      // to the consumer in that case — dispatch enforcement is internal.
+      //
+      // When no overlay is set (the common case — chat agents, sub-agents
+      // spawned by parents, etc.), permission_request updates are yielded
+      // through unchanged so chat surfaces' UI permission dialogs (the
+      // swarmcraft PermissionDialog rendered via the openhive-acp-service
+      // WS subscription) keep working.
+      //
+      // See `docs/PERMISSION_OVERLAY_ACP_DESIGN.md` for the rationale and
+      // a diagram of the four-process flow.
+      for await (const update of activeSession.session.prompt(message)) {
+        const u = update as {
+          sessionUpdate?: string;
+          requestId?: string;
+          toolCall?: { title?: string; kind?: string; rawInput?: unknown };
+          options?: Array<{ kind?: string; optionId?: string }>;
+        };
+        if (u?.sessionUpdate === "permission_request") {
+          const overlay = getPermissionOverlay(agentId);
+          // No overlay → pass through to the consumer (chat UI, etc.).
+          if (!overlay) {
+            yield update;
+            continue;
+          }
+          let optionId: string | undefined;
+          try {
+            const toolName = deriveToolName(u.toolCall);
+            const toolInput = u.toolCall?.rawInput ?? {};
+            const decision = evaluatePermission(toolName, toolInput, overlay)
+              .decision;
+            const wantedKind =
+              decision === "deny" ? "reject_once" : "allow_once";
+            const opt =
+              u.options?.find((o) => o.kind === wantedKind) ??
+              u.options?.find(
+                (o) =>
+                  o.kind === (decision === "deny" ? "reject_always" : "allow_always"),
+              );
+            optionId = opt?.optionId;
+          } catch {
+            // Fail closed: on registry/evaluator error, deny.
+            optionId = u.options?.find((o) => o.kind === "reject_once")?.optionId;
+          }
+          if (u.requestId && optionId) {
+            try {
+              (activeSession.session as any).respondToPermission?.(
+                u.requestId,
+                optionId,
+              );
+            } catch (err) {
+              console.warn(
+                `[perm-overlay] respondToPermission failed agent=${agentId} req=${u.requestId}: ${(err as Error).message}`,
+              );
+            }
+          }
+          // Don't yield permission_request to the consumer — dispatch-internal.
+          continue;
+        }
+        yield update;
+      }
     } finally {
       activeSession.isPrompting = false;
       agentStore.updateAgent(agentId, {

package/src/agent/types.ts

@@ -78,6 +78,57 @@ export interface SpawnAgentOptions {
   /** Team instance ID this agent belongs to (set by TeamManager interceptor) */
   team_instance?: string;
 
+  /**
+   * When true, spawn the worker with `claudeCode.options.settingSources = []`
+   * so it does NOT inherit the host machine's user/project/local Claude
+   * settings. This prevents host-level plugin MCP servers (e.g.
+   * claude-code-swarm, oh-my-claudecode) from auto-mounting and hanging
+   * the worker's session/new at MCP-init time. Mail-inbound dispatch
+   * workers always set this; interactive `multiagent` users typically
+   * don't (they want their plugins).
+   */
+  isolatedSettings?: boolean;
+
+  /**
+   * Per-spawn permission rules — Claude Code permission patterns
+   * (e.g., `Read(**)`, `Bash(rm -rf:*)`).
+   *
+   * Wired through `agentMeta.claudeCode.options.settings.permissions` so
+   * Claude's permission engine consults them on every tool call. `deny`
+   * always wins, even over `permissionMode: "auto-approve"` (verified live).
+   *
+   * `ask` resolution depends on `fullAutonomous`:
+   *   - fullAutonomous: true  → `ask` rules collapse to `allow` (no human
+   *     to answer; opt-in by callers like the mail-inbound consumer)
+   *   - fullAutonomous: false → `ask` rules collapse to `deny` (safe
+   *     default — autonomous workers shouldn't make judgment calls)
+   *
+   * No file I/O — passed inline via SDK options, so concurrent spawns
+   * sharing a CWD never collide on `.claude/settings.json`.
+   */
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+    ask?: string[];
+  };
+
+  /**
+   * When true, treat `permissions.ask` rules as auto-approve. Use only for
+   * autonomous workers with no user-interactive permission round-trip
+   * available (e.g., mail-inbound dispatch). Default: false.
+   */
+  fullAutonomous?: boolean;
+
+  /**
+   * When true, set `settings.permissions.ask: ['*']` so the SDK consults
+   * `canUseTool` for every tool call, emitting `permission_request` session
+   * updates the host's prompt iterator can intercept. Used for dispatch-
+   * target agents (mail+reuse, ACP+reuse) where the dispatch consumer
+   * applies per-call deny rules via the permission overlay registry.
+   * Default: false (chat agents and parented children stay on static rules).
+   */
+  askForAllTools?: boolean;
+
   /**
    * Stream ID to join (for workers and integrators).
    * Required for workers and integrators when using workspace isolation.