macro-agent 0.1.1 → 0.1.3

package/src/acp/macro-agent.ts

@@ -1,1887 +1,827 @@
 /**
- * MacroAgent - ACP-compliant agent implementation for macro-agent
+ * MacroAgent — ACP Agent implementation for macro-agent.
  *
- * Implements the Agent interface from @agentclientprotocol/sdk to allow
- * macro-agent to be spawned and controlled via the Agent Communication Protocol.
+ * Bridges the ACP protocol to macro-agent's V2 services:
+ * - session/new → agentManager.getOrCreateHeadManager()
+ * - session/prompt → agentManager.prompt() with streaming
+ * - Extension methods → spawn, mount, fork, hierarchy, tasks, etc.
+ *
+ * @module acp/macro-agent
  */
 
 import type {
-  Agent,
-  AgentSideConnection,
+  Agent as ACPAgent,
   InitializeRequest,
   InitializeResponse,
   NewSessionRequest,
   NewSessionResponse,
   LoadSessionRequest,
   LoadSessionResponse,
-  AuthenticateRequest,
-  AuthenticateResponse,
   PromptRequest,
   PromptResponse,
+  AuthenticateRequest,
+  AuthenticateResponse,
   CancelNotification,
   SessionNotification,
-  SessionModelState,
+  SessionUpdate,
 } from "@agentclientprotocol/sdk";
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import { RequestError } from "@agentclientprotocol/sdk";
+import type { ExtendedSessionUpdate, PermissionRequestUpdate } from "acp-factory";
 import type { AgentManager } from "../agent/agent-manager.js";
-import type { EventStore } from "../store/event-store.js";
-import type { TaskManager } from "../task/task-manager.js";
-import type { AgentId } from "../store/types/index.js";
+import type { InboxAdapter, TasksAdapter } from "../adapters/types.js";
+import type { MacroAgentSystemV2 } from "../boot-v2.js";
 import { SessionMapper } from "./session-mapper.js";
-import type {
-  ACPSessionId,
-  ACPExtensionMethod,
-  SpawnAgentRequest,
-  SpawnAgentResponse,
-  GetHierarchyRequest,
-  GetHierarchyResponse,
-  GetTaskRequest,
-  GetTaskResponse,
-  MountAgentRequest,
-  MountAgentResponse,
-  ForkAgentRequest,
-  ForkAgentResponse,
-  MacroAgentInitConfig,
-  SubAgentConfig,
-  SendPeerMessageACPRequest,
-  SendPeerMessageACPResponse,
-  SendPeerRequestACPRequest,
-  SendPeerRequestACPResponse,
-  DeliverPeerMessageRequest,
-  DeliverPeerMessageResponse,
-  DeliverPeerRequestRequest,
-  DeliverPeerRequestResponse,
-  GrantCapabilityRequest,
-  GrantCapabilityResponse,
-  RevokeCapabilityRequest,
-  RevokeCapabilityResponse,
-  GetCapabilitiesRequest,
-  GetCapabilitiesResponse,
-  CheckCapabilityRequest,
-  CheckCapabilityResponse,
-  RespondToPermissionRequest,
-  RespondToPermissionResponse,
-  CancelPermissionRequest,
-  CancelPermissionResponse,
-  SetPermissionModeRequest,
-  SetPermissionModeResponse,
-  ResumeAgentRequest,
-  ResumeAgentResponse,
-  GetHistoryRequest,
-  GetHistoryResponse,
-  HistoryTurn,
-} from "./types.js";
 import { ACPError } from "./types.js";
-import type { PeerManager } from "../peer/peer-manager.js";
-import type { CapabilityManager } from "../peer/capability-manager.js";
-import type { AgentConfig } from "../agent/types.js";
-import type { RoleRegistry, Capability } from "../roles/types.js";
-import { AGENT_CAPABILITIES } from "../roles/capabilities.js";
-import { DefaultRoleRegistry } from "../roles/registry.js";
+import type { MacroAgentInitConfig } from "./types.js";
+import type { TrajectoryCheckpointPayload } from "../map/types.js";
+import { execSync } from "node:child_process";
 
 // ─────────────────────────────────────────────────────────────────
-// Helpers
+// Configuration
 // ─────────────────────────────────────────────────────────────────
 
