macro-agent 0.1.0 → 0.1.2

package/dist/agent/agent-manager.js

@@ -7,6 +7,7 @@
  * - MessageRouter for subscription setup
  */
 import { nanoid } from "nanoid";
+import { uniqueNamesGenerator, adjectives, animals, } from "unique-names-generator";
 import { AgentFactory, } from "acp-factory";
 import { AgentManagerError } from "./types.js";
 import { AGENT_CAPABILITIES } from "../roles/capabilities.js";
@@ -45,7 +46,9 @@ function getSpawnCapability(childRole) {
 // AgentManager Implementation
 // ─────────────────────────────────────────────────────────────────
 export function createAgentManager(eventStore, messageRouter, config = {}) {
-    const { defaultPermissionMode = "auto-approve", defaultAgentType = "claude-code", defaultCwd = process.cwd(), workspaceManager, roleRegistry = new DefaultRoleRegistry(), healthCheckService, mailService: initialMailService, conversationMap: initialConversationMap, } = config;
+    const { defaultPermissionMode = "auto-approve", defaultAgentType = "claude-code", defaultCwd = process.cwd(), workspaceManager, roleRegistry = new DefaultRoleRegistry(), 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;
@@ -57,17 +60,76 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
     const agentWorkspaces = new Map();
     // Lifecycle event listeners
     const lifecycleListeners = new Set();
+    // 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) {
+        // 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 ?? "",
+            },
+            // Pass streamId so MCP subprocess can include it in lifecycle context
+            // (WorkspaceManager is not available in subprocess)
+            { name: "MACRO_STREAM_ID", value: opts.streamId ?? "" },
+        ];
+        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) {
+        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)
             : rawOptions;
         const { task, task_id, parent, cwd = defaultCwd, permissionMode = defaultPermissionMode, subscribeParent = true, topics = [], config: agentConfig, agentType = defaultAgentType, customPrompt, interactionPatterns, 
         // Workspace-related fields (Phase 2)
-        role, streamId, streamConfig, dataplaneTaskId, } = options;
+        role, team_instance, streamId, streamConfig, dataplaneTaskId, capabilities, } = options;
         // Generate IDs upfront (including session_id so we can persist before starting MCP)
         const agentId = `agent_${nanoid(12)}`;
         const taskId = task_id ?? `task_${nanoid(12)}`;
@@ -140,10 +202,18 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
                 task_id: taskId,
                 parent: parent ?? null,
                 role: role ?? undefined,
+                team_instance: team_instance ?? undefined,
                 config: agentConfig ?? {},
                 cwd,
             },
         });
+        // Generate a human-readable default name
+        const generatedName = uniqueNamesGenerator({
+            dictionaries: [adjectives, animals],
+            separator: "-",
+            length: 2,
+        });
+        eventStore.updateAgentMetadata(agentId, { name: generatedName });
         // Persist immediately so MCP server subprocess can read the agent
         await eventStore.persist();
         // Verify the agent is now in the store
@@ -157,162 +227,204 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
                 permissionMode,
                 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 }))
