macro-agent 0.1.0 → 0.1.1

package/src/agent/agent-manager.ts

@@ -8,6 +8,11 @@
  */
 
 import { nanoid } from "nanoid";
+import {
+  uniqueNamesGenerator,
+  adjectives,
+  animals,
+} from "unique-names-generator";
 import {
   AgentFactory,
   type Session,
@@ -50,6 +55,7 @@ import {
   type CascadeAgentManager,
 } from "../lifecycle/cascade.js";
 import type { HealthCheckService } from "../monitor/health-check-service.js";
+import { AgentTokenManager } from "../auth/token.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Helper Functions
@@ -103,8 +109,12 @@ export interface AgentManager {
 
   /**
    * Resume a stopped agent by loading its existing session.
+   * @param permissionMode - Optional permission mode override (defaults to the agent manager's default)
    */
-  resume(agentId: AgentId): Promise<SpawnedAgent>;
+  resume(
+    agentId: AgentId,
+    permissionMode?: PermissionMode,
+  ): Promise<SpawnedAgent>;
 
   /**
    * Continue a terminated agent by spawning a new agent with the same
@@ -117,7 +127,20 @@ export interface AgentManager {
    */
   continueAgent(
     agentId: AgentId,
-    options?: ContinueAgentOptions
+    options?: ContinueAgentOptions,
+  ): Promise<SpawnedAgent>;
+
+  /**
+   * Fork an agent's session, creating a new agent with the same
+   * conversation history. Uses forkWithFlush for active sessions
+   * or loadSession for stopped agents with persisted sessions.
+   *
+   * @param sourceAgentId - ID of the agent to fork from
+   * @param options - Fork options (name, prompt, cwd)
+   */
+  forkAgent(
+    sourceAgentId: AgentId,
+    options?: { name?: string; prompt?: string; cwd?: string },
   ): Promise<SpawnedAgent>;
 
   // ── Queries ────────────────────────────────────────────────────
@@ -143,7 +166,7 @@ export interface AgentManager {
    */
   getHierarchy(
     agentId: AgentId,
-    options?: HierarchyOptions
+    options?: HierarchyOptions,
   ): AgentHierarchy | null;
 
   // ── Head Manager ───────────────────────────────────────────────
@@ -166,7 +189,7 @@ export interface AgentManager {
    */
   prompt(
     agentId: AgentId,
-    message: string
+    message: string,
   ): AsyncIterable<ExtendedSessionUpdate>;
 
   /**
@@ -186,7 +209,7 @@ export interface AgentManager {
       maxFollowUps?: number;
       /** Callback for each update during prompting */
       onUpdate?: (update: ExtendedSessionUpdate) => void;
-    }
+    },
   ): Promise<{
     doneCalled: boolean;
     doneStatus?: string;
@@ -235,7 +258,7 @@ export interface AgentManager {
   respondToPermission(
     agentId: AgentId,
     requestId: string,
-    optionId: string
+    optionId: string,
   ): boolean;
 
   /**
@@ -247,6 +270,24 @@ export interface AgentManager {
    */
   cancelPermission(agentId: AgentId, requestId: string): boolean;
 
+  /**
+   * Change the permission mode for a running agent at runtime.
+   * Takes effect on the next permission request.
+   *
+   * @param agentId - Agent ID to change permission mode for
+   * @param mode - New permission mode
+   * @returns true if the mode was changed successfully
+   */
+  setPermissionMode(agentId: AgentId, mode: PermissionMode): boolean;
+
+  /**
+   * Get the current permission mode for a running agent.
+   *
+   * @param agentId - Agent ID to query
+   * @returns The current permission mode, or null if no active session
+   */
+  getPermissionMode(agentId: AgentId): PermissionMode | null;
+
   // ── Lifecycle Callbacks ────────────────────────────────────────
 
   /**
@@ -260,15 +301,22 @@ export interface AgentManager {
    * Set a spawn interceptor that transforms SpawnAgentOptions before spawning.
    * Used by TeamRuntime to inject team topics, prompts, MCP servers, and env vars.
    */
-  setSpawnInterceptor(
-    interceptor: SpawnInterceptor | null
-  ): void;
+  setSpawnInterceptor(interceptor: SpawnInterceptor | null): void;
 
   /**
    * Get the RoleRegistry used by this AgentManager.
    */
   getRoleRegistry(): RoleRegistry;
 
+  // ── OpenTasks Socket Path (Late Binding) ─────────────────────
+
+  /**
+   * Set the runtime OpenTasks socket path for propagation to child agents.
+   * Used when createTaskBackend() discovers the daemon socket path after
+   * AgentManager is already created.
+   */
+  setOpenTasksSocketPath(socketPath: string): void;
+
   // ── Mail Services (Late Binding) ─────────────────────────────
 
   /**
@@ -277,7 +325,7 @@ export interface AgentManager {
    */
   setMailServices(
     mailService: import("../mail/mail-service.js").MailService,
-    conversationMap: import("../mail/conversation-map.js").ConversationMap
+    conversationMap: import("../mail/conversation-map.js").ConversationMap,
   ): void;
 
   // ── Cleanup ────────────────────────────────────────────────────
@@ -335,6 +383,38 @@ export interface AgentManagerConfig {
    * Required when mailService is provided.
    */
   conversationMap?: import("../mail/conversation-map.js").ConversationMap;
+
+  /**
+   * Optional server URL for MCP thin-client mode.
+   * When set, spawned agents use ephemeral MAP WebSocket calls instead
+   * of creating local service stacks.
+   */
+  serverUrl?: string;
+
+  /**
+   * Server authentication token for MCP thin-client connections.
+   * Passed to spawned agents as MACRO_SERVER_TOKEN env var.
+   */
+  serverToken?: string;
+
+  /**
+   * Per-agent token manager for MCP bridge authentication.
+   * When provided, generates a unique token per agent at spawn time
+   * and revokes it on terminate.
+   */
+  agentTokenManager?: AgentTokenManager;
+
+  /**
+   * Task backend type to propagate to child MCP subprocesses.
+   * Sourced from merged config. Falls back to MACRO_TASK_BACKEND env var.
+   */
+  taskBackend?: string;
+
+  /**
+   * OpenTasks socket path to propagate to child MCP subprocesses.
+   * Sourced from merged config. Falls back to OPENTASKS_SOCKET_PATH env var.
+   */
+  openTasksSocketPath?: string;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -346,7 +426,7 @@ export interface AgentManagerConfig {
  * Used by TeamRuntime to inject team-specific configuration.
  */
 export type SpawnInterceptor = (
-  options: SpawnAgentOptions
+  options: SpawnAgentOptions,
 ) => SpawnAgentOptions | Promise<SpawnAgentOptions>;
 
 // ─────────────────────────────────────────────────────────────────
@@ -356,7 +436,7 @@ export type SpawnInterceptor = (
 export function createAgentManager(
   eventStore: EventStore,
   messageRouter: MessageRouter,
-  config: AgentManagerConfig = {}
+  config: AgentManagerConfig = {},
 ): AgentManager {
   const {
     defaultPermissionMode = "auto-approve",
@@ -367,8 +447,16 @@ export function createAgentManager(
     healthCheckService,
     mailService: initialMailService,
     conversationMap: initialConversationMap,
+    serverUrl,
+    serverToken,
+    agentTokenManager,
+    taskBackend: configTaskBackend,
+    openTasksSocketPath: initialOpenTasksSocketPath,
   } = config;
 
+  // Mutable OpenTasks socket path (support late binding via setOpenTasksSocketPath)
+  let configOpenTasksSocketPath = initialOpenTasksSocketPath;
+
   // Mutable mail services (support late binding via setMailServices)
   let mailService = initialMailService;
   let conversationMap = initialConversationMap;
@@ -385,11 +473,91 @@ export function createAgentManager(
   // Lifecycle event listeners
   const lifecycleListeners = new Set<AgentLifecycleCallback>();
 
+  // Shutdown guard — prevents spawns during close()
+  let isShuttingDown = false;
+
+  // ─────────────────────────────────────────────────────────────────
+  // MCP Server Config
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Build the macro-agent MCP server config for a Claude Code agent session.
+   * Used by spawn(), resume(), and forkAgent() to ensure every agent gets
+   * access to the macro-agent coordination tools.
+   */
+  function buildMacroAgentMcp(opts: {
+    agentId: string;
+    parentId: string;
+    taskId: string;
+    cwd: string;
+    permissionMode: string;
+    lineage?: string[];
+    sessionId?: string;
+  }) {
+    // Common env vars for both thin-client and legacy modes
+    const env = [
+      { name: "MACRO_AGENT_ID", value: opts.agentId },
+      { name: "MACRO_PARENT_ID", value: opts.parentId },
+      { name: "MACRO_TASK_ID", value: opts.taskId },
+      { name: "MACRO_AGENT_CWD", value: opts.cwd },
+      { name: "MACRO_PERMISSION_MODE", value: opts.permissionMode },
+      {
+        name: "MACRO_TASK_BACKEND",
+        value: configTaskBackend ?? process.env.MACRO_TASK_BACKEND ?? "",
+      },
+      {
+        name: "OPENTASKS_SOCKET_PATH",
+        value: configOpenTasksSocketPath ?? process.env.OPENTASKS_SOCKET_PATH ?? "",
+      },
+    ];
+
+    if (serverUrl) {
+      // Thin-client mode: forward tool calls to main server via MAP WebSocket
+      env.push(
+        { name: "MACRO_SERVER_URL", value: serverUrl },
+        {
+          name: "MACRO_AGENT_LINEAGE",
+          value: JSON.stringify(opts.lineage ?? []),
+        },
+        { name: "MACRO_SESSION_ID", value: opts.sessionId ?? "" },
+      );
+
+      // Auth tokens for thin-client connections
+      if (serverToken) {
+        env.push({ name: "MACRO_SERVER_TOKEN", value: serverToken });
+      }
+      if (agentTokenManager) {
+        const agentToken = agentTokenManager.createToken(opts.agentId);
+        env.push({ name: "MACRO_AGENT_TOKEN", value: agentToken });
+      }
+    } else {
+      // Legacy mode: create local service stack with shared SQLite
+      env.push(
+        { name: "MACRO_INSTANCE_ID", value: eventStore.instanceId },
+        { name: "MACRO_BASE_DIR", value: eventStore.baseDir },
+      );
+    }
+
+    return {
+      name: "macro-agent",
+      command: "npx",
+      args: ["multiagent-mcp"],
+      env,
+    };
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Lifecycle
   // ─────────────────────────────────────────────────────────────────
 
   async function spawn(rawOptions: SpawnAgentOptions): Promise<SpawnedAgent> {
+    if (isShuttingDown) {
+      throw new AgentManagerError(
+        "Cannot spawn agent during shutdown",
+        "SHUTDOWN_IN_PROGRESS",
+      );
+    }
+
     // Apply spawn interceptor if set (used by TeamRuntime for team context injection)
     const options = spawnInterceptor
       ? await spawnInterceptor(rawOptions)
@@ -426,7 +594,7 @@ export function createAgentManager(
         throw new AgentManagerError(
           `Parent agent not found: ${parent}`,
           "AGENT_NOT_FOUND",
-          parent
+          parent,
         );
       }
 
@@ -437,8 +605,12 @@ export function createAgentManager(
 
       // Accept either the specific capability (e.g., agent.spawn.grinder)
       // or the generic agent.spawn.custom as a fallback for non-built-in roles
-      const hasSpecific = roleRegistry.hasCapability(parentRole, requiredCapability);
-      const hasGeneric = requiredCapability !== AGENT_CAPABILITIES.SPAWN_CUSTOM &&
+      const hasSpecific = roleRegistry.hasCapability(
+        parentRole,
+        requiredCapability,
+      );
+      const hasGeneric =
+        requiredCapability !== AGENT_CAPABILITIES.SPAWN_CUSTOM &&
         roleRegistry.hasCapability(parentRole, AGENT_CAPABILITIES.SPAWN_CUSTOM);
 
       if (!hasSpecific && !hasGeneric) {
@@ -446,7 +618,7 @@ export function createAgentManager(
           `Parent agent with role '${parentRole}' does not have capability to spawn '${childRole}' agents. ` +
             `Required capability: ${requiredCapability}`,
           "CAPABILITY_DENIED",
-          parent
+          parent,
         );
       }
     }
@@ -507,6 +679,14 @@ export function createAgentManager(
       },
     });
 
+    // Generate a human-readable default name
+    const generatedName = uniqueNamesGenerator({
+      dictionaries: [adjectives, animals],
+      separator: "-",
+      length: 2,
+    });
+    eventStore.updateAgentMetadata(agentId as AgentId, { name: generatedName });
+
     // Persist immediately so MCP server subprocess can read the agent
     await eventStore.persist();
 
@@ -514,10 +694,10 @@ export function createAgentManager(
     const verifyAgent = eventStore.getAgent(agentId);
     const allAgents = eventStore.listAgents();
     console.error(
-      `[AgentManager] After persist: agent ${agentId} exists = ${!!verifyAgent}, total agents = ${allAgents.length}, instancePath = ${eventStore.instancePath}`
+      `[AgentManager] After persist: agent ${agentId} exists = ${!!verifyAgent}, total agents = ${allAgents.length}, instancePath = ${eventStore.instancePath}`,
     );
     console.error(
-      `[AgentManager] All agent IDs: ${allAgents.map((a) => a.id).join(", ")}`
+      `[AgentManager] All agent IDs: ${allAgents.map((a) => a.id).join(", ")}`,
     );
 
     try {
@@ -527,195 +707,207 @@ export function createAgentManager(
         env: agentConfig?.env,
       });
 
-      // Build MCP server configuration for the macro-agent MCP server
-      // Note: McpServerStdio doesn't have a 'type' field - stdio is the implicit default
-      // when neither 'type: http' nor 'type: sse' is specified
-      const macroAgentMcp = {
-        name: "macro-agent",
-        command: "npx",
-        args: ["multiagent-mcp"],
-        env: [
-          { name: "MACRO_AGENT_ID", value: agentId },
-          { name: "MACRO_PARENT_ID", value: parent ?? "" },
-          { name: "MACRO_TASK_ID", value: taskId },
-          { name: "MACRO_AGENT_CWD", value: cwd },
-          { name: "MACRO_INSTANCE_ID", value: eventStore.instanceId },
-          { name: "MACRO_BASE_DIR", value: eventStore.baseDir },
-        ],
-      };
-
-      // Combine with any user-provided MCP servers
-      // Note: Like macroAgentMcp, user MCP servers use stdio (no 'type' field)
-      const userMcpServers =
-        agentConfig?.mcpServers?.map((s) => ({
-          name: s.name,
-          command: s.command,
-          args: s.args ?? [],
-          env: s.env
-            ? Object.entries(s.env).map(([name, value]) => ({ name, value }))
+      try {
+        const macroAgentMcp = buildMacroAgentMcp({
+          agentId,
+          parentId: parent ?? "",
+          taskId,
+          cwd,
+          permissionMode,
+          lineage: parentAgent?.lineage
+            ? [...parentAgent.lineage, parent!]
             : [],
-        })) ?? [];
-
-      // Create session with MCP servers
-      // Note: The MCP server subprocess will start here and look for the agent
-      // in EventStore. We already persisted the spawn event above.
-      const session = await handle.createSession(cwd, {
-        mcpServers: [macroAgentMcp, ...userMcpServers],
-      });
-
-      // Emit started status (session is ready)
-      // Include the provider's session ID (e.g., Claude Code UUID) so
-      // it can be used for handle.loadSession() during resume
-      eventStore.emit({
-        type: "status",
-        source: { agent_id: agentId },
-        payload: {
-          status_type: "started",
-          summary: "Agent session started",
-          provider_session_id: session.id,
-        },
-      });
-
-      // Persist the status event
-      await eventStore.persist();
-
-      // Set up default subscriptions via MessageRouter
-      messageRouter.setupDefaultSubscriptions({
-        agent_id: agentId,
-        parent_id: parent ?? undefined,
-        task_id: taskId,
-        subscribe_parent: subscribeParent,
-        additional_topics: topics,
-        role: role ?? undefined,
-      });
+          sessionId,
+        });
 
-      // ─────────────────────────────────────────────────────────────────
-      // Mail: Create task conversation for this agent
-      // ─────────────────────────────────────────────────────────────────
-      if (mailService && conversationMap) {
-        try {
-          const parentConversationId = parent
-            ? conversationMap.getAgentConversation(parent) ??
-              conversationMap.getSessionConversation(parent)
+        // Combine with any user-provided MCP servers
+        // Note: Like macroAgentMcp, user MCP servers use stdio (no 'type' field)
+        const userMcpServers =
+          agentConfig?.mcpServers?.map((s) => ({
+            name: s.name,
+            command: s.command,
+            args: s.args ?? [],
+            env: s.env
+              ? Object.entries(s.env).map(([name, value]) => ({ name, value }))
+              : [],
+          })) ?? [];
+
+        // Create session with MCP servers
+        // Note: The MCP server subprocess will start here and look for the agent
+        // in EventStore. We already persisted the spawn event above.
+        //
+        // When permissionMode is "interactive", we strip settingSources so that
+        // the Claude Code subprocess doesn't read pre-approved tool rules from
+        // the user's ~/.claude/settings.local.json. This ensures ALL tool calls
+        // go through the canUseTool → requestPermission ACP flow.
+        const agentMeta =
+          permissionMode === "interactive"
+            ? { claudeCode: { options: { settingSources: [] } } }
             : undefined;
+        const session = await handle.createSession(cwd, {
+          mcpServers: [macroAgentMcp, ...userMcpServers],
+          ...(agentMeta && { agentMeta }),
+        });
 
-          const { conversationId: taskConvId } =
-            mailService.createConversation({
-              type: "task",
-              subject: task?.slice(0, 80),
-              createdBy: parent ?? agentId,
-              parentConversationId: parentConversationId,
-            });
+        // Emit started status (session is ready)
+        // Include the provider's session ID (e.g., Claude Code UUID) so
+        // it can be used for handle.loadSession() during resume
+        eventStore.emit({
+          type: "status",
+          source: { agent_id: agentId },
+          payload: {
+            status_type: "started",
+            summary: "Agent session started",
+            provider_session_id: session.id,
+          },
+        });
 
-          // Join parent and child as participants
-          if (parent) {
+        // Persist the status event
+        await eventStore.persist();
+
+        // Set up default subscriptions via MessageRouter
+        messageRouter.setupDefaultSubscriptions({
+          agent_id: agentId,
+          parent_id: parent ?? undefined,
+          task_id: taskId,
+          subscribe_parent: subscribeParent,
+          additional_topics: topics,
+          role: role ?? undefined,
+        });
+
+        // ─────────────────────────────────────────────────────────────────
+        // Mail: Create task conversation for this agent
+        // ─────────────────────────────────────────────────────────────────
+        if (mailService && conversationMap) {
+          try {
+            const parentConversationId = parent
+              ? (conversationMap.getAgentConversation(parent) ??
+                conversationMap.getSessionConversation(parent))
+              : undefined;
+
+            const { conversationId: taskConvId } =
+              mailService.createConversation({
+                type: "task",
+                subject: task?.slice(0, 80),
+                createdBy: parent ?? agentId,
+                parentConversationId: parentConversationId,
+              });
+
+            // Join parent and child as participants
+            if (parent) {
+              mailService.joinConversation({
+                conversationId: taskConvId,
+                participantId: parent,
+                participantType: "agent",
+                role: "initiator",
+                agentId: parent,
+              });
+            }
             mailService.joinConversation({
               conversationId: taskConvId,
-              participantId: parent,
+              participantId: agentId,
               participantType: "agent",
-              role: "initiator",
-              agentId: parent,
+              role: "worker",
+              agentId,
             });
-          }
-          mailService.joinConversation({
-            conversationId: taskConvId,
-            participantId: agentId,
-            participantType: "agent",
-            role: "worker",
-            agentId,
-          });
 
-          conversationMap.setAgentConversation(agentId, taskConvId);
-        } catch (err) {
-          // Never fail spawn due to mail errors
-          console.warn(
-            `[AgentManager] Failed to create task conversation for ${agentId}:`,
-            err
-          );
+            conversationMap.setAgentConversation(agentId, taskConvId);
+          } catch (err) {
+            // Never fail spawn due to mail errors
+            console.warn(
+              `[AgentManager] Failed to create task conversation for ${agentId}:`,
+              err,
+            );
+          }
         }
-      }
 
-      // Track active session
-      const activeSession: ActiveSession = {
-        agentId,
-        handle,
-        session,
-        createdAt: Date.now(),
-        isPrompting: false,
-      };
-      activeSessions.set(agentId, activeSession);
+        // Track active session
+        const activeSession: ActiveSession = {
+          agentId,
+          handle,
+          session,
+          createdAt: Date.now(),
+          isPrompting: false,
+        };
+        activeSessions.set(agentId, activeSession);
 
-      // Get the agent from materialized view
-      const agent = eventStore.getAgent(agentId)!;
+        // Get the agent from materialized view
+        const agent = eventStore.getAgent(agentId)!;
 
-      // ─────────────────────────────────────────────────────────────────
-      // Workspace Creation (Phase 2)
-      // ─────────────────────────────────────────────────────────────────
-      let workspace: Workspace | undefined;
-      let resolvedStreamId = streamId;
+        // ─────────────────────────────────────────────────────────────────
+        // Workspace Creation (Phase 2)
+        // ─────────────────────────────────────────────────────────────────
+        let workspace: Workspace | undefined;
+        let resolvedStreamId = streamId;
 
-      if (workspaceManager && role) {
-        try {
-          workspace = await createWorkspaceForRole(
-            workspaceManager,
-            agentId,
-            role,
-            {
-              streamId,
-              streamConfig,
-              dataplaneTaskId,
-              cwd,
-            }
-          );
-
-          if (workspace) {
-            agentWorkspaces.set(agentId, workspace);
-            resolvedStreamId = workspace.streamId;
-
-            // Register with parent coordinator if applicable
-            if (
-              parent &&
-              (role === "worker" || role === "integrator")
-            ) {
-              const parentWorkspace = agentWorkspaces.get(parent);
-              if (parentWorkspace?.role === "coordinator") {
-                workspaceManager.registerChildWorkspace(
-                  parent,
-                  agentId,
-                  workspace.path
-                );
+        if (workspaceManager && role) {
+          try {
+            workspace = await createWorkspaceForRole(
+              workspaceManager,
+              agentId,
+              role,
+              {
+                streamId,
+                streamConfig,
+                dataplaneTaskId,
+                cwd,
+              },
+            );
+
+            if (workspace) {
+              agentWorkspaces.set(agentId, workspace);
+              resolvedStreamId = workspace.streamId;
+
+              // Register with parent coordinator if applicable
+              if (parent && (role === "worker" || role === "integrator")) {
+                const parentWorkspace = agentWorkspaces.get(parent);
+                if (parentWorkspace?.role === "coordinator") {
+                  workspaceManager.registerChildWorkspace(
+                    parent,
+                    agentId,
+                    workspace.path,
+                  );
+                }
               }
             }
+          } catch (wsError) {
+            console.error(
+              `[AgentManager] Failed to create workspace for ${agentId}: ${wsError}`,
+            );
+            // Continue without workspace - don't fail the spawn
           }
-        } catch (wsError) {
-          console.error(
-            `[AgentManager] Failed to create workspace for ${agentId}: ${wsError}`
-          );
-          // Continue without workspace - don't fail the spawn
         }
-      }
 
-      // Notify lifecycle listeners
-      notifyLifecycle({ type: "spawned", agent });
-      notifyLifecycle({ type: "started", agent });
+        // Notify lifecycle listeners
+        notifyLifecycle({ type: "spawned", agent });
+        notifyLifecycle({ type: "started", agent });
 
-      // Start health monitoring for coordinators
-      if (healthCheckService && role === "coordinator") {
-        healthCheckService.startForCoordinator(agentId);
-      }
+        // Start health monitoring for coordinators
+        if (healthCheckService && role === "coordinator") {
+          healthCheckService.startForCoordinator(agentId);
+        }
 
-      return {
-        id: agentId,
-        session_id: sessionId, // Macro-agent's own session ID for ACP protocol mapping
-        agent,
-        session,
-        workspace,
-        streamId: resolvedStreamId,
-      };
+        return {
+          id: agentId,
+          session_id: sessionId, // Macro-agent's own session ID for ACP protocol mapping
+          agent,
+          session,
+          workspace,
+          streamId: resolvedStreamId,
+        };
+      } catch (handleError) {
+        // Close the spawned process to prevent orphaning
+        try {
+          await handle.close();
+        } catch {
+          // Ignore errors during cleanup
+        }
+        throw handleError;
+      }
     } catch (error) {
       // Clean up the spawn event we already emitted
       eventStore.emit({
-        type: "terminate",
+        type: "stop",
         source: { agent_id: agentId },
         payload: {
           reason: "failed",
@@ -726,21 +918,21 @@ export function createAgentManager(
       throw new AgentManagerError(
         `Failed to spawn agent: ${error}`,
         "SPAWN_FAILED",
-        agentId
+        agentId,
       );
     }
   }
 
   async function terminate(
     agentId: AgentId,
-    reason: AgentStopReason
+    reason: AgentStopReason,
   ): Promise<void> {
     const agent = eventStore.getAgent(agentId);
     if (!agent) {
       throw new AgentManagerError(
         `Agent not found: ${agentId}`,
         "AGENT_NOT_FOUND",
-        agentId
+        agentId,
       );
     }
 
@@ -769,12 +961,17 @@ export function createAgentManager(
         agentWorkspaces.delete(agentId);
       } catch (wsError) {
         console.error(
-          `[AgentManager] Failed to deallocate workspace for ${agentId}: ${wsError}`
+          `[AgentManager] Failed to deallocate workspace for ${agentId}: ${wsError}`,
         );
         // Continue with termination even if workspace cleanup fails
       }
     }
 
+    // Revoke agent authentication token
+    if (agentTokenManager) {
+      agentTokenManager.revokeToken(agentId);
+    }
+
     // ─────────────────────────────────────────────────────────────────
     // Mail: Close task conversation on terminate
     // ─────────────────────────────────────────────────────────────────
@@ -789,8 +986,7 @@ export function createAgentManager(
           });
         }
         // Close any peer conversations
-        const peerConvIds =
-          conversationMap.closePeerConversationsFor(agentId);
+        const peerConvIds = conversationMap.closePeerConversationsFor(agentId);
         for (const peerConvId of peerConvIds) {
           mailService.closeConversation({
             conversationId: peerConvId,
@@ -802,14 +998,14 @@ export function createAgentManager(
       } catch (err) {
         console.warn(
           `[AgentManager] Failed to close conversation for ${agentId}:`,
-          err
+          err,
         );
       }
     }
 
-    // Emit terminate event
+    // Emit stop event
     eventStore.emit({
-      type: "terminate",
+      type: "stop",
       source: { agent_id: agentId },
       payload: {
         agent_id: agentId,
@@ -876,19 +1072,30 @@ export function createAgentManager(
           child.id,
           agentId,
           cascadeAdapter,
-          workspaceProvider
+          workspaceProvider,
         );
       }
     }
   }
 
-  async function resume(agentId: AgentId): Promise<SpawnedAgent> {
+  async function resume(
+    agentId: AgentId,
+    overridePermissionMode?: PermissionMode,
+  ): Promise<SpawnedAgent> {
+    if (isShuttingDown) {
+      throw new AgentManagerError(
+        "Cannot resume agent during shutdown",
+        "SHUTDOWN_IN_PROGRESS",
+        agentId,
+      );
+    }
+
     const agent = eventStore.getAgent(agentId);
     if (!agent) {
       throw new AgentManagerError(
         `Agent not found: ${agentId}`,
         "AGENT_NOT_FOUND",
-        agentId
+        agentId,
       );
     }
 
@@ -897,66 +1104,260 @@ export function createAgentManager(
       throw new AgentManagerError(
         `Agent already has active session: ${agentId}`,
         "ALREADY_RUNNING",
-        agentId
+        agentId,
       );
     }
 
+    const permissionMode = overridePermissionMode ?? defaultPermissionMode;
+
     // Spawn new process
     const handle = await AgentFactory.spawn(defaultAgentType, {
-      permissionMode: defaultPermissionMode,
+      permissionMode,
     });
 
-    const agentCwd = agent.cwd ?? defaultCwd;
-    let session;
+    try {
+      const agentCwd = agent.cwd ?? defaultCwd;
+      let session;
 
-    if (agent.provider_session_id) {
-      // Load existing session using the provider's session ID (e.g., Claude Code UUID)
-      session = await handle.loadSession(agent.provider_session_id, agentCwd);
-    } else {
-      // No provider session ID available (agent predates this feature or wasn't persisted).
-      // Create a new session instead of loading with the macro-agent session_id
-      // which is not a valid provider session ID (e.g., Claude Code expects UUIDs).
-      session = await handle.createSession(agentCwd);
+      // When interactive mode, strip settings to prevent auto-approval
+      const resumeAgentMeta =
+        permissionMode === "interactive"
+          ? { claudeCode: { options: { settingSources: [] } } }
+          : undefined;
+
+      const macroAgentMcp = buildMacroAgentMcp({
+        agentId,
+        parentId: agent.parent ?? "",
+        taskId: agent.task_id ?? "",
+        cwd: agentCwd,
+        permissionMode,
+        lineage: agent.lineage ?? [],
+        sessionId: agent.session_id ?? "",
+      });
+      const mcpServers = [macroAgentMcp];
+
+      if (agent.provider_session_id) {
+        // Load existing session using the provider's session ID (e.g., Claude Code UUID)
+        // Note: loadSession's TS type for mcpServers is { name, uri }[] but
+        // the underlying ACP protocol accepts full McpServerStdio. The JS
+        // implementation passes mcpServers through to the connection unchanged.
+        session = await handle.loadSession(
+          agent.provider_session_id,
+          agentCwd,
+          mcpServers as any,
+          resumeAgentMeta ? { agentMeta: resumeAgentMeta } : undefined,
+        );
+      } else {
+        // No provider session ID available (agent predates this feature or wasn't persisted).
+        // Create a new session instead of loading with the macro-agent session_id
+        // which is not a valid provider session ID (e.g., Claude Code expects UUIDs).
+        session = await handle.createSession(agentCwd, {
+          mcpServers,
+          ...(resumeAgentMeta && { agentMeta: resumeAgentMeta }),
+        });
+
+        // Store the provider session ID for future resumes
+        eventStore.emit({
+          type: "status",
+          source: { agent_id: agentId },
+          payload: {
+            status_type: "started",
+            summary: "Agent session created (no provider session to resume)",
+            provider_session_id: session.id,
+          },
+        });
+      }
+
+      // Track active session
+      const activeSession: ActiveSession = {
+        agentId,
+        handle,
+        session,
+        createdAt: Date.now(),
+        isPrompting: false,
+      };
+      activeSessions.set(agentId, activeSession);
 
-      // Store the provider session ID for future resumes
+      // Emit status event for resume
       eventStore.emit({
         type: "status",
         source: { agent_id: agentId },
         payload: {
           status_type: "started",
-          summary: "Agent session created (no provider session to resume)",
+          summary: "Agent session resumed",
           provider_session_id: session.id,
         },
       });
+
+      return {
+        id: agentId,
+        session_id: agent.session_id, // Macro-agent's own session ID
+        agent: eventStore.getAgent(agentId)!,
+        session,
+      };
+    } catch (handleError) {
+      // Close the spawned process to prevent orphaning
+      try {
+        await handle.close();
+      } catch {
+        // Ignore errors during cleanup
+      }
+      throw handleError;
     }
+  }
 
-    // Track active session
-    const activeSession: ActiveSession = {
-      agentId,
-      handle,
-      session,
-      createdAt: Date.now(),
-      isPrompting: false,
-    };
-    activeSessions.set(agentId, activeSession);
+  // ─────────────────────────────────────────────────────────────────
+  // Fork
+  // ─────────────────────────────────────────────────────────────────
+
+  async function forkAgent(
+    sourceAgentId: AgentId,
+    options?: { name?: string; prompt?: string; cwd?: string },
+  ): Promise<SpawnedAgent> {
+    if (isShuttingDown) {
+      throw new AgentManagerError(
+        "Cannot fork agent during shutdown",
+        "SHUTDOWN_IN_PROGRESS",
+        sourceAgentId,
+      );
+    }
+
+    const sourceAgent = eventStore.getAgent(sourceAgentId);
+    if (!sourceAgent) {
+      throw new AgentManagerError(
+        `Agent not found: ${sourceAgentId}`,
+        "AGENT_NOT_FOUND",
+        sourceAgentId,
+      );
+    }
 
-    // Emit status event for resume
+    // Need either an active session or a persisted provider_session_id
+    const activeSession = activeSessions.get(sourceAgentId);
+    if (!activeSession && !sourceAgent.provider_session_id) {
+      throw new AgentManagerError(
+        `Agent has no session to fork: ${sourceAgentId}`,
+        "FORK_NOT_SUPPORTED",
+        sourceAgentId,
+      );
+    }
+
+    // Generate new IDs
+    const agentId = `agent_${nanoid(12)}`;
+    const taskId = `task_${nanoid(12)}`;
+    const sessionId = `session_${nanoid(12)}`;
+    const cwd = options?.cwd ?? sourceAgent.cwd ?? defaultCwd;
+
+    // Emit spawn event with fork metadata
     eventStore.emit({
-      type: "status",
-      source: { agent_id: agentId },
+      type: "spawn",
+      source: { agent_id: sourceAgentId },
       payload: {
-        status_type: "started",
-        summary: "Agent session resumed",
-        provider_session_id: session.id,
+        agent_id: agentId,
+        session_id: sessionId,
+        task: options?.name ?? `[Fork of ${sourceAgentId}]`,
+        task_id: taskId,
+        parent: sourceAgent.parent ?? null,
+        role: sourceAgent.role ?? undefined,
+        config: {},
+        cwd,
+        metadata: { fork_of: sourceAgentId },
       },
     });
 
-    return {
-      id: agentId,
-      session_id: agent.session_id, // Macro-agent's own session ID
-      agent: eventStore.getAgent(agentId)!,
-      session,
-    };
+    // Generate a human-readable name
+    const generatedName = uniqueNamesGenerator({
+      dictionaries: [adjectives, animals],
+      separator: "-",
+      length: 2,
+    });
+    eventStore.updateAgentMetadata(agentId as AgentId, { name: generatedName });
+    await eventStore.persist();
+
+    // Get the provider session ID to fork from
+    let forkedProviderSessionId: string;
+    if (activeSession) {
+      // Active session: fork with flush to ensure data is persisted
+      const forkedSession = await activeSession.session.forkWithFlush();
+      forkedProviderSessionId = forkedSession.id;
+    } else {
+      // Stopped agent: use the persisted provider session ID directly
+      forkedProviderSessionId = sourceAgent.provider_session_id!;
+    }
+
+    // Spawn a new process
+    const handle = await AgentFactory.spawn(defaultAgentType, {
+      permissionMode: defaultPermissionMode,
+    });
+
+    try {
+      const macroAgentMcp = buildMacroAgentMcp({
+        agentId,
+        parentId: sourceAgent.parent ?? "",
+        taskId,
+        cwd,
+        permissionMode: defaultPermissionMode,
+        lineage: sourceAgent.lineage ?? [],
+        sessionId,
+      });
+
+      // Load the forked session on the new process with correct MCP config.
+      // Note: loadSession's TS type for mcpServers is { name, uri }[] but
+      // the underlying ACP protocol accepts full McpServerStdio. The JS
+      // implementation passes mcpServers through to the connection unchanged.
+      const session = await handle.loadSession(forkedProviderSessionId, cwd, [
+        macroAgentMcp,
+      ] as any);
+
+      // Emit started status with provider session ID
+      eventStore.emit({
+        type: "status",
+        source: { agent_id: agentId },
+        payload: {
+          status_type: "started",
+          summary: "Agent session started (forked)",
+          provider_session_id: session.id,
+        },
+      });
+      await eventStore.persist();
+
+      // Set up message router subscriptions
+      messageRouter.setupDefaultSubscriptions({
+        agent_id: agentId,
+        parent_id: sourceAgent.parent ?? undefined,
+        task_id: taskId,
+        subscribe_parent: false,
+        additional_topics: [],
+        role: sourceAgent.role ?? undefined,
+      });
+
+      // Track active session
+      const newActiveSession: ActiveSession = {
+        agentId,
+        handle,
+        session,
+        createdAt: Date.now(),
+        isPrompting: false,
+      };
+      activeSessions.set(agentId, newActiveSession);
+
+      const agent = eventStore.getAgent(agentId)!;
+      notifyLifecycle({ type: "spawned", agent });
+      notifyLifecycle({ type: "started", agent });
+
+      return {
+        id: agentId,
+        session_id: sessionId,
+        agent,
+        session,
+      };
+    } catch (handleError) {
+      try {
+        await handle.close();
+      } catch {
+        // Ignore errors during cleanup
+      }
+      throw handleError;
+    }
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -994,7 +1395,7 @@ export function createAgentManager(
 
   function getHierarchy(
     agentId: AgentId,
-    options?: HierarchyOptions
+    options?: HierarchyOptions,
   ): AgentHierarchy | null {
     const agent = eventStore.getAgent(agentId);
     if (!agent) return null;
@@ -1035,7 +1436,7 @@ export function createAgentManager(
   // ─────────────────────────────────────────────────────────────────
 
   async function getOrCreateHeadManager(
-    options: HeadManagerOptions
+    options: HeadManagerOptions,
   ): Promise<SpawnedAgent> {
     const {
       cwd,
@@ -1107,14 +1508,14 @@ export function createAgentManager(
 
   async function* prompt(
     agentId: AgentId,
-    message: string
+    message: string,
   ): AsyncIterable<ExtendedSessionUpdate> {
     const activeSession = activeSessions.get(agentId);
     if (!activeSession) {
       throw new AgentManagerError(
         `No active session for agent: ${agentId}`,
         "SESSION_NOT_FOUND",
-        agentId
+        agentId,
       );
     }
 
@@ -1139,7 +1540,7 @@ export function createAgentManager(
       maxFollowUps?: number;
       throwOnMaxExceeded?: boolean;
       onUpdate?: (update: ExtendedSessionUpdate) => void;
-    }
+    },
   ): Promise<{
     doneCalled: boolean;
     doneStatus?: string;
@@ -1156,7 +1557,10 @@ export function createAgentManager(
     // Helper to check if done() was called by looking for status events
     // The done() MCP tool emits status events with status_type completed/failed
     // and includes signal: "WORKER_DONE" in the details
-    const checkDoneCalled = async (): Promise<{ called: boolean; status?: string }> => {
+    const checkDoneCalled = async (): Promise<{
+      called: boolean;
+      status?: string;
+    }> => {
       // Reload from disk to see events from MCP subprocess
       await eventStore.reload();
       const statusEvents = eventStore.query({ type: "status" });
@@ -1166,14 +1570,15 @@ export function createAgentManager(
         (e) =>
           e.source?.agent_id === agentId &&
           (e.payload?.status_type === "completed" ||
-           e.payload?.status_type === "failed" ||
-           (e.payload?.details as Record<string, unknown>)?.signal === "WORKER_DONE")
+            e.payload?.status_type === "failed" ||
+            (e.payload?.details as Record<string, unknown>)?.signal ===
+              "WORKER_DONE"),
       );
 
       if (agentCompletedStatus) {
         return {
           called: true,
-          status: agentCompletedStatus.payload?.status_type as string
+          status: agentCompletedStatus.payload?.status_type as string,
         };
       }
 
@@ -1213,7 +1618,8 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
 
     for (let i = 0; i < maxFollowUps; i++) {
       followUpCount++;
-      const followUpMessage = followUpMessages[Math.min(i, followUpMessages.length - 1)];
+      const followUpMessage =
+        followUpMessages[Math.min(i, followUpMessages.length - 1)];
 
       // Send follow-up prompt
       for await (const update of prompt(agentId, followUpMessage)) {
@@ -1238,7 +1644,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     if (throwOnMaxExceeded) {
       throw new Error(
         `Agent ${agentId} did not call done() after ${maxFollowUps} follow-up attempts. ` +
-        `Total prompts sent: ${1 + followUpCount}. Consider increasing maxFollowUps or investigating agent behavior.`
+          `Total prompts sent: ${1 + followUpCount}. Consider increasing maxFollowUps or investigating agent behavior.`,
       );
     }
 
@@ -1293,12 +1699,12 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
   function respondToPermission(
     agentId: AgentId,
     requestId: string,
-    optionId: string
+    optionId: string,
   ): boolean {
     const activeSession = activeSessions.get(agentId);
     if (!activeSession) {
       console.warn(
-        `[AgentManager] Cannot respond to permission: no active session for agent ${agentId}`
+        `[AgentManager] Cannot respond to permission: no active session for agent ${agentId}`,
       );
       return false;
     }
@@ -1306,13 +1712,13 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     try {
       activeSession.session.respondToPermission(requestId, optionId);
       console.log(
-        `[AgentManager] Responded to permission ${requestId} for agent ${agentId} with ${optionId}`
+        `[AgentManager] Responded to permission ${requestId} for agent ${agentId} with ${optionId}`,
       );
       return true;
     } catch (err) {
       console.error(
         `[AgentManager] Error responding to permission ${requestId}:`,
-        err
+        err,
       );
       return false;
     }
@@ -1322,7 +1728,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     const activeSession = activeSessions.get(agentId);
     if (!activeSession) {
       console.warn(
-        `[AgentManager] Cannot cancel permission: no active session for agent ${agentId}`
+        `[AgentManager] Cannot cancel permission: no active session for agent ${agentId}`,
       );
       return false;
     }
@@ -1330,18 +1736,50 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     try {
       activeSession.session.cancelPermission(requestId);
       console.log(
-        `[AgentManager] Cancelled permission ${requestId} for agent ${agentId}`
+        `[AgentManager] Cancelled permission ${requestId} for agent ${agentId}`,
       );
       return true;
     } catch (err) {
       console.error(
         `[AgentManager] Error cancelling permission ${requestId}:`,
-        err
+        err,
+      );
+      return false;
+    }
+  }
+
+  function setPermissionMode(agentId: AgentId, mode: PermissionMode): boolean {
+    const activeSession = activeSessions.get(agentId);
+    if (!activeSession) {
+      console.warn(
+        `[AgentManager] Cannot set permission mode: no active session for agent ${agentId}`,
+      );
+      return false;
+    }
+
+    try {
+      activeSession.handle.setPermissionMode(mode);
+      console.log(
+        `[AgentManager] Set permission mode for agent ${agentId} to ${mode}`,
+      );
+      return true;
+    } catch (err) {
+      console.error(
+        `[AgentManager] Error setting permission mode for agent ${agentId}:`,
+        err,
       );
       return false;
     }
   }
 
+  function getPermissionMode(agentId: AgentId): PermissionMode | null {
+    const activeSession = activeSessions.get(agentId);
+    if (!activeSession) {
+      return null;
+    }
+    return activeSession.handle.getPermissionMode();
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Lifecycle Callbacks
   // ─────────────────────────────────────────────────────────────────
@@ -1361,13 +1799,21 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     }
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // OpenTasks Socket Path (Late Binding)
+  // ─────────────────────────────────────────────────────────────────
+
+  function setOpenTasksSocketPath(socketPath: string): void {
+    configOpenTasksSocketPath = socketPath;
+  }
+
   // ─────────────────────────────────────────────────────────────────
   // Mail Services (Late Binding)
   // ─────────────────────────────────────────────────────────────────
 
   function setMailServices(
     ms: import("../mail/mail-service.js").MailService,
-    cm: import("../mail/conversation-map.js").ConversationMap
+    cm: import("../mail/conversation-map.js").ConversationMap,
   ): void {
     mailService = ms;
     conversationMap = cm;
@@ -1378,6 +1824,9 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
   // ─────────────────────────────────────────────────────────────────
 
   async function close(): Promise<void> {
+    // Prevent new spawns/resumes from racing with cleanup
+    isShuttingDown = true;
+
     // Stop all health checks
     if (healthCheckService) {
       healthCheckService.stopAll();
@@ -1393,7 +1842,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
           } catch {
             // Ignore errors during cleanup
           }
-        })()
+        })(),
       );
     }
 
@@ -1416,14 +1865,14 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
    */
   async function continueAgent(
     agentId: AgentId,
-    options?: ContinueAgentOptions
+    options?: ContinueAgentOptions,
   ): Promise<SpawnedAgent> {
     const agent = eventStore.getAgent(agentId);
     if (!agent) {
       throw new AgentManagerError(
         `Agent not found: ${agentId}`,
         "AGENT_NOT_FOUND",
-        agentId
+        agentId,
       );
     }
 
@@ -1443,7 +1892,9 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
 
     if (events.length > 0) {
       contextLines.push("## Prior Session Context");
-      contextLines.push(`Continuing from agent ${agentId} (${events.length} events).`);
+      contextLines.push(
+        `Continuing from agent ${agentId} (${events.length} events).`,
+      );
       for (const event of events.slice(-20)) {
         const summary = event.payload?.summary;
         if (summary && typeof summary === "string") {
@@ -1456,9 +1907,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
 
     // Spawn a continuation agent with same role, task, and context
     const taskDescription =
-      options?.task ??
-      agent.task ??
-      `Continue work from ${agentId}`;
+      options?.task ?? agent.task ?? `Continue work from ${agentId}`;
 
     const newAgent = await spawn({
       task: taskDescription,
@@ -1487,6 +1936,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     terminate,
     resume,
     continueAgent,
+    forkAgent,
     get,
     list,
     getChildren,
@@ -1502,9 +1952,12 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     isProcessRunning,
     respondToPermission,
     cancelPermission,
+    setPermissionMode,
+    getPermissionMode,
     onLifecycleEvent,
     setSpawnInterceptor,
     getRoleRegistry,
+    setOpenTasksSocketPath,
     setMailServices,
     close,
   };
@@ -1534,7 +1987,7 @@ async function createWorkspaceForRole(
   workspaceManager: WorkspaceManager,
   agentId: AgentId,
   role: string,
-  options: CreateWorkspaceOptions
+  options: CreateWorkspaceOptions,
 ): Promise<Workspace | undefined> {
   const { streamId, streamConfig, dataplaneTaskId } = options;
 
@@ -1543,14 +1996,14 @@ async function createWorkspaceForRole(
       // Coordinators create a new integration stream
       if (!streamConfig) {
         console.warn(
-          `[AgentManager] Coordinator ${agentId} spawn missing streamConfig, skipping workspace`
+          `[AgentManager] Coordinator ${agentId} spawn missing streamConfig, skipping workspace`,
         );
         return undefined;
       }
 
       const newStreamId = workspaceManager.createIntegrationStream(
         agentId,
-        streamConfig
+        streamConfig,
       );
 
       return workspaceManager.createCoordinatorWorkspace(agentId, newStreamId);
@@ -1560,7 +2013,7 @@ async function createWorkspaceForRole(
       // Integrators join an existing stream
       if (!streamId) {
         console.warn(
-          `[AgentManager] Integrator ${agentId} spawn missing streamId, skipping workspace`
+          `[AgentManager] Integrator ${agentId} spawn missing streamId, skipping workspace`,
         );
         return undefined;
       }
@@ -1573,7 +2026,7 @@ async function createWorkspaceForRole(
       // Workers need streamId and either dataplaneTaskId or create a new task
       if (!streamId) {
         console.warn(
-          `[AgentManager] Worker ${agentId} spawn missing streamId, skipping workspace`
+          `[AgentManager] Worker ${agentId} spawn missing streamId, skipping workspace`,
         );
         return undefined;
       }
@@ -1582,7 +2035,7 @@ async function createWorkspaceForRole(
       const taskId = dataplaneTaskId;
       if (!taskId) {
         console.warn(
-          `[AgentManager] Worker ${agentId} spawn missing dataplaneTaskId, skipping workspace`
+          `[AgentManager] Worker ${agentId} spawn missing dataplaneTaskId, skipping workspace`,
         );
         return undefined;
       }