-/** Extract a plain-text output string from `rawOutput` (string | ContentBlock[] | undefined). */
-function extractToolOutput(rawOutput: unknown): string | undefined {
-  if (typeof rawOutput === "string") return rawOutput;
-  if (Array.isArray(rawOutput)) {
-    return rawOutput
-      .filter((item: any) => item.type === "text" && typeof item.text === "string")
-      .map((item: any) => item.text as string)
-      .join("\n") || undefined;
-  }
-  return undefined;
+export interface MacroAgentConfig {
+  system: MacroAgentSystemV2;
+  initConfig?: MacroAgentInitConfig;
 }
 
 // ─────────────────────────────────────────────────────────────────
-// Protocol Constants
+// Extension method names
 // ─────────────────────────────────────────────────────────────────
 
-const PROTOCOL_VERSION = 1;
-
-const SUPPORTED_EXTENSIONS: ACPExtensionMethod[] = [
+const SUPPORTED_EXTENSIONS = [
   "_macro/spawnAgent",
   "_macro/getHierarchy",
   "_macro/getTask",
   "_macro/mountAgent",
   "_macro/forkAgent",
-  "_macro/sendPeerMessage",
-  "_macro/sendPeerRequest",
-  "_macro/deliverPeerMessage",
-  "_macro/deliverPeerRequest",
-  "_macro/grantCapability",
-  "_macro/revokeCapability",
-  "_macro/getCapabilities",
-  "_macro/checkCapability",
-  "_macro/respondToPermission",
-  "_macro/cancelPermission",
-  "_macro/setPermissionMode",
   "_macro/resume",
   "_macro/getHistory",
   "_macro/getModels",
-];
+  "_macro/respondToPermission",
+  "_macro/cancelPermission",
+  "_macro/setPermissionMode",
+] as const;
+
+const STUBBED_PEER_EXTENSIONS = [
+  "_macro/listPeers",
+  "_macro/getPeer",
+  "_macro/sendToPeer",
+  "_macro/subscribePeer",
+  "_macro/unsubscribePeer",
+  "_macro/getCapabilities",
+  "_macro/setCapabilities",
+  "_macro/negotiateCapabilities",
+] as const;
+
+type SupportedExtension = (typeof SUPPORTED_EXTENSIONS)[number];
+type StubbedExtension = (typeof STUBBED_PEER_EXTENSIONS)[number];
 
 // ─────────────────────────────────────────────────────────────────
-// MacroAgent Configuration
+// Type Guards
 // ─────────────────────────────────────────────────────────────────
 
-export interface MacroAgentConfig {
-  /** AgentManager for spawning and managing agents */
-  agentManager: AgentManager;
-
-  /** EventStore for persistence */
-  eventStore: EventStore;
-
-  /** TaskManager for task operations */
-  taskManager: TaskManager;
+/** ACP-standard session update type discriminants. */
+const ACP_SESSION_UPDATE_TYPES = new Set([
+  "user_message_chunk",
+  "agent_message_chunk",
+  "agent_thought_chunk",
+  "tool_call",
+  "tool_call_update",
+  "plan",
+  "available_commands_update",
+  "current_mode_update",
+  "config_option_update",
+  "session_info_update",
+]);
 
-  /** PeerManager for inter-macro-agent communication (optional) */
-  peerManager?: PeerManager;
-
-  /** CapabilityManager for peer capability management (optional) */
-  capabilityManager?: CapabilityManager;
-
-  /** RoleRegistry for role-based capability checking (optional, uses default if not provided) */
-  roleRegistry?: RoleRegistry;
-
-  /** Default working directory for new sessions */
-  defaultCwd?: string;
+/**
+ * Type guard: returns true if the update is an ACP-standard SessionUpdate
+ * (not an acp-factory extension like PermissionRequestUpdate or CompactionUpdate).
+ */
+function isACPSessionUpdate(
+  update: ExtendedSessionUpdate,
+): update is SessionUpdate {
+  return (
+    "sessionUpdate" in update &&
+    ACP_SESSION_UPDATE_TYPES.has(
+      (update as { sessionUpdate: string }).sessionUpdate,
+    )
+  );
 }
 
-// ─────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────
-
 /**
- * Build a SessionModelState from the acp-factory Session.models (string[]).
- * Returns null if the models array is empty or missing.
+ * Type guard: returns true if the update is a PermissionRequestUpdate
+ * from acp-factory (emitted when the agent is in interactive permission mode).
  */
-function buildModelState(models: string[]): SessionModelState | null {
-  if (!models || models.length === 0) return null;
-  return {
-    currentModelId: models[0],
-    availableModels: models.map((id) => ({ modelId: id, name: id })),
-  };
+function isPermissionRequestUpdate(
+  update: ExtendedSessionUpdate,
+): update is PermissionRequestUpdate {
+  return (
+    "sessionUpdate" in update &&
+    (update as { sessionUpdate: string }).sessionUpdate === "permission_request"
+  );
 }
 
 // ─────────────────────────────────────────────────────────────────
-// MacroAgent Implementation
+// Factory
 // ─────────────────────────────────────────────────────────────────
 
 /**
- * MacroAgent implements the ACP Agent interface to expose macro-agent
- * as an ACP-compliant agent that can be spawned by external systems.
+ * Create a macro-agent ACP handler for an AgentSideConnection.
+ *
+ * Usage:
+ * ```ts
+ * new AgentSideConnection(
+ *   (conn) => createMacroAgent(conn, { system }),
+ *   stream,
+ * );
+ * ```
  */
-export class MacroAgent implements Agent {
-  private connection: AgentSideConnection;
-  private agentManager: AgentManager;
-  private eventStore: EventStore;
-  private taskManager: TaskManager;
-  private peerManager: PeerManager | undefined;
-  private capabilityManager: CapabilityManager | undefined;
-  private roleRegistry: RoleRegistry;
-  private sessionMapper: SessionMapper;
-  private defaultCwd: string;
-
-  /** Configuration from ACP initialization */
-  private initConfig: MacroAgentInitConfig = {};
-
-  /** Map of ACP session ID to cancellation abort controllers */
-  private cancellationControllers: Map<ACPSessionId, AbortController> =
-    new Map();
-
-  /** Accumulates assistant response parts during prompt streaming for history persistence */
-  private promptBuffers: Map<
-    ACPSessionId,
-    { parts: Array<{ type: "text"; text: string } | ({ type: "tool" } & Record<string, unknown>)> }
-  > = new Map();
-
-  /** Caches tool info (title, name, input) from initial tool_call events per session */
-  private toolInfoCaches: Map<
-    ACPSessionId,
-    Map<string, { title?: string; name?: string; input?: unknown }>
-  > = new Map();
-
-  constructor(connection: AgentSideConnection, config: MacroAgentConfig) {
-    this.connection = connection;
-    this.agentManager = config.agentManager;
-    this.eventStore = config.eventStore;
-    this.taskManager = config.taskManager;
-    this.peerManager = config.peerManager;
-    this.capabilityManager = config.capabilityManager;
-    this.roleRegistry = config.roleRegistry ?? new DefaultRoleRegistry();
-    this.sessionMapper = new SessionMapper(config.eventStore);
-    this.defaultCwd = config.defaultCwd ?? process.cwd();
-
-    // Recover persisted sessions from the EventStore
-    const recovered = this.sessionMapper.recoverFromStore();
-    if (recovered > 0) {
-      console.log(
-        `[MacroAgent] Recovered ${recovered} session(s) from EventStore`,
-      );
+export function createMacroAgent(
+  connection: AgentSideConnection,
+  config: MacroAgentConfig,
+): ACPAgent {
+  const { system, initConfig } = config;
+  const { agentManager, inboxAdapter, tasksAdapter } = system;
+  const sessionMapper = new SessionMapper();
+
+  const defaultCwd = initConfig?.defaultCwd ?? process.cwd();
+
+  // Per-session state for trajectory tracking
+  let checkpointCounter = 0;
+  let firstPrompt: string | null = null;
+  const sessionStartedAt = new Date().toISOString();
+
+  // Git info (cached — read once per session)
+  let gitInfo: { branch: string | null; commitHash: string | null; remoteUrl: string | null } | null = null;
+  function getGitInfo(cwd: string): { branch: string | null; commitHash: string | null; remoteUrl: string | null } {
+    if (gitInfo) return gitInfo;
+    try {
+      const branch = execSync("git rev-parse --abbrev-ref HEAD", { cwd, timeout: 3000 }).toString().trim() || null;
+      const commitHash = execSync("git rev-parse HEAD", { cwd, timeout: 3000 }).toString().trim() || null;
+      let remoteUrl: string | null = null;
+      try {
+        remoteUrl = execSync("git remote get-url origin", { cwd, timeout: 3000 }).toString().trim() || null;
+      } catch { /* no remote */ }
+      gitInfo = { branch, commitHash, remoteUrl };
+    } catch {
+      gitInfo = { branch: null, commitHash: null, remoteUrl: null };
     }
+    return gitInfo;
   }
 
-  // ─────────────────────────────────────────────────────────────────
-  // Core ACP Methods
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Initialize the connection and advertise capabilities
-   *
-   * Reads configuration from `params._meta?.macroConfig` if provided.
-   * This allows each macro-agent instance to have different settings.
-   */
-  async initialize(params: InitializeRequest): Promise<InitializeResponse> {
-    // Extract macro-agent config from _meta if provided
-    const meta = params._meta as Record<string, unknown> | undefined;
-    if (meta?.macroConfig) {
-      this.initConfig = meta.macroConfig as MacroAgentInitConfig;
-
-      // Apply defaultCwd from init config if provided
-      if (this.initConfig.defaultCwd) {
-        this.defaultCwd = this.initConfig.defaultCwd;
-      }
-    }
+  // ── Helpers ──────────────────────────────────────────────────
 
-    return {
-      protocolVersion: PROTOCOL_VERSION,
-      agentCapabilities: {
-        loadSession: true,
-        _meta: {
-          extensions: SUPPORTED_EXTENSIONS,
-          agentType: "macro-agent",
-          // Echo back the config so client knows what was applied
-          appliedConfig: this.initConfig,
-        },
-      },
-    };
+  function getSessionOrThrow(sessionId: string) {
+    const mapping = sessionMapper.getMapping(sessionId);
+    if (!mapping) {
+      throw RequestError.invalidParams(
+        { sessionId },
+        `Session not found: ${sessionId}`,
+      );
+    }
+    return mapping;
   }
 
-  /**
-   * Create a new session by spawning a head manager
-   */
-  async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
-    const cwd = params.cwd ?? this.defaultCwd;
-
-    // Build head manager options from init config
-    const defaultConfig = this.initConfig.defaultSubAgentConfig;
-    const permissionModeToUse = defaultConfig?.permissionMode;
-
-    // Spawn a new head manager for this session
-    const spawned = await this.agentManager.getOrCreateHeadManager({
-      cwd,
-      forceNew: true, // Always create new for newSession
-      permissionMode: permissionModeToUse,
-      systemPrompt: this.buildSystemPrompt(),
-    });
-
-    // Create session mapping
-    const acpSessionId = spawned.session_id;
-    this.sessionMapper.createMapping(acpSessionId, spawned.id);
-
-    // Create abort controller for cancellation
-    this.cancellationControllers.set(acpSessionId, new AbortController());
-
-    // Create a conversation in EventStore for history tracking
-    this.ensureConversation(acpSessionId, spawned.id);
-
-    // Emit session_info_update so client has title/timestamps
-    await this.emitSessionInfo(acpSessionId);
-
-    return {
-      sessionId: acpSessionId,
-      models: buildModelState(spawned.session.models),
-    };
-  }
+  // ── Extension dispatcher ────────────────────────────────────
 
-  /**
-   * Load an existing session from EventStore
-   */
-  async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
-    let acpSessionId = params.sessionId;
-    const cwd = params.cwd ?? this.defaultCwd;
-
-    // DEBUG: Log loadSession params
-    // Extension: If _meta.agentId provided, look up session from agent record
-    // This allows resuming a stopped head manager by MAP agent ID
-    // when the TUI doesn't know the ACP session ID
-    const metaAgentId = (params as { _meta?: Record<string, unknown> })._meta
-      ?.agentId as string | undefined;
-    if (metaAgentId) {
-      const agent = this.eventStore.getAgent(metaAgentId as AgentId);
-      if (!agent) {
-        throw new Error(`Agent not found: ${metaAgentId}`);
-      }
-      acpSessionId = agent.session_id;
-      console.log(
-        `[MacroAgent] loadSession: Resolved agentId ${metaAgentId} to session ${acpSessionId}`,
+  async function handleExtension(
+    method: string,
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    // Check if it's a stubbed peer method
+    if (
+      (STUBBED_PEER_EXTENSIONS as readonly string[]).includes(method)
+    ) {
+      throw new ACPError(
+        `Peer manager not available: ${method}`,
+        "NO_PEER_MANAGER",
+        { method },
       );
     }
 
-    // Try to find an existing head manager with this session ID
-    const headManagers = this.agentManager.listHeadManagers();
-    const existing = headManagers.find((hm) => hm.session_id === acpSessionId);
-
-    if (existing) {
-      // Check if the agent already has an active session
-      if (this.agentManager.hasActiveSession(existing.id)) {
-        console.log(
-          `[MacroAgent] loadSession: Agent ${existing.id} already has active session, reusing`,
-        );
-        // Reuse the existing active session - just update mappings
-        this.sessionMapper.createMapping(acpSessionId, existing.id);
-        if (!this.cancellationControllers.has(acpSessionId)) {
-          this.cancellationControllers.set(acpSessionId, new AbortController());
-        }
-        this.ensureConversation(acpSessionId, existing.id);
-        await this.emitSessionInfo(acpSessionId);
-        const activeSession = this.agentManager.getSession(existing.id);
+    switch (method as SupportedExtension) {
+      case "_macro/spawnAgent": {
+        const task = params.task as string;
+        if (!task) throw RequestError.invalidParams(params, "task is required");
+        const spawned = await agentManager.spawn({
+          task,
+          parent: params.parent as string | undefined,
+          cwd: (params.cwd as string) ?? defaultCwd,
+          role: params.role as string | undefined,
+          permissionMode: params.permissionMode as "auto-approve" | undefined,
+        });
         return {
-          models: activeSession ? buildModelState(activeSession.models) : null,
+          agentId: spawned.id,
+          sessionId: spawned.session_id,
+          role: spawned.agent.role,
+          state: spawned.agent.state,
         };
       }
 
-      // Agent exists but no active session - resume it
-      console.log(
-        `[MacroAgent] loadSession: Resuming stopped agent ${existing.id}`,
-      );
-      const defaultConfig = this.initConfig.defaultSubAgentConfig;
-      const spawned = await this.agentManager.resume(existing.id, defaultConfig?.permissionMode);
-
-      // Create session mapping
-      this.sessionMapper.createMapping(acpSessionId, spawned.id);
-      this.cancellationControllers.set(acpSessionId, new AbortController());
-      this.ensureConversation(acpSessionId, spawned.id);
-      await this.emitSessionInfo(acpSessionId);
-
-      return {
-        models: buildModelState(spawned.session.models),
-      };
-    }
-
-    // No existing agent found - try to get or create with the specific session ID
-    console.log(
-      `[MacroAgent] loadSession: No existing agent for session ${acpSessionId}, creating new`,
-    );
-    const defaultConfig = this.initConfig.defaultSubAgentConfig;
-    const spawned = await this.agentManager.getOrCreateHeadManager({
-      cwd,
-      sessionId: acpSessionId,
-      permissionMode: defaultConfig?.permissionMode,
-    });
-
-    // Create session mapping
-    this.sessionMapper.createMapping(acpSessionId, spawned.id);
-    this.cancellationControllers.set(acpSessionId, new AbortController());
-    this.ensureConversation(acpSessionId, spawned.id);
-    await this.emitSessionInfo(acpSessionId);
-
-    return {
-      models: buildModelState(spawned.session.models),
-    };
-  }
-
-  /**
-   * Authenticate - macro-agent doesn't require authentication
-   */
-  async authenticate(
-    _params: AuthenticateRequest,
-  ): Promise<AuthenticateResponse> {
-    // No authentication required
-    return {};
-  }
-
-  /**
-   * Process a prompt by routing to the mapped agent
-   */
-  async prompt(params: PromptRequest): Promise<PromptResponse> {
-    const acpSessionId = params.sessionId;
-
-    // Get the mapped agent
-    const agentId = this.sessionMapper.getAgentIdOrThrow(acpSessionId);
-
-    // Get or set up abort controller
-    let abortController = this.cancellationControllers.get(acpSessionId);
-    if (!abortController || abortController.signal.aborted) {
-      abortController = new AbortController();
-      this.cancellationControllers.set(acpSessionId, abortController);
-    }
-
-    // Extract message content from prompt blocks
-    const messageContent = this.extractMessageContent(params.prompt);
-
-    // Mark session as processing (for health monitoring)
-    this.sessionMapper.setProcessing(acpSessionId, true);
-
-    // Initialize prompt buffer and tool info cache for history accumulation
-    this.promptBuffers.set(acpSessionId, { parts: [] });
-    this.toolInfoCaches.set(acpSessionId, new Map());
-
-    try {
-      // Stream responses from the agent
-      for await (const update of this.agentManager.prompt(
-        agentId,
-        messageContent,
-      )) {
-        // Check for cancellation
-        if (abortController.signal.aborted) {
-          return {
-            stopReason: "cancelled",
-          };
-        }
-
-        // Forward session updates to the client
-        await this.forwardSessionUpdate(acpSessionId, update);
+      case "_macro/getHierarchy": {
+        const agentId = params.agentId as string;
+        if (!agentId) throw RequestError.invalidParams(params, "agentId is required");
+        const hierarchy = agentManager.getHierarchy(agentId, {
+          depth: params.depth as number | undefined,
+        });
+        return { hierarchy: hierarchy ?? null } as Record<string, unknown>;
       }
 
-      // Persist conversation turns for history
-      this.recordPromptTurns(acpSessionId, agentId, messageContent);
-
-      // Emit updated session info after prompt completes
-      await this.emitSessionInfo(acpSessionId);
-
-      return {
-        stopReason: "end_turn",
-      };
-    } catch (error) {
-      // Handle errors
-      const errorMessage =
-        error instanceof Error ? error.message : "Unknown error";
-
-      // Send error as session update
-      await this.connection.sessionUpdate({
-        sessionId: acpSessionId,
-        update: {
-          sessionUpdate: "agent_message_chunk",
-          content: { type: "text", text: `Error: ${errorMessage}` },
-        },
-      });
-
-      return {
-        stopReason: "end_turn",
-      };
-    } finally {
-      // Mark session as not processing (for health monitoring)
-      this.sessionMapper.setProcessing(acpSessionId, false);
-    }
-  }
-
-  /**
-   * Cancel ongoing operations for a session
-   */
-  async cancel(params: CancelNotification): Promise<void> {
-    const acpSessionId = params.sessionId;
-
-    // Signal cancellation
-    const controller = this.cancellationControllers.get(acpSessionId);
-    if (controller) {
-      controller.abort();
-    }
-
-    // Get the mapped agent ID for this session
-    const agentId = this.sessionMapper.getAgentId(acpSessionId);
-    if (!agentId) {
-      // No agent mapped - just clean up the controller
-      this.cancellationControllers.delete(acpSessionId);
-      return;
-    }
-
-    // Terminate the agent (which kills the subprocess)
-    try {
-      await this.agentManager.terminate(agentId, "cancelled");
-    } catch (error) {
-      // Agent may already be stopped - log but don't throw
-      console.warn(
-        `[MacroAgent] Error terminating agent ${agentId}:`,
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-
-    // Clean up resources
-    this.cancellationControllers.delete(acpSessionId);
-    this.sessionMapper.removeMapping(acpSessionId);
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Extension Methods
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Route extension method calls to handlers
-   */
-  async extMethod(
-    method: string,
-    params: Record<string, unknown>,
-  ): Promise<Record<string, unknown>> {
-    // Method may come with or without underscore prefix depending on caller
-    // SDK calls with full name (e.g., "_macro/spawnAgent"), direct calls may omit it
-    const fullMethod = (
-      method.startsWith("_") ? method : `_${method}`
-    ) as ACPExtensionMethod;
-
-    switch (fullMethod) {
-      case "_macro/spawnAgent":
-        return this.handleSpawnAgent(
-          params as unknown as SpawnAgentRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/getHierarchy":
-        return this.handleGetHierarchy(
-          params as unknown as GetHierarchyRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/getTask":
-        return this.handleGetTask(
-          params as unknown as GetTaskRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/mountAgent":
-        return this.handleMountAgent(
-          params as unknown as MountAgentRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/forkAgent":
-        return this.handleForkAgent(
-          params as unknown as ForkAgentRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/sendPeerMessage":
-        return this.handleSendPeerMessage(
-          params as unknown as SendPeerMessageACPRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/sendPeerRequest":
-        return this.handleSendPeerRequest(
-          params as unknown as SendPeerRequestACPRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/deliverPeerMessage":
-        return this.handleDeliverPeerMessage(
-          params as unknown as DeliverPeerMessageRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/deliverPeerRequest":
-        return this.handleDeliverPeerRequest(
-          params as unknown as DeliverPeerRequestRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/grantCapability":
-        return this.handleGrantCapability(
-          params as unknown as GrantCapabilityRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/revokeCapability":
-        return this.handleRevokeCapability(
-          params as unknown as RevokeCapabilityRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/getCapabilities":
-        return this.handleGetCapabilities(
-          params as unknown as GetCapabilitiesRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/checkCapability":
-        return this.handleCheckCapability(
-          params as unknown as CheckCapabilityRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/respondToPermission":
-        return this.handleRespondToPermission(
-          params as unknown as RespondToPermissionRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/cancelPermission":
-        return this.handleCancelPermission(
-          params as unknown as CancelPermissionRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/setPermissionMode":
-        return this.handleSetPermissionMode(
-          params as unknown as SetPermissionModeRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/resume":
-        return this.handleResumeAgent(
-          params as unknown as ResumeAgentRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/getHistory":
-        return this.handleGetHistory(
-          params as unknown as GetHistoryRequest,
-        ) as unknown as Record<string, unknown>;
-
-      case "_macro/getModels":
-        return this.handleGetModels(
-          params as { sessionId: string },
-        ) as unknown as Record<string, unknown>;
-
-      default:
-        throw new ACPError(
-          `Unknown extension method: ${method}`,
-          "INVALID_EXTENSION",
-        );
-    }
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Extension Handlers
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Spawn a new child agent
-   */
-  private async handleSpawnAgent(
-    params: SpawnAgentRequest,
-  ): Promise<SpawnAgentResponse> {
-    // Determine parent - use provided parentId or fall back to a session's mapped agent
-    let parentId = params.parentId;
-
-    // If no parentId provided, we need to find a suitable parent
-    // This would typically come from an ACP session context
-    if (!parentId) {
-      // Get the first head manager as default parent
-      const headManagers = this.agentManager.listHeadManagers();
-      if (headManagers.length > 0) {
-        parentId = headManagers[0].id;
+      case "_macro/getTask": {
+        const taskId = params.taskId as string;
+        if (!taskId) throw RequestError.invalidParams(params, "taskId is required");
+        const task = await tasksAdapter.getTask(taskId);
+        return { task } as Record<string, unknown>;
       }
-    }
 
-    // Check spawn capability if parent exists
-    if (parentId) {
-      const parentAgent = this.eventStore.getAgent(parentId);
-      if (parentAgent) {
-        const childRole = params.role ?? "worker";
-        const requiredCapability = this.getSpawnCapability(childRole);
+      case "_macro/mountAgent": {
+        const sessionId = params.sessionId as string;
+        const agentId = params.agentId as string;
+        if (!sessionId || !agentId) {
+          throw RequestError.invalidParams(
+            params,
+            "sessionId and agentId are required",
+          );
+        }
 
-        // Check if parent has the required spawn capability
-        const parentRole = parentAgent.role ?? "worker";
-        if (!this.roleRegistry.hasCapability(parentRole, requiredCapability)) {
+        // Verify the agent exists
+        const agent = agentManager.get(agentId);
+        if (!agent) {
           throw new ACPError(
-            `Parent agent with role '${parentRole}' does not have capability to spawn '${childRole}' agents. ` +
-              `Required capability: ${requiredCapability}`,
-            "CAPABILITY_DENIED",
-            {
-              parentId,
-              parentRole,
-              childRole,
-              requiredCapability,
-            },
+            `Agent not found: ${agentId}`,
+            "AGENT_NOT_FOUND",
+            { agentId },
           );
         }
-      }
-    }
 
-    // Merge default config with per-spawn override
-    const mergedConfig = this.mergeSubAgentConfig(
-      this.initConfig.defaultSubAgentConfig,
-      params.config,
-    );
-
-    // Spawn the agent with merged config
-    const spawned = await this.agentManager.spawn({
-      task: params.task_description,
-      parent: parentId ?? null,
-      role: params.role,
-      cwd: params.options?.cwd ?? this.defaultCwd,
-      subscribeParent: params.options?.subscribeParent ?? true,
-      topics: params.options?.topics,
-      permissionMode: mergedConfig?.permissionMode,
-      agentType: mergedConfig?.agentType,
-      config: this.toAgentConfig(mergedConfig),
-    });
-
-    return {
-      agentId: spawned.id,
-      taskId: spawned.agent.task_id!,
-      sessionId: spawned.session_id,
-    };
-  }
-
-  /**
-   * Map a child role name to the required spawn capability.
-   * Handles subroles like "worker.resolver" by checking base role.
-   */
-  private getSpawnCapability(childRole: string): Capability {
-    // Extract base role (e.g., "worker.resolver" -> "worker")
-    const baseRole = childRole.split(".")[0];
-
-    switch (baseRole) {
-      case "worker":
-        return AGENT_CAPABILITIES.SPAWN_WORKER;
-      case "integrator":
-        return AGENT_CAPABILITIES.SPAWN_INTEGRATOR;
-      case "monitor":
-        return AGENT_CAPABILITIES.SPAWN_MONITOR;
-      case "coordinator":
-        // Coordinators require special handling - typically only other coordinators
-        // or system-level agents can spawn coordinators
-        return AGENT_CAPABILITIES.SPAWN_CUSTOM;
-      default:
-        // For custom roles, check against the custom spawn capability
-        return AGENT_CAPABILITIES.SPAWN_CUSTOM;
-    }
-  }
-
-  /**
-   * Get the agent hierarchy tree
-   */
-  private async handleGetHierarchy(
-    params: GetHierarchyRequest,
-  ): Promise<GetHierarchyResponse> {
-    let rootAgentId = params.rootAgentId;
-
-    // If no root specified, use the first head manager
-    if (!rootAgentId) {
-      const headManagers = this.agentManager.listHeadManagers();
-      if (headManagers.length === 0) {
-        // Return empty hierarchy if no agents
+        const previousAgentId = sessionMapper.mount(sessionId, agentId);
         return {
-          hierarchy: {
-            agent: null as unknown as import("../store/types/index.js").Agent,
-            children: [],
-          },
-          totalAgents: 0,
-          depth: 0,
+          mounted: true,
+          agentId,
+          previousAgentId: previousAgentId ?? null,
         };
       }
-      rootAgentId = headManagers[0].id;
-    }
-
-    // Get hierarchy from agent manager
-    const hierarchy = this.agentManager.getHierarchy(rootAgentId);
-
-    if (!hierarchy) {
-      throw new ACPError(`Agent not found: ${rootAgentId}`, "AGENT_NOT_FOUND", {
-        agentId: rootAgentId,
-      });
-    }
-
-    return {
-      hierarchy: hierarchy.root,
-      totalAgents: hierarchy.totalAgents,
-      depth: hierarchy.depth,
-    };
-  }
-
-  /**
-   * Get task details by ID
-   */
-  private async handleGetTask(
-    params: GetTaskRequest,
-  ): Promise<GetTaskResponse> {
-    const task = this.taskManager.get(params.taskId);
-
-    if (!task) {
-      throw new ACPError(`Task not found: ${params.taskId}`, "TASK_NOT_FOUND", {
-        taskId: params.taskId,
-      });
-    }
-
-    return {
-      task,
-    };
-  }
-
-  /**
-   * Mount (attach to) an existing agent
-   *
-   * Remaps an ACP session to point to a different agent.
-   * Subsequent prompts will go to the mounted agent.
-   */
-  private async handleMountAgent(
-    params: MountAgentRequest,
-  ): Promise<MountAgentResponse> {
-    const { sessionId, agentId } = params;
-
-    // Verify the target agent exists
-    const agent = this.agentManager.get(agentId);
-    if (!agent) {
-      throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND", {
-        agentId,
-      });
-    }
-
-    // Verify the session exists in our mapper
-    const mapping = this.sessionMapper.getMapping(sessionId);
-    if (!mapping) {
-      throw new ACPError(
-        `Session not found: ${sessionId}`,
-        "SESSION_NOT_FOUND",
-        { sessionId },
-      );
-    }
-
-    // Get the previous agent before mounting
-    const previousAgentId = mapping.agentId;
-
-    // Remap the session to the target agent
-    this.sessionMapper.mount(sessionId, agentId);
-
-    return {
-      sessionId,
-      agent,
-      previousAgentId,
-    };
-  }
-
-  /**
-   * Fork an agent (create a branch with same conversation context)
-   *
-   * Creates a new agent that starts from the same point as the original.
-   * Uses native fork if available, otherwise falls back to loadSession.
-   */
-  private async handleForkAgent(
-    params: ForkAgentRequest,
-  ): Promise<ForkAgentResponse> {
-    const { agentId, name, prompt, cwd } = params;
-
-    // Validate source agent exists
-    const originalAgent = this.agentManager.get(agentId);
-    if (!originalAgent) {
-      throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND", {
-        agentId,
-      });
-    }
-
-    // Check forkable: needs active session or persisted provider_session_id
-    if (
-      !this.agentManager.hasActiveSession(agentId) &&
-      !originalAgent.provider_session_id
-    ) {
-      throw new ACPError(
-        `Agent has no session to fork: ${agentId}`,
-        "FORK_NOT_SUPPORTED",
-        { agentId },
-      );
-    }
-
-    // Fork via AgentManager (handles forkWithFlush + new process + loadSession)
-    const forked = await this.agentManager.forkAgent(agentId, {
-      name,
-      cwd: cwd ?? originalAgent.cwd ?? this.defaultCwd,
-    });
 
-    // Fire-and-forget initial prompt if provided
-    if (prompt) {
-      (async () => {
+      case "_macro/forkAgent": {
+        const sourceAgentId = params.sourceAgentId as string;
+        if (!sourceAgentId) {
+          throw RequestError.invalidParams(params, "sourceAgentId is required");
+        }
         try {
-          for await (const _update of this.agentManager.prompt(
-            forked.id,
-            prompt,
-          )) {
-            // Drain the async iterable
-          }
+          const forked = await agentManager.forkAgent(sourceAgentId, {
+            name: params.name as string | undefined,
+            prompt: params.prompt as string | undefined,
+            cwd: params.cwd as string | undefined,
+          });
+          return {
+            agentId: forked.id,
+            sessionId: forked.session_id,
+          };
         } catch (err) {
-          console.warn(
-            `[MacroAgent] Failed to send initial prompt to forked agent ${forked.id}:`,
-            err,
+          throw new ACPError(
+            `Fork failed: ${(err as Error).message}`,
+            "FORK_FAILED",
+            { sourceAgentId },
           );
         }
-      })();
-    }
-
-    return {
-      newAgentId: forked.id,
-      newSessionId: forked.session_id,
-      originalAgentId: agentId,
-      providerSessionId: forked.session.id,
-    };
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Peer Communication Extension Handlers
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Send a peer message (outbound, fire-and-forget)
-   *
-   * Called by external clients to have an agent send a message to a peer.
-   */
-  private async handleSendPeerMessage(
-    params: SendPeerMessageACPRequest,
-  ): Promise<SendPeerMessageACPResponse> {
-    if (!this.peerManager) {
-      throw new ACPError(
-        "PeerManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
-
-    // Determine which agent is sending (use head manager by default)
-    const headManagers = this.agentManager.listHeadManagers();
-    if (headManagers.length === 0) {
-      throw new ACPError(
-        "No agents available to send peer message",
-        "AGENT_NOT_FOUND",
-      );
-    }
-    const sendingAgentId = headManagers[0].id;
-
-    try {
-      await this.peerManager.sendMessage(sendingAgentId, params.to, {
-        type: params.type,
-        payload: params.payload,
-        metadata: params.correlationId
-          ? { correlationId: params.correlationId }
-          : undefined,
-      });
-
-      return {
-        success: true,
-        timestamp: Date.now(),
-      };
-    } catch (error) {
-      throw new ACPError(
-        `Failed to send peer message: ${error instanceof Error ? error.message : String(error)}`,
-        "PEER_SEND_FAILED",
-        { to: params.to, error },
-      );
-    }
-  }
-
-  /**
-   * Send a peer request (outbound, request-response)
-   *
-   * Called by external clients to have an agent send a request to a peer
-   * and wait for a response.
-   */
-  private async handleSendPeerRequest(
-    params: SendPeerRequestACPRequest,
-  ): Promise<SendPeerRequestACPResponse> {
-    if (!this.peerManager) {
-      throw new ACPError(
-        "PeerManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
-
-    // Determine which agent is sending (use head manager by default)
-    const headManagers = this.agentManager.listHeadManagers();
-    if (headManagers.length === 0) {
-      throw new ACPError(
-        "No agents available to send peer request",
-        "AGENT_NOT_FOUND",
-      );
-    }
-    const sendingAgentId = headManagers[0].id;
-
-    try {
-      const response = await this.peerManager.sendRequest(
-        sendingAgentId,
-        params.to,
-        {
-          method: params.method,
-          params: params.params,
-          timeout: params.timeout,
-        },
-      );
-
-      return response;
-    } catch (error) {
-      throw new ACPError(
-        `Failed to send peer request: ${error instanceof Error ? error.message : String(error)}`,
-        "PEER_SEND_FAILED",
-        { to: params.to, error },
-      );
-    }
-  }
-
-  /**
-   * Deliver a peer message (inbound, fire-and-forget)
-   *
-   * Called by external clients to route an inbound message from a peer
-   * to this macro-agent. The message is queued for the target agent.
-   */
-  private async handleDeliverPeerMessage(
-    params: DeliverPeerMessageRequest,
-  ): Promise<DeliverPeerMessageResponse> {
-    if (!this.peerManager) {
-      throw new ACPError(
-        "PeerManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
-
-    // Use PeerManager's deliverMessage to queue the message
-    const messageId = this.peerManager.deliverMessage(
-      params.from,
-      {
-        type: params.type,
-        payload: params.payload,
-        metadata: params.correlationId
-          ? { correlationId: params.correlationId }
-          : undefined,
-      },
-      params.targetAgentId,
-    );
-
-    return {
-      success: true,
-      messageId,
-    };
-  }
-
-  /**
-   * Deliver a peer request (inbound, request-response)
-   *
-   * Called by external clients to route an inbound request from a peer
-   * to this macro-agent. The request is queued and this waits for the
-   * internal agent to respond.
-   */
-  private async handleDeliverPeerRequest(
-    params: DeliverPeerRequestRequest,
-  ): Promise<DeliverPeerRequestResponse> {
-    if (!this.peerManager) {
-      throw new ACPError(
-        "PeerManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
+      }
 
-    // Use PeerManager's deliverRequest which returns a promise
-    // that resolves when the internal agent responds
-    const response = await this.peerManager.deliverRequest(
-      params.from,
-      {
-        method: params.method,
-        params: params.params,
-        timeout: params.timeout,
-      },
-      params.targetAgentId,
-    );
-
-    return response;
-  }
+      case "_macro/resume": {
+        const agentId = params.agentId as string;
+        if (!agentId) throw RequestError.invalidParams(params, "agentId is required");
+        const resumed = await agentManager.resume(agentId);
+        return {
+          agentId: resumed.id,
+          sessionId: resumed.session_id,
+          state: resumed.agent.state,
+        };
+      }
 
-  // ─────────────────────────────────────────────────────────────────
-  // Capability Extension Handlers
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Grant capabilities to a peer
-   */
-  private async handleGrantCapability(
-    params: GrantCapabilityRequest,
-  ): Promise<GrantCapabilityResponse> {
-    if (!this.capabilityManager) {
-      throw new ACPError(
-        "CapabilityManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
+      case "_macro/getHistory": {
+        const agentId = params.agentId as string;
+        if (!agentId) throw RequestError.invalidParams(params, "agentId is required");
 
-    const capabilities = this.capabilityManager.grant(
-      params.peerId,
-      params.grants,
-      {
-        expiresIn: params.expiresIn,
-        issuedBy: params.issuedBy,
-      },
-    );
+        if (params.threadTag) {
+          const thread = await inboxAdapter.readThread(
+            params.threadTag as string,
+            params.scope as string | undefined,
+          );
+          return { messages: thread };
+        }
 
-    return { capabilities };
-  }
+        const messages = await inboxAdapter.checkInbox(agentId, {
+          limit: params.limit as number | undefined,
+        });
+        return { messages };
+      }
 
-  /**
-   * Revoke capabilities from a peer
-   */
-  private async handleRevokeCapability(
-    params: RevokeCapabilityRequest,
-  ): Promise<RevokeCapabilityResponse> {
-    if (!this.capabilityManager) {
-      throw new ACPError(
-        "CapabilityManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
+      case "_macro/getModels": {
+        // Models are not centrally tracked; return empty
+        return { models: [] };
+      }
 
-    this.capabilityManager.revoke(params.peerId, params.grantTypes);
+      case "_macro/respondToPermission": {
+        const agentId = params.agentId as string;
+        const requestId = params.requestId as string;
+        const optionId = params.optionId as string;
+        if (!agentId || !requestId || !optionId) {
+          throw RequestError.invalidParams(
+            params,
+            "agentId, requestId, and optionId are required",
+          );
+        }
+        const success = agentManager.respondToPermission(
+          agentId,
+          requestId,
+          optionId,
+        );
+        return { success };
+      }
 
-    return {
-      success: true,
-      remainingCapabilities: this.capabilityManager.getCapabilities(
-        params.peerId,
-      ),
-    };
-  }
+      case "_macro/cancelPermission": {
+        const agentId = params.agentId as string;
+        const requestId = params.requestId as string;
+        if (!agentId || !requestId) {
+          throw RequestError.invalidParams(
+            params,
+            "agentId and requestId are required",
+          );
+        }
+        const success = agentManager.cancelPermission(agentId, requestId);
+        return { success };
+      }
 
-  /**
-   * Get capabilities for a peer or list all authorized peers
-   */
-  private async handleGetCapabilities(
-    params: GetCapabilitiesRequest,
-  ): Promise<GetCapabilitiesResponse> {
-    if (!this.capabilityManager) {
-      throw new ACPError(
-        "CapabilityManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
+      case "_macro/setPermissionMode": {
+        const agentId = params.agentId as string;
+        const mode = params.mode as string;
+        if (!agentId || !mode) {
+          throw RequestError.invalidParams(
+            params,
+            "agentId and mode are required",
+          );
+        }
+        const success = agentManager.setPermissionMode(
+          agentId,
+          mode as "auto-approve",
+        );
+        return { success };
+      }
 
-    if (params.peerId) {
-      return {
-        capabilities: this.capabilityManager.getCapabilities(params.peerId),
-      };
+      default:
+        throw new ACPError(
+          `Unknown extension: ${method}`,
+          "INVALID_EXTENSION",
+          { method },
+        );
     }
-
-    return {
-      authorizedPeers: this.capabilityManager.listAuthorizedPeers(),
-    };
   }
 
-  /**
-   * Check if a peer has a required capability
-   */
-  private async handleCheckCapability(
-    params: CheckCapabilityRequest,
-  ): Promise<CheckCapabilityResponse> {
-    if (!this.capabilityManager) {
-      throw new ACPError(
-        "CapabilityManager not configured for this macro-agent",
-        "NO_PEER_MANAGER",
-      );
-    }
-
-    return {
-      hasCapability: this.capabilityManager.hasCapability(
-        params.peerId,
-        params.required,
-      ),
-    };
-  }
+  // ── ACP Agent Implementation ────────────────────────────────
 
-  // ─────────────────────────────────────────────────────────────────
-  // Permission Extension Handlers
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Respond to a permission request for a session
-   *
-   * Routes the response through the session mapper to find the agent,
-   * then calls the agent manager to resolve the pending permission.
-   */
-  private async handleRespondToPermission(
-    params: RespondToPermissionRequest,
-  ): Promise<RespondToPermissionResponse> {
-    const { sessionId, requestId, optionId } = params;
-
-    // Get the agent ID from session mapper
-    const agentId = this.sessionMapper.getAgentId(sessionId);
-    if (!agentId) {
+  const agent: ACPAgent = {
+    async initialize(
+      _params: InitializeRequest,
+    ): Promise<InitializeResponse> {
       return {
-        success: false,
-        error: `No agent found for session: ${sessionId}`,
-      };
-    }
-
-    // Respond via agent manager
-    const success = this.agentManager.respondToPermission(
-      agentId,
-      requestId,
-      optionId,
-    );
+        protocolVersion: 1,
+        agentInfo: {
+          name: "macro-agent",
+          version: "2.0.0",
+        },
+        agentCapabilities: {
+          loadSession: true,
+          sessionCapabilities: {
+            resume: {},
+          },
+        },
+        extensions: [
+          ...SUPPORTED_EXTENSIONS.map((name) => ({
+            name,
+            description: `macro-agent extension: ${name}`,
+          })),
+          ...STUBBED_PEER_EXTENSIONS.map((name) => ({
+            name,
+            description: `Peer extension (stub): ${name}`,
+          })),
+        ],
+      } as InitializeResponse;
+    },
+
+    async newSession(
+      params: NewSessionRequest,
+    ): Promise<NewSessionResponse> {
+      const cwd = params.cwd ?? defaultCwd;
+
+      // Get or create a head manager for this workspace
+      const headManager = await agentManager.getOrCreateHeadManager({
+        cwd,
+      });
 
-    if (success) {
-      console.log(
-        `[MacroAgent] Responded to permission ${requestId} for session ${sessionId} with ${optionId}`,
+      // Create session mapping
+      const mapping = sessionMapper.createMapping(
+        headManager.session_id,
+        headManager.id,
       );
-      return { success: true };
-    } else {
-      return {
-        success: false,
-        error: `Failed to respond to permission ${requestId} for agent ${agentId}`,
-      };
-    }
-  }
-
-  /**
-   * Cancel a permission request for a session
-   *
-   * Routes the cancellation through the session mapper to find the agent,
-   * then calls the agent manager to cancel the pending permission.
-   */
-  private async handleCancelPermission(
-    params: CancelPermissionRequest,
-  ): Promise<CancelPermissionResponse> {
-    const { sessionId, requestId } = params;
-
-    // Get the agent ID from session mapper
-    const agentId = this.sessionMapper.getAgentId(sessionId);
-    if (!agentId) {
-      return {
-        success: false,
-        error: `No agent found for session: ${sessionId}`,
-      };
-    }
 
-    // Cancel via agent manager
-    const success = this.agentManager.cancelPermission(agentId, requestId);
-
-    if (success) {
-      console.log(
-        `[MacroAgent] Cancelled permission ${requestId} for session ${sessionId}`,
-      );
-      return { success: true };
-    } else {
-      return {
-        success: false,
-        error: `Failed to cancel permission ${requestId} for agent ${agentId}`,
-      };
-    }
-  }
+      // Annotate sessionlog with swarm metadata (best effort)
+      try {
+        const { annotateSession } = await import("../integrations/sessionlog.js");
+        annotateSession(cwd, {
+          swarmId: headManager.id,
+          scope: "macro-agent",
+        });
+      } catch {
+        // sessionlog not available — non-fatal
+      }
 
-  /**
-   * Change the permission mode for a running agent at runtime
-   */
-  private async handleSetPermissionMode(
-    params: SetPermissionModeRequest,
-  ): Promise<SetPermissionModeResponse> {
-    const { agentId, permissionMode } = params;
-
-    // Get the current mode before changing
-    const previousMode = this.agentManager.getPermissionMode(
-      agentId as AgentId,
-    );
-
-    // Set the new mode via agent manager
-    const success = this.agentManager.setPermissionMode(
-      agentId as AgentId,
-      permissionMode,
-    );
-
-    if (success) {
-      console.log(
-        `[MacroAgent] Set permission mode for agent ${agentId} from ${previousMode} to ${permissionMode}`,
-      );
-      return {
-        success: true,
-        previousMode: previousMode ?? undefined,
-      };
-    } else {
       return {
-        success: false,
-        error: `No active session found for agent ${agentId}`,
+        sessionId: mapping.acpSessionId,
       };
-    }
-  }
+    },
 
-  /**
-   * Resume a stopped/failed agent
-   */
-  private async handleResumeAgent(
-    params: ResumeAgentRequest,
-  ): Promise<ResumeAgentResponse> {
-    const { agentId } = params;
+    async loadSession(
+      params: LoadSessionRequest,
+    ): Promise<LoadSessionResponse> {
+      const sessionId = params.sessionId;
 
-    if (!agentId) {
-      throw new ACPError("agentId is required", "INVALID_EXTENSION");
-    }
-
-    // Verify agent exists
-    const agent = this.eventStore.getAgent(agentId);
-    if (!agent) {
-      throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND");
-    }
-
-    // Only resume stopped/failed agents
-    if (agent.state !== "stopped" && agent.state !== "failed") {
-      throw new ACPError(
-        `Agent ${agentId} is ${agent.state} — only stopped or failed agents can be resumed`,
-        "INVALID_EXTENSION",
-      );
-    }
-
-    console.log(`[MacroAgent] Resuming agent ${agentId}`);
-    const spawned = await this.agentManager.resume(agentId);
-
-    return {
-      success: true,
-      agentId: spawned.id,
-      sessionId: spawned.session_id,
-    };
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Helper Methods
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Extract text content from prompt content blocks
-   */
-  private extractMessageContent(prompt: PromptRequest["prompt"]): string {
-    // Handle content blocks array
-    if (Array.isArray(prompt)) {
-      return prompt
-        .map((block) => {
-          if ("text" in block) {
-            return block.text;
-          }
-          return "";
-        })
-        .filter(Boolean)
-        .join("\n");
-    }
+      // Check if we already have a mapping for this session
+      let mapping = sessionMapper.getMapping(sessionId);
+      if (mapping) {
+        return {};
+      }
 
-    return "";
-  }
+      // Try to resume the agent associated with this session
+      // The session ID might be an agent ID in our system
+      const agent = agentManager.get(sessionId);
+      if (agent) {
+        const resumed = await agentManager.resume(sessionId);
+        mapping = sessionMapper.createMapping(
+          resumed.session_id,
+          resumed.id,
+        );
+        return {};
+      }
 
-  /**
-   * Forward session updates from child agents to the ACP client
-   *
-   * acp-factory already sends updates in ACP SDK format, so we forward
-   * all updates directly. This handles all update types including:
-   * - agent_message_chunk: Text content from agent
-   * - agent_thought_chunk: Agent thinking/reasoning (if enabled)
-   * - user_message_chunk: Echo of user messages
-   * - tool_call: Tool invocation start
-   * - tool_call_update: Tool execution progress/completion
-   * - plan: Plan updates
-   * - available_commands_update: Available slash commands
-   * - current_mode_update: Mode changes (code/plan/etc)
-   * - config_option_update: Configuration changes
-   * - session_info_update: Session title and timestamps
-   *
-   * Permission requests are handled separately via the requestPermission RPC.
-   */
-  private async forwardSessionUpdate(
-    acpSessionId: ACPSessionId,
-    update: unknown,
-  ): Promise<void> {
-    const sessionUpdate = update as Record<string, unknown>;
-
-    // Check if this is a valid session update with the sessionUpdate discriminator
-    if (!("sessionUpdate" in sessionUpdate)) {
-      console.warn(
-        `[MacroAgent] Received update without sessionUpdate field:`,
-        JSON.stringify(update).substring(0, 200),
+      throw RequestError.invalidParams(
+        { sessionId },
+        `Session not found: ${sessionId}`,
       );
-      return;
-    }
-
-    const updateType = sessionUpdate.sessionUpdate as string;
-
-    // Log update details based on type (verbose logging for debugging)
-    switch (updateType) {
-      case "agent_message_chunk":
-      case "agent_thought_chunk":
-      case "user_message_chunk": {
-        const content = sessionUpdate.content as
-          | { type?: string; text?: string }
-          | undefined;
-        const text = content?.text ?? "";
-        if (text) {
-          console.log(
-            `[MacroAgent] Forwarding ${updateType} (${text.length} chars): "${text.substring(0, 80)}${text.length > 80 ? "..." : ""}"`,
-          );
+    },
+
+    async authenticate(
+      _params: AuthenticateRequest,
+    ): Promise<AuthenticateResponse> {
+      // No-op: macro-agent does not require authentication
+      return {};
+    },
+
+    async prompt(params: PromptRequest): Promise<PromptResponse> {
+      const mapping = getSessionOrThrow(params.sessionId);
+      const agentId = mapping.agentId;
+
+      // Extract text content from prompt blocks
+      const textParts: string[] = [];
+      for (const block of params.prompt) {
+        if ("text" in block && typeof block.text === "string") {
+          textParts.push(block.text);
         }
-        break;
       }
+      const message = textParts.join("\n") || "";
 
-      case "tool_call": {
-        const toolCallId = sessionUpdate.toolCallId as string;
-        const title = sessionUpdate.title as string;
-        const status = sessionUpdate.status as string;
-        console.log(
-          `[MacroAgent] Forwarding tool_call: id=${toolCallId}, title="${title}", status=${status}`,
-        );
-        break;
-      }
+      sessionMapper.setProcessing(params.sessionId, true);
 
-      case "tool_call_update": {
-        const toolCallId = sessionUpdate.toolCallId as string;
-        const status = sessionUpdate.status as string;
-        console.log(
-          `[MacroAgent] Forwarding tool_call_update: id=${toolCallId}, status=${status}`,
-        );
-        break;
+      // Capture first prompt for trajectory metadata (used as session description in OpenHive UI)
+      if (!firstPrompt) {
+        firstPrompt = message.slice(0, 200);
       }
 
-      case "permission_request": {
-        // Handle permission_request specially - ACP SDK doesn't recognize it as a session update
-        // We need to call requestPermission on the connection to forward to the client
-
-        // Extract permission request data
-        const permReq = sessionUpdate as {
-          requestId: string;
-          sessionId: string;
-          toolCall: {
-            toolCallId: string;
-            title: string;
-            status?: string;
-            rawInput?: unknown;
-          };
-          options: Array<{
-            kind: string;
-            name: string;
-            optionId: string;
-          }>;
-        };
-
-        // Look up agent ID using the ACP session ID (from the client connection),
-        // NOT permReq.sessionId which is the agent's internal session ID.
-        // The session mapper maps ACP session IDs → agent IDs, so using the
-        // internal session ID would fail silently and drop the permission request.
-        const agentId = this.sessionMapper.getAgentId(acpSessionId);
-        if (!agentId) {
-          console.warn(
-            `[MacroAgent] No agent found for ACP session ${acpSessionId}, cannot forward permission request`,
+      // Track data for trajectory checkpoint
+      const filesTouched = new Set<string>();
+      let toolCallCount = 0;
+      const promptStartTime = Date.now();
+      let tokenUsage = { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 };
+
+      // Update agent state to "busy" — both local MAP server and upstream sidecar
+      try {
+        const mapServer = (system as any).mapServerInstance;
+        if (mapServer) {
+          const agents = mapServer.agents?.list?.() ?? [];
+          const mapAgent = agents.find(
+            (a: any) => a.metadata?.localAgentId === agentId,
           );
-          return;
+          if (mapAgent) {
+            mapServer.agents.updateState(mapAgent.id, "busy");
+          }
         }
+      } catch { /* best effort */ }
+
+      // Update upstream sidecar state (so OpenHive sees activity)
+      try {
+        const sidecarConn = (system as any).mapSidecar;
+        if (sidecarConn?.connected) {
+          // The sidecar's underlying AgentConnection has updateState
+          // but it's not directly exposed. Emit via the eventBus instead.
+        }
+      } catch { /* best effort */ }
+
+      try {
+        // Stream updates from agentManager.prompt()
+        const updates = agentManager.prompt(agentId, message);
+
+        for await (const update of updates) {
+          // Track tool calls, files, and token usage for trajectory checkpoint.
+          // Also emit task bridge events for TaskCreate/TaskUpdate tool calls.
+          if ("sessionUpdate" in update) {
+            const su = update as any;
+            if (su.sessionUpdate === "tool_call") {
+              toolCallCount++;
+              const input = su.rawInput as Record<string, unknown> | undefined;
+              if (input?.file_path) filesTouched.add(input.file_path as string);
+              if (input?.filePath) filesTouched.add(input.filePath as string);
+              if (input?.path) filesTouched.add(input.path as string);
+              if (input?.command) filesTouched.add(`[bash] ${(input.command as string).slice(0, 50)}`);
+            }
 
-        // Forward via requestPermission RPC
-        // This will trigger the client's handler which will show the prompt
-        try {
-          const response = await this.connection.requestPermission({
-            sessionId: acpSessionId,
-            toolCall: {
-              toolCallId: permReq.toolCall.toolCallId,
-              title: permReq.toolCall.title,
-              status: permReq.toolCall.status as
-                | "pending"
-                | "in_progress"
-                | "completed"
-                | "failed"
-                | undefined,
-              rawInput: permReq.toolCall.rawInput,
-            },
-            options: permReq.options as Array<{
-              kind:
-                | "allow_once"
-                | "allow_always"
-                | "reject_once"
-                | "reject_always";
-              name: string;
-              optionId: string;
-            }>,
-          });
+            // Track token usage from session info updates
+            if (su.sessionUpdate === "session_info_update" && su.usage) {
+              const u = su.usage;
+              if (u.inputTokens) tokenUsage.input_tokens += u.inputTokens;
+              if (u.outputTokens) tokenUsage.output_tokens += u.outputTokens;
+              if (u.cacheReadTokens) tokenUsage.cache_read_tokens += u.cacheReadTokens;
+              if (u.cacheCreationTokens) tokenUsage.cache_creation_tokens += u.cacheCreationTokens;
+            }
 
-          // Forward the response back to the sub-agent via agentManager
-          if (response.outcome) {
-            if (
-              response.outcome.outcome === "selected" &&
-              response.outcome.optionId
-            ) {
-              const success = this.agentManager.respondToPermission(
-                agentId,
-                permReq.requestId,
-                response.outcome.optionId,
-              );
-              if (!success) {
-                console.warn(
-                  `[MacroAgent] Failed to forward permission response to agent ${agentId}`,
-                );
+            // Bridge tool call completions to MAP events
+            if (su.sessionUpdate === "tool_call_update" && su.output !== undefined) {
+              const toolName = su.title ?? "";
+              const sidecar = (system as any).mapSidecar;
+              if (sidecar?.connected && toolName) {
+                try {
+                  // Native task lifecycle events
+                  if (toolName === "TaskCreate" || toolName.includes("TaskCreate")) {
+                    const taskData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `task-created-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.created", task: taskData },
+                    }).catch(() => {});
+                  } else if (toolName === "TaskUpdate" || toolName.includes("TaskUpdate")) {
+                    const taskData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `task-updated-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.status", task: taskData },
+                    }).catch(() => {});
+                  }
+
+                  // Gap 3: Opentasks MCP bridge — bridge opentasks tool calls to MAP events
+                  else if (toolName === "opentasks__create_task" || toolName.includes("create_task")) {
+                    const taskData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `opentasks-created-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.created", source: "opentasks", task: taskData },
+                    }).catch(() => {});
+                  } else if (toolName === "opentasks__update_task" || toolName.includes("update_task")) {
+                    const taskData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `opentasks-status-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.status", source: "opentasks", task: taskData },
+                    }).catch(() => {});
+                  } else if (toolName === "opentasks__link" || toolName.includes("opentasks") && toolName.includes("link")) {
+                    const linkData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `opentasks-linked-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.linked", source: "opentasks", link: linkData },
+                    }).catch(() => {});
+                  } else if (toolName === "opentasks__annotate" || toolName.includes("opentasks") && toolName.includes("annotate")) {
+                    const annotateData = typeof su.output === "string"
+                      ? JSON.parse(su.output) : su.output;
+                    sidecar.reportCheckpoint?.({
+                      id: `opentasks-sync-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "task.sync", source: "opentasks", annotation: annotateData },
+                    }).catch(() => {});
+                  }
+
+                  // Gap 2: Memory sync — detect minimem write tools
+                  else if (toolName.includes("memory_append") || toolName.includes("memory_upsert")) {
+                    sidecar.reportCheckpoint?.({
+                      id: `memory-sync-${Date.now()}`,
+                      session_id: params.sessionId,
+                      agent: agentId,
+                      branch: null,
+                      files_touched: [],
+                      checkpoints_count: checkpointCounter,
+                      metadata: { phase: "active", event: "memory.sync" },
+                    }).catch(() => {});
+                  }
+                } catch { /* ignore parse errors */ }
               }
-            } else if (response.outcome.outcome === "cancelled") {
-              const success = this.agentManager.cancelPermission(
-                agentId,
-                permReq.requestId,
-              );
-              if (!success) {
-                console.warn(
-                  `[MacroAgent] Failed to cancel permission for agent ${agentId}`,
-                );
+            }
+          }
+
+          // Handle permission requests from the underlying agent.
+          // When the agent is in interactive mode, it yields
+          // PermissionRequestUpdate objects instead of auto-approving.
+          // We forward these to the client via AgentSideConnection's
+          // requestPermission() method (JSON-RPC agent→client request).
+          if (isPermissionRequestUpdate(update)) {
+            try {
+              const permResponse = await connection.requestPermission({
+                sessionId: params.sessionId,
+                toolCall: {
+                  toolCallId: update.toolCall.toolCallId,
+                  title: update.toolCall.title,
+                  status: update.toolCall.status as any,
+                  rawInput: update.toolCall.rawInput,
+                },
+                options: update.options,
+              });
+              // Relay the permission response back to the agent.
+              // ACP response: { outcome: { outcome: "selected", optionId } | { outcome: "cancelled" } }
+              const outcome = permResponse?.outcome;
+              if (outcome) {
+                if (outcome.outcome === "selected" && "optionId" in outcome) {
+                  agentManager.respondToPermission(
+                    agentId,
+                    update.requestId,
+                    outcome.optionId,
+                  );
+                } else if (outcome.outcome === "cancelled") {
+                  agentManager.cancelPermission(agentId, update.requestId);
+                }
+              }
+            } catch {
+              // If the permission request fails (e.g., client disconnected),
+              // cancel it so the agent doesn't hang.
+              try {
+                agentManager.cancelPermission(agentId, update.requestId);
+              } catch {
+                // Best effort
               }
             }
+            continue;
           }
-        } catch (err) {
-          console.error(
-            `[MacroAgent] Failed to forward permission_request:`,
-            err instanceof Error ? err.message : err,
-          );
-          // Cancel the permission request on error
-          try {
-            this.agentManager.cancelPermission(agentId, permReq.requestId);
-          } catch {
-            // Ignore cancel errors
+
+          // Forward each update to the client as a session notification.
+          // Only forward ACP-compatible SessionUpdate types; skip
+          // acp-factory extended types like CompactionUpdate.
+          if ("sessionUpdate" in update && isACPSessionUpdate(update)) {
+            const notification: SessionNotification = {
+              sessionId: params.sessionId,
+              update,
+            };
+            await connection.sessionUpdate(notification);
           }
         }
-        // Don't forward via sessionUpdate - we handled it via requestPermission
-        return;
-      }
-
-      default:
-        // Log other update types at debug level
-        console.log(`[MacroAgent] Forwarding ${updateType}`);
-    }
 
-    // Accumulate content for history persistence (preserving text/tool interleaving order)
-    const buffer = this.promptBuffers.get(acpSessionId);
-    if (buffer) {
-      if (updateType === "agent_message_chunk") {
-        const content = sessionUpdate.content as
-          | { type?: string; text?: string }
-          | undefined;
-        if (content?.text) {
-          const last = buffer.parts[buffer.parts.length - 1];
-          if (last && last.type === "text") {
-            last.text += content.text;
-          } else {
-            buffer.parts.push({ type: "text", text: content.text });
+        // Emit enriched trajectory checkpoint after prompt completes.
+        // Matches cc-swarm's wire format so OpenHive UI can display session data.
+        const sidecar = (system as any).mapSidecar;
+        if (sidecar) {
+          checkpointCounter++;
+          const agentRecord = (system as any).agentStore?.getAgent?.(agentId);
+          const agentCwd = agentRecord?.cwd ?? defaultCwd;
+          const git = getGitInfo(agentCwd);
+
+          // Determine sync level from sessionlog config (default: "full")
+          const syncLevel: string = (system as any)._sessionlogSyncLevel ?? "full";
+
+          // Build checkpoint with sync-level gating:
+          // - lifecycle: phase, turnId, startedAt, label
+          // - metrics: above + token_usage, files_touched, checkpoints_count, toolCallCount, duration_ms
+          // - full: everything
+          const isMetrics = syncLevel === "metrics" || syncLevel === "full";
+          const isFull = syncLevel === "full";
+
+          const checkpoint: TrajectoryCheckpointPayload = {
+            id: `${params.sessionId}-step${checkpointCounter}`,
+            session_id: params.sessionId,
+            agent: agentRecord?.name ?? agentId,
+            branch: git.branch,
+            files_touched: isMetrics ? Array.from(filesTouched) : [],
+            checkpoints_count: isMetrics ? checkpointCounter : 0,
+            // Token usage — only at metrics level or above
+            ...(isMetrics && (tokenUsage.input_tokens > 0 || tokenUsage.output_tokens > 0)
+              ? { token_usage: tokenUsage }
+              : {}),
+            metadata: {
+              // lifecycle fields (always included)
+              phase: "active",
+              startedAt: sessionStartedAt,
+              label: `Step ${checkpointCounter} (${toolCallCount} tool calls)`,
+              // metrics fields
+              ...(isMetrics ? {
+                duration_ms: Date.now() - promptStartTime,
+                toolCallCount,
+              } : {}),
+              // full fields
+              ...(isFull ? {
+                project: agentCwd.split("/").pop() ?? "",
+                projectPath: agentCwd,
+                firstPrompt: firstPrompt ?? undefined,
+                gitCommitHash: git.commitHash ?? undefined,
+                gitRemoteUrl: git.remoteUrl ?? undefined,
+              } : {}),
+            },
+          };
+          // Enrich with sessionlog state if available (adds turn IDs, better token usage)
+          let enrichedCheckpoint = checkpoint;
+          try {
+            const { findActiveSession, enrichCheckpoint } = await import("../integrations/sessionlog.js");
+            const sessionState = findActiveSession(agentCwd);
+            if (sessionState) {
+              enrichedCheckpoint = enrichCheckpoint(sessionState, checkpoint);
+            }
+          } catch {
+            // sessionlog not available — use base checkpoint
           }
-        }
-      } else if (
-        updateType === "tool_call" ||
-        updateType === "tool_call_update"
-      ) {
-        const toolCallId = sessionUpdate.toolCallId as string | undefined;
-        const status = sessionUpdate.status as string | undefined;
-        const meta = sessionUpdate._meta as { claudeCode?: { toolName?: string } } | undefined;
-        const toolInfoCache = this.toolInfoCaches.get(acpSessionId);
-
-        // Cache tool info from initial tool_call events
-        if (updateType === "tool_call" && toolCallId && toolInfoCache) {
-          toolInfoCache.set(toolCallId, {
-            title: sessionUpdate.title as string | undefined,
-            name: meta?.claudeCode?.toolName,
-            input: sessionUpdate.rawInput,
-          });
-        }
 
-        if (status === "completed" || status === "failed") {
-          // Merge cached info for tool_call_update events that lack title/input
-          const cached = toolCallId ? toolInfoCache?.get(toolCallId) : undefined;
-          buffer.parts.push({
-            type: "tool",
-            toolCallId,
-            title: sessionUpdate.title ?? cached?.title,
-            name: meta?.claudeCode?.toolName ?? cached?.name,
-            status: sessionUpdate.status,
-            input: sessionUpdate.rawInput ?? cached?.input,
-            output: extractToolOutput(sessionUpdate.rawOutput),
-          });
+          sidecar.reportCheckpoint(enrichedCheckpoint).catch(() => {});
         }
-      }
-    }
-
-    // Forward updates via sessionUpdate (except permission_request which is handled above)
-    try {
-      await this.connection.sessionUpdate({
-        sessionId: acpSessionId,
-        update: sessionUpdate as Parameters<
-          AgentSideConnection["sessionUpdate"]
-        >[0]["update"],
-      });
-    } catch (err) {
-      console.error(
-        `[MacroAgent] Failed to forward ${updateType}:`,
-        err instanceof Error ? err.message : err,
-      );
-    }
-  }
-
-  /**
-   * Emit a session_info_update with title and timestamps.
-   * Uses agent task as title and session mapping timestamps.
-   */
-  private async emitSessionInfo(acpSessionId: ACPSessionId): Promise<void> {
-    const mapping = this.sessionMapper.getMapping(acpSessionId);
-    const agentId = mapping?.agentId;
-    const agent = agentId ? this.eventStore.getAgent(agentId) : null;
-
-    const title = agent?.task ?? null;
-    const updatedAt = new Date(mapping?.updatedAt ?? Date.now()).toISOString();
-
-    try {
-      await this.connection.sessionUpdate({
-        sessionId: acpSessionId,
-        update: {
-          sessionUpdate: "session_info_update",
-          title,
-          updatedAt,
-        } as Parameters<AgentSideConnection["sessionUpdate"]>[0]["update"],
-      });
-    } catch (err) {
-      console.warn(
-        `[MacroAgent] Failed to send session_info_update:`,
-        err instanceof Error ? err.message : err,
-      );
-    }
-  }
-
-  /**
-   * Build system prompt with configured prefix/suffix
-   */
-  private buildSystemPrompt(): string | undefined {
-    const { systemPromptPrefix, systemPromptSuffix } = this.initConfig;
-
-    if (!systemPromptPrefix && !systemPromptSuffix) {
-      return undefined;
-    }
-
-    const parts: string[] = [];
-    if (systemPromptPrefix) {
-      parts.push(systemPromptPrefix);
-    }
-    if (systemPromptSuffix) {
-      parts.push(systemPromptSuffix);
-    }
-
-    return parts.join("\n\n");
-  }
 
-  /**
-   * Merge default sub-agent config with per-spawn override
-   *
-   * Override values take precedence over defaults.
-   * Arrays (like mcpServers) are concatenated, not replaced.
-   */
-  private mergeSubAgentConfig(
-    defaults?: SubAgentConfig,
-    override?: SubAgentConfig,
-  ): SubAgentConfig | undefined {
-    if (!defaults && !override) {
-      return undefined;
-    }
-
-    if (!defaults) {
-      return override;
-    }
-
-    if (!override) {
-      return defaults;
-    }
-
-    // Deep merge with override taking precedence
-    return {
-      model: override.model ?? defaults.model,
-      maxTokens: override.maxTokens ?? defaults.maxTokens,
-      temperature: override.temperature ?? defaults.temperature,
-      permissionMode: override.permissionMode ?? defaults.permissionMode,
-      agentType: override.agentType ?? defaults.agentType,
-      // Merge env variables (override takes precedence for same keys)
-      env:
-        defaults.env || override.env
-          ? { ...defaults.env, ...override.env }
-          : undefined,
-      // Concatenate MCP servers (both default and override)
-      mcpServers:
-        [...(defaults.mcpServers ?? []), ...(override.mcpServers ?? [])]
-          .length > 0
-          ? [...(defaults.mcpServers ?? []), ...(override.mcpServers ?? [])]
-          : undefined,
-    };
-  }
+        return { stopReason: "end_turn" };
+      } catch (err) {
+        // If prompt fails, still return a valid response
+        return { stopReason: "cancelled" };
+      } finally {
+        sessionMapper.setProcessing(params.sessionId, false);
 
-  /**
-   * Convert SubAgentConfig to internal AgentConfig format
-   */
-  private toAgentConfig(config?: SubAgentConfig): AgentConfig | undefined {
-    if (!config) {
-      return undefined;
-    }
-
-    return {
-      model: config.model,
-      maxTokens: config.maxTokens,
-      temperature: config.temperature,
-      env: config.env,
-      mcpServers: config.mcpServers?.map((server) => ({
-        name: server.name,
-        command: server.command,
-        args: server.args,
-        env: server.env,
-      })),
-    };
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // History Persistence Helpers
-  // ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Ensure a conversation exists in the EventStore for a session.
-   * Uses the ACP session ID as the conversation ID for direct lookup.
-   */
-  private ensureConversation(
-    acpSessionId: ACPSessionId,
-    agentId: AgentId,
-  ): void {
-    // Guard: EventStore may not support conversations (e.g., in tests with mocks)
-    if (typeof this.eventStore.getConversation !== "function") return;
-
-    // Check if conversation already exists
-    const existing = this.eventStore.getConversation(acpSessionId);
-    if (existing) return;
-
-    try {
-      this.eventStore.emit({
-        type: "conversation",
-        source: { agent_id: agentId },
-        payload: {
-          action: "created",
-          conversation_id: acpSessionId,
-          conversation_type: "session",
-          subject: `ACP session ${acpSessionId}`,
-        },
-      });
-    } catch (error) {
-      console.warn(
-        `[MacroAgent] Failed to create conversation for session ${acpSessionId}:`,
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-  }
-
-  /**
-   * Record user and assistant turns after a prompt completes.
-   */
-  private recordPromptTurns(
-    acpSessionId: ACPSessionId,
-    agentId: AgentId,
-    userMessage: string,
-  ): void {
-    const buffer = this.promptBuffers.get(acpSessionId);
-    if (!buffer) return;
-
-    const now = Date.now();
-
-    try {
-      // Record user turn
-      if (userMessage) {
-        this.eventStore.emit({
-          type: "turn",
-          source: { agent_id: agentId },
-          payload: {
-            action: "recorded",
-            turn_id: `turn_user_${now}_${Math.random().toString(36).slice(2, 8)}`,
-            conversation_id: acpSessionId,
-            participant: "user",
-            timestamp: now,
-            content_type: "user_prompt",
-            content: userMessage,
-            source_type: "explicit",
-          },
-        });
-      }
-
-      // Record assistant turn with accumulated content (parts already in order)
-      const parts = buffer.parts;
-
-      if (parts.length > 0) {
-        this.eventStore.emit({
-          type: "turn",
-          source: { agent_id: agentId },
-          payload: {
-            action: "recorded",
-            turn_id: `turn_asst_${now}_${Math.random().toString(36).slice(2, 8)}`,
-            conversation_id: acpSessionId,
-            participant: agentId,
-            timestamp: now + 1, // +1ms to ensure ordering after user turn
-            content_type: "assistant_response",
-            content: { parts },
-            source_type: "explicit",
-          },
-        });
+        // Update agent state back to "idle" — local MAP server
+        try {
+          const mapServer = (system as any).mapServerInstance;
+          if (mapServer) {
+            const agents = mapServer.agents?.list?.() ?? [];
+            const mapAgent = agents.find(
+              (a: any) => a.metadata?.localAgentId === agentId,
+            );
+            if (mapAgent) {
+              mapServer.agents.updateState(mapAgent.id, "idle");
+            }
+          }
+        } catch { /* best effort */ }
       }
-    } catch (error) {
-      console.warn(
-        `[MacroAgent] Failed to record turns for session ${acpSessionId}:`,
-        error instanceof Error ? error.message : String(error),
-      );
-    } finally {
-      // Clean up the buffer and tool info cache
-      this.promptBuffers.delete(acpSessionId);
-      this.toolInfoCaches.delete(acpSessionId);
-    }
-  }
+    },
 
-  /**
-   * Handle _macro/getModels extension — returns the session's available models.
-   * Claude Code populates models asynchronously after session creation
-   * (via _model_state_update notification), so this allows the TUI to poll
-   * for the model list once it's available.
-   *
-   * Returns full model info (modelId + name) since Claude Code uses shorthand
-   * model IDs ("default", "sonnet") that don't match models.dev. The name
-   * field (e.g., "Claude Sonnet 4") enables better model registry matching.
-   */
-  private handleGetModels(params: { sessionId: string }): {
-    currentModelId: string | null;
-    availableModels: Array<{ modelId: string; name: string }>;
-  } {
-    const { sessionId } = params;
-    const agentId = this.sessionMapper.getAgentId(sessionId);
-    if (!agentId) {
-      return { currentModelId: null, availableModels: [] };
-    }
-    const session = this.agentManager.getSession(agentId);
-    if (!session) {
-      return { currentModelId: null, availableModels: [] };
-    }
-    // Try clientHandler's model info store first (from _model_state_update notification)
-    const clientHandler = (session as unknown as {
-      clientHandler?: {
-        getSessionModelInfo?: (id: string) => {
-          currentModelId: string | null;
-          availableModels: Array<{ modelId: string; name: string }>;
-        } | null;
-      };
-    }).clientHandler;
-    const modelInfo = clientHandler?.getSessionModelInfo?.(session.id);
-    if (modelInfo && modelInfo.availableModels.length > 0) {
-      return modelInfo;
-    }
-    // Fall back to Session.models (from initial session response — just IDs)
-    if (session.models && session.models.length > 0) {
-      return {
-        currentModelId: session.models[0],
-        availableModels: session.models.map((id) => ({ modelId: id, name: id })),
-      };
-    }
-    return { currentModelId: null, availableModels: [] };
-  }
-
-  /**
-   * Handle _macro/getHistory extension — returns conversation turns for a session
-   */
-  private handleGetHistory(params: GetHistoryRequest): GetHistoryResponse {
-    const { sessionId, limit } = params;
-
-    // Query turns from EventStore (conversation ID = session ID)
-    const turns = this.eventStore.listTurns({
-      conversationId: sessionId,
-      order: "asc",
-      limit: limit ?? 200,
-    });
-
-    // Convert to HistoryTurn format
-    const historyTurns: HistoryTurn[] = turns.map((turn) => ({
-      role:
-        turn.contentType === "user_prompt"
-          ? ("user" as const)
-          : ("assistant" as const),
-      timestamp: turn.timestamp,
-      content: turn.content,
-    }));
-
-    return { turns: historyTurns };
-  }
-
-  // ─────────────────────────────────────────────────────────────────
-  // Accessors
-  // ─────────────────────────────────────────────────────────────────
+    async cancel(params: CancelNotification): Promise<void> {
+      const mapping = sessionMapper.getMapping(params.sessionId);
+      if (!mapping) return;
 
-  /**
-   * Get the session mapper for testing/debugging
-   */
-  getSessionMapper(): SessionMapper {
-    return this.sessionMapper;
-  }
-
-  /**
-   * Get mapped agent ID for a session
-   */
-  getMappedAgentId(acpSessionId: ACPSessionId): AgentId | undefined {
-    return this.sessionMapper.getAgentId(acpSessionId);
-  }
+      try {
+        await agentManager.terminate(mapping.agentId, "cancelled");
+      } catch {
+        // Best effort cancellation
+      }
+    },
+
+    async extMethod(
+      method: string,
+      params: Record<string, unknown>,
+    ): Promise<Record<string, unknown>> {
+      return handleExtension(method, params);
+    },
+  };
 
-  /**
-   * Get the applied initialization config
-   */
-  getInitConfig(): MacroAgentInitConfig {
-    return this.initConfig;
-  }
+  return agent;
 }
+
+/**
+ * Get the SessionMapper instance from a macro-agent.
+ * Exposed for testing and for the WebSocket server.
+ */
+export { SessionMapper };