-                    : [],
-            })) ?? [];
-            // 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,
-            });
-            // ─────────────────────────────────────────────────────────────────
-            // 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) {
+            try {
+                // ─────────────────────────────────────────────────────────────────
+                // Workspace Creation (before session, so cwd reflects worktree)
+                // ─────────────────────────────────────────────────────────────────
+                let workspace;
+                let resolvedStreamId = streamId;
+                if (workspaceManager && role) {
+                    try {
+                        workspace = await createWorkspaceForRole(workspaceManager, agentId, role, {
+                            streamId,
+                            streamConfig,
+                            dataplaneTaskId,
+                            capabilities,
+                            cwd,
+                        });
+                        if (workspace) {
+                            agentWorkspaces.set(agentId, workspace);
+                            resolvedStreamId = workspace.streamId;
+                            // Create and claim a dataplane task so the worktree gets a real
+                            // worker branch.  Without this, the worktree stays in detached
+                            // HEAD and done() would detect "HEAD" instead of the actual
+                            // worker branch name (e.g. worker/<agentId>/<taskId>).
+                            if (workspace.role === "worker" && workspace.streamId) {
+                                try {
+                                    const dpTaskId = workspaceManager.createTask(workspace.streamId, { title: task ?? `Task for ${agentId}` });
+                                    workspaceManager.claimTask(dpTaskId, agentId, workspace.path);
+                                }
+                                catch (claimErr) {
+                                    console.error(`[AgentManager] Failed to create/claim dataplane task for ${agentId}:`, claimErr);
+                                    // Continue without a branch — worktree stays in detached HEAD
+                                }
+                            }
+                            // Register with parent coordinator if applicable
+                            const isChildRole = role === "worker" || role === "integrator" ||
+                                (capabilities && (capabilities.includes("workspace.worktree") || capabilities.includes("workspace.integrate")));
+                            if (parent && isChildRole) {
+                                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
+                    }
+                }
+                // Use workspace path as the agent's working directory when available.
+                // This ensures the agent process, MCP subprocess (MACRO_AGENT_CWD), and
+                // done handler all use the worktree path instead of the repo root.
+                const effectiveCwd = workspace?.path ?? cwd;
+                // Update agent's cwd in EventStore so resume() also uses workspace path
+                if (workspace) {
+                    eventStore.updateAgentMetadata(agentId, { cwd: effectiveCwd });
+                    await eventStore.persist();
+                }
+                const macroAgentMcp = buildMacroAgentMcp({
+                    agentId,
+                    parentId: parent ?? "",
+                    taskId,
+                    cwd: effectiveCwd,
+                    permissionMode,
+                    lineage: parentAgent?.lineage
+                        ? [...parentAgent.lineage, parent]
+                        : [],
+                    sessionId,
+                    streamId,
+                });
+                // 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(effectiveCwd, {
+                    mcpServers: [macroAgentMcp, ...userMcpServers],
+                    ...(agentMeta && { agentMeta }),
+                });
+                // 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,
+                });
+                // ─────────────────────────────────────────────────────────────────
+                // 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,
                         });
+                        conversationMap.setAgentConversation(agentId, taskConvId);
+                    }
+                    catch (err) {
+                        // Never fail spawn due to mail errors
+                        console.warn(`[AgentManager] Failed to create task conversation for ${agentId}:`, err);
                     }
-                    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);
+                // Track active session
+                const activeSession = {
+                    agentId,
+                    handle,
+                    session,
+                    createdAt: Date.now(),
+                    isPrompting: false,
+                };
+                activeSessions.set(agentId, activeSession);
+                // Get the agent from materialized view
+                const agent = eventStore.getAgent(agentId);
+                // Notify lifecycle listeners
+                notifyLifecycle({ type: "spawned", agent });
+                notifyLifecycle({ type: "started", agent });
+                // 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,
+                };
             }
-            // Track active session
-            const activeSession = {
-                agentId,
-                handle,
-                session,
-                createdAt: Date.now(),
-                isPrompting: false,
-            };
-            activeSessions.set(agentId, activeSession);
-            // Get the agent from materialized view
-            const agent = eventStore.getAgent(agentId);
-            // ─────────────────────────────────────────────────────────────────
-            // Workspace Creation (Phase 2)
-            // ─────────────────────────────────────────────────────────────────
-            let workspace;
-            let resolvedStreamId = streamId;
-            if (workspaceManager && role) {
+            catch (handleError) {
+                // Close the spawned process to prevent orphaning
                 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);
-                            }
-                        }
-                    }
+                    await handle.close();
                 }
-                catch (wsError) {
-                    console.error(`[AgentManager] Failed to create workspace for ${agentId}: ${wsError}`);
-                    // Continue without workspace - don't fail the spawn
+                catch {
+                    // Ignore errors during cleanup
                 }
+                throw handleError;
             }
-            // Notify lifecycle listeners
-            notifyLifecycle({ type: "spawned", agent });
-            notifyLifecycle({ type: "started", agent });
-            // 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,
-            };
         }
         catch (error) {
             // Clean up the spawn event we already emitted
             eventStore.emit({
-                type: "terminate",
+                type: "stop",
                 source: { agent_id: agentId },
                 payload: {
                     reason: "failed",
@@ -355,6 +467,10 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
                 // Continue with termination even if workspace cleanup fails
             }
         }
+        // Revoke agent authentication token
+        if (agentTokenManager) {
+            agentTokenManager.revokeToken(agentId);
+        }
         // ─────────────────────────────────────────────────────────────────
         // Mail: Close task conversation on terminate
         // ─────────────────────────────────────────────────────────────────
@@ -383,9 +499,9 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
                 console.warn(`[AgentManager] Failed to close conversation for ${agentId}:`, err);
             }
         }
-        // Emit terminate event
+        // Emit stop event
         eventStore.emit({
-            type: "terminate",
+            type: "stop",
             source: { agent_id: agentId },
             payload: {
                 agent_id: agentId,
@@ -442,7 +558,10 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
             }
         }
     }
-    async function resume(agentId) {
+    async function resume(agentId, overridePermissionMode) {
+        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);
@@ -451,57 +570,217 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
         if (activeSessions.has(agentId)) {
             throw new AgentManagerError(`Agent already has active session: ${agentId}`, "ALREADY_RUNNING", agentId);
         }
+        const permissionMode = overridePermissionMode ?? defaultPermissionMode;
         // Spawn new process
         const handle = await AgentFactory.spawn(defaultAgentType, {
-            permissionMode: defaultPermissionMode,
+            permissionMode,
         });
-        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);
-            // Store the provider session ID for future resumes
+        try {
+            const agentCwd = agent.cwd ?? defaultCwd;
+            let session;
+            // 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, 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 = {
+                agentId,
+                handle,
+                session,
+                createdAt: Date.now(),
+                isPrompting: false,
+            };
+            activeSessions.set(agentId, activeSession);
+            // 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,
+            };
         }
-        // Track active session
-        const activeSession = {
-            agentId,
-            handle,
-            session,
-            createdAt: Date.now(),
-            isPrompting: false,
-        };
-        activeSessions.set(agentId, activeSession);
-        // Emit status event for resume
+        catch (handleError) {
+            // Close the spawned process to prevent orphaning
+            try {
+                await handle.close();
+            }
+            catch {
+                // Ignore errors during cleanup
+            }
+            throw handleError;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Fork
+    // ─────────────────────────────────────────────────────────────────
+    async function forkAgent(sourceAgentId, options) {
+        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);
+        }
+        // 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,
+                team_instance: sourceAgent.team_instance ?? 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, { name: generatedName });
+        await eventStore.persist();
+        // Get the provider session ID to fork from
+        let forkedProviderSessionId;
+        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,
+            ]);
+            // 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 = {
+                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;
+        }
     }
     // ─────────────────────────────────────────────────────────────────
     // Queries
@@ -654,11 +933,12 @@ export function createAgentManager(eventStore, messageRouter, config = {}) {
             const agentCompletedStatus = statusEvents.find((e) => e.source?.agent_id === agentId &&
                 (e.payload?.status_type === "completed" ||
                     e.payload?.status_type === "failed" ||
-                    e.payload?.details?.signal === "WORKER_DONE"));
+                    e.payload?.details?.signal ===
+                        "WORKER_DONE"));
             if (agentCompletedStatus) {
                 return {
                     called: true,
-                    status: agentCompletedStatus.payload?.status_type
+                    status: agentCompletedStatus.payload?.status_type,
                 };
             }
             return { called: false };
@@ -789,6 +1069,29 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
             return false;
         }
     }
+    function setPermissionMode(agentId, mode) {
+        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) {
+        const activeSession = activeSessions.get(agentId);
+        if (!activeSession) {
+            return null;
+        }
+        return activeSession.handle.getPermissionMode();
+    }
     // ─────────────────────────────────────────────────────────────────
     // Lifecycle Callbacks
     // ─────────────────────────────────────────────────────────────────
@@ -807,6 +1110,12 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
         }
     }
     // ─────────────────────────────────────────────────────────────────
+    // OpenTasks Socket Path (Late Binding)
+    // ─────────────────────────────────────────────────────────────────
+    function setOpenTasksSocketPath(socketPath) {
+        configOpenTasksSocketPath = socketPath;
+    }
+    // ─────────────────────────────────────────────────────────────────
     // Mail Services (Late Binding)
     // ─────────────────────────────────────────────────────────────────
     function setMailServices(ms, cm) {
@@ -817,6 +1126,8 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
     // Cleanup
     // ─────────────────────────────────────────────────────────────────
     async function close() {
+        // Prevent new spawns/resumes from racing with cleanup
+        isShuttingDown = true;
         // Stop all health checks
         if (healthCheckService) {
             healthCheckService.stopAll();
@@ -876,9 +1187,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
         }
         const resumeContext = contextLines.join("\n");
         // Spawn a continuation agent with same role, task, and context
-        const taskDescription = options?.task ??
-            agent.task ??
-            `Continue work from ${agentId}`;
+        const taskDescription = options?.task ?? agent.task ?? `Continue work from ${agentId}`;
         const newAgent = await spawn({
             task: taskDescription,
             role: agent.role,
@@ -903,6 +1212,7 @@ Call done() NOW with status "completed" if your work is finished, or "blocked" i
         terminate,
         resume,
         continueAgent,
+        forkAgent,
         get,
         list,
         getChildren,
@@ -918,27 +1228,70 @@ 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,
     };
 }
 /**
- * Create a workspace for an agent based on their role.
+ * Create a workspace for an agent based on their capabilities.
+ *
+ * Dispatches on workspace capabilities (workspace.stream, workspace.integrate,
+ * workspace.worktree) rather than role names. This allows team-defined roles
+ * (e.g., "developer" extending "worker") to get proper workspace allocation
+ * by inheriting workspace capabilities from their base role.
+ *
+ * Falls back to role-name matching for backward compatibility when no
+ * capabilities are provided.
  *
  * @param workspaceManager - WorkspaceManager instance
  * @param agentId - Agent ID
- * @param role - Agent role (e.g., 'worker', 'coordinator', 'integrator')
- * @param options - Additional options
+ * @param role - Agent role name (used for logging and fallback)
+ * @param options - Workspace options including capabilities
  * @returns Created workspace or undefined
  */
 async function createWorkspaceForRole(workspaceManager, agentId, role, options) {
-    const { streamId, streamConfig, dataplaneTaskId } = options;
+    const { streamId, streamConfig, dataplaneTaskId, capabilities } = options;
+    // Capability-based dispatch (preferred — works for team-defined roles)
+    if (capabilities && capabilities.length > 0) {
+        if (capabilities.includes("workspace.stream")) {
+            // Coordinator pattern: create integration stream.
+            // In team mode, stream is managed by TeamRuntime.setupWorkspaceIntegration(),
+            // so missing streamConfig is expected — return silently.
+            if (!streamConfig) {
+                return undefined;
+            }
+            const newStreamId = workspaceManager.createIntegrationStream(agentId, streamConfig);
+            return workspaceManager.createCoordinatorWorkspace(agentId, newStreamId);
+        }
+        else if (capabilities.includes("workspace.integrate")) {
+            // Integrator pattern: join existing stream
+            if (!streamId) {
+                console.warn(`[AgentManager] ${role} ${agentId} has workspace.integrate but no streamId, skipping workspace`);
+                return undefined;
+            }
+            return workspaceManager.createIntegratorWorkspace(agentId, streamId);
+        }
+        else if (capabilities.includes("workspace.worktree")) {
+            // Worker pattern: create worktree in stream
+            if (!streamId) {
+                console.warn(`[AgentManager] ${role} ${agentId} has workspace.worktree but no streamId, skipping workspace`);
+                return undefined;
+            }
+            const taskId = dataplaneTaskId ?? agentId;
+            return workspaceManager.createWorkerWorkspace(agentId, taskId, streamId);
+        }
+        // Has capabilities but no workspace capability — no workspace needed
+        return undefined;
+    }
+    // Fallback: role-name dispatch (backward compatibility for non-team spawns)
     switch (role) {
         case "coordinator": {
-            // Coordinators create a new integration stream
             if (!streamConfig) {
                 console.warn(`[AgentManager] Coordinator ${agentId} spawn missing streamConfig, skipping workspace`);
                 return undefined;
@@ -947,7 +1300,6 @@ async function createWorkspaceForRole(workspaceManager, agentId, role, options)
             return workspaceManager.createCoordinatorWorkspace(agentId, newStreamId);
         }
         case "integrator": {
-            // Integrators join an existing stream
             if (!streamId) {
                 console.warn(`[AgentManager] Integrator ${agentId} spawn missing streamId, skipping workspace`);
                 return undefined;
@@ -956,24 +1308,16 @@ async function createWorkspaceForRole(workspaceManager, agentId, role, options)
         }
         case "worker":
         case "worker.resolver": {
-            // Workers need streamId and either dataplaneTaskId or create a new task
             if (!streamId) {
                 console.warn(`[AgentManager] Worker ${agentId} spawn missing streamId, skipping workspace`);
                 return undefined;
             }
-            // Use provided task ID or skip (task should be created separately)
-            const taskId = dataplaneTaskId;
-            if (!taskId) {
-                console.warn(`[AgentManager] Worker ${agentId} spawn missing dataplaneTaskId, skipping workspace`);
-                return undefined;
-            }
+            const taskId = dataplaneTaskId ?? agentId;
             return workspaceManager.createWorkerWorkspace(agentId, taskId, streamId);
         }
         case "monitor":
-            // Monitors don't need workspaces
             return undefined;
         default:
-            // Unknown role - no workspace
             return undefined;
     }
 }