@desplega.ai/agent-swarm 1.87.0 → 1.89.0

package/src/providers/opencode-adapter.ts

@@ -20,6 +20,7 @@ import {
 import { validateOpencodeCredentials } from "../utils/credentials";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
 import type {
   CostData,
   CredCheckOptions,
@@ -176,6 +177,32 @@ function resolvePluginPath(): string {
   return join(import.meta.dir, "../../plugin/opencode-plugins/agent-swarm.ts");
 }
 
+// context-mode is installed globally via `npm install -g` (Dockerfile.worker),
+// which places it under the npm global modules dir. opencode resolves bare
+// plugin names with `import(await Bun.resolve(name, ...))`, which does NOT walk
+// the npm global dir — a bare "context-mode" entry only resolves if Bun
+// auto-installs from the registry at runtime, which fails on network-sandboxed
+// workers. So we hand opencode the ABSOLUTE path to the package's built
+// opencode-plugin entry, which imports cleanly with no network.
+const CONTEXT_MODE_GLOBAL_ROOTS = ["/usr/lib/node_modules", "/usr/local/lib/node_modules"];
+const CONTEXT_MODE_PLUGIN_SUBPATH = "context-mode/build/adapters/opencode/plugin.js";
+
+/**
+ * Resolve the absolute path to context-mode's opencode plugin entry, or `null`
+ * if it can't be found on disk. `CONTEXT_MODE_OPENCODE_PLUGIN_PATH` overrides
+ * the lookup (and must itself exist). Returning `null` lets the caller skip the
+ * plugin gracefully instead of handing opencode an unresolvable entry.
+ */
+export function resolveContextModePluginPath(): string | null {
+  const override = process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH;
+  if (override) return existsSync(override) ? override : null;
+  for (const root of CONTEXT_MODE_GLOBAL_ROOTS) {
+    const candidate = join(root, CONTEXT_MODE_PLUGIN_SUBPATH);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 export class OpencodeSession implements ProviderSession {
   private _sessionId: string;
   private listeners: Array<(event: ProviderEvent) => void> = [];
@@ -192,6 +219,7 @@ export class OpencodeSession implements ProviderSession {
   private completionPromise: Promise<ProviderResult>;
   private server: { url: string; close(): void };
   private aborted = false;
+  private completed = false;
 
   // Running cost accumulators
   private totalCostUsd = 0;
@@ -246,6 +274,10 @@ export class OpencodeSession implements ProviderSession {
     return this._sessionId;
   }
 
+  get isFinished(): boolean {
+    return this.completed;
+  }
+
   /** Emit the synthetic session_init event. Called by the adapter immediately
    * after construction; buffers if no listener is attached yet. */
   emitSessionInit(provider: "opencode"): void {
@@ -331,7 +363,7 @@ export class OpencodeSession implements ProviderSession {
 
   /** Process a single opencode SSE event */
   handleOpencodeEvent(ev: OpencodeEvent): void {
-    if (this.aborted) return;
+    if (this.aborted || this.completed) return;
 
     // Always emit the raw event as a scrubbed raw_log
     const rawContent = scrubSecrets(JSON.stringify(ev));
@@ -444,7 +476,7 @@ export class OpencodeSession implements ProviderSession {
         for (const l of this.listeners) l(resultEvent);
         const raw = scrubSecrets(JSON.stringify(resultEvent));
         this.emitDirect({ type: "raw_log", content: raw });
-        this.completionResolve({
+        void this.finish({
           exitCode: 0,
           sessionId: this._sessionId,
           cost,
@@ -488,7 +520,7 @@ export class OpencodeSession implements ProviderSession {
     const raw = scrubSecrets(JSON.stringify(errorEvent));
     this.emitDirect({ type: "raw_log", content: raw });
     const cost = this.buildCostData(true);
-    this.completionResolve({
+    void this.finish({
       exitCode: 1,
       sessionId: this._sessionId,
       cost,
@@ -519,12 +551,22 @@ export class OpencodeSession implements ProviderSession {
     return this.completionPromise;
   }
 
+  private async finish(result: ProviderResult): Promise<void> {
+    if (this.completed) return;
+    this.completed = true;
+    try {
+      this.server.close();
+    } catch {
+      // best-effort
+    }
+    await this.cleanupFiles();
+    this.completionResolve(result);
+  }
+
   async abort(): Promise<void> {
     if (this.aborted) return;
     this.aborted = true;
-    this.server.close();
-    await this.cleanupFiles();
-    this.completionResolve({
+    await this.finish({
       exitCode: 1,
       sessionId: this._sessionId,
       isError: true,
@@ -588,6 +630,27 @@ export class OpencodeAdapter implements ProviderAdapter {
     // an accident, not a contract.
     const pluginPath = resolvePluginPath();
 
+    // context-mode ships as an in-process opencode plugin (NOT an MCP server).
+    // Its built plugin entry registers both the native ctx_* tools and the 5
+    // hook surrogates. It must NOT also appear in the `mcp` block — dual
+    // registration yields zero tools. We push the ABSOLUTE path to the globally
+    // installed package's opencode plugin entry, not the bare name (see
+    // resolveContextModePluginPath for why a bare name fails to resolve offline).
+    // Gated by CONTEXT_MODE_DISABLED so builds/deploys without it opt out.
+    const plugins = [pluginPath];
+    if (process.env.CONTEXT_MODE_DISABLED !== "true") {
+      const contextModePluginPath = resolveContextModePluginPath();
+      if (contextModePluginPath) {
+        plugins.push(contextModePluginPath);
+      } else {
+        console.warn(
+          "[opencode] context-mode is enabled but its opencode plugin entry was not found on disk; " +
+            "skipping it for this session. Set CONTEXT_MODE_OPENCODE_PLUGIN_PATH to override, or " +
+            "CONTEXT_MODE_DISABLED=true to silence.",
+        );
+      }
+    }
+
     // Build per-task opencode config (plugin field carries the swarm plugin)
     const opencodeConfig: Config & { plugin?: string[] } = {
       $schema: "https://opencode.ai/config.json",
@@ -600,7 +663,7 @@ export class OpencodeAdapter implements ProviderAdapter {
         doom_loop: "allow",
         external_directory: "allow",
       },
-      plugin: [pluginPath],
+      plugin: plugins,
     };
 
     // Write per-task config file
@@ -626,6 +689,7 @@ export class OpencodeAdapter implements ProviderAdapter {
     process.env.SWARM_AGENT_ID = config.agentId;
     process.env.SWARM_TASK_ID = config.taskId;
     process.env.SWARM_IS_LEAD = config.role === "lead" ? "true" : "false";
+    process.env.CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY = CTX_MODE_NUDGE_EVERY;
 
     // Set OPENCODE_CONFIG scoped to the spawn call (save + restore)
     const prevOpencodeConfig = process.env.OPENCODE_CONFIG;
@@ -711,6 +775,7 @@ export class OpencodeAdapter implements ProviderAdapter {
       .then(async ({ stream }) => {
         for await (const event of stream) {
           session.handleOpencodeEvent(event as OpencodeEvent);
+          if (session.isFinished) break;
         }
         // Stream ended without session.idle — treat as completion
       })

package/src/server.ts

@@ -6,6 +6,7 @@ import { registerCancelTaskTool } from "./tools/cancel-task";
 import { registerContextDiffTool } from "./tools/context-diff";
 import { registerContextHistoryTool } from "./tools/context-history";
 import { registerCreateChannelTool } from "./tools/create-channel";
+import { registerCreateMetricTool } from "./tools/create-metric";
 import { registerCreatePageTool } from "./tools/create-page";
 import { registerDbQueryTool } from "./tools/db-query";
 import { registerDeleteChannelTool } from "./tools/delete-channel";
@@ -109,6 +110,7 @@ import {
   registerListConfigTool,
   registerSetConfigTool,
 } from "./tools/swarm-config";
+import { registerSwarmXTool } from "./tools/swarm-x";
 // Task pool capability
 import { registerTaskActionTool } from "./tools/task-action";
 // Tracker capability
@@ -146,7 +148,7 @@ import {
 // Capability-based feature flags
 // Default: all capabilities enabled
 const DEFAULT_CAPABILITIES =
-  "core,task-pool,profiles,services,scheduling,memory,workflows,pages,kv";
+  "core,task-pool,profiles,services,scheduling,memory,workflows,pages,metrics,kv";
 const CAPABILITIES = new Set(
   (process.env.CAPABILITIES || DEFAULT_CAPABILITIES).split(",").map((s) => s.trim()),
 );
@@ -226,6 +228,9 @@ export function createServer() {
   registerScriptDeleteTool(server);
   registerScriptQueryTypesTool(server);
 
+  // External command routes - mirrors the `agent-swarm x ...` CLI surface.
+  registerSwarmXTool(server);
+
   // Slack integration tools (always registered, will no-op if Slack not configured)
   registerSlackReplyTool(server);
   registerSlackReadTool(server);
@@ -338,6 +343,10 @@ export function createServer() {
     registerCreatePageTool(server);
   }
 
+  if (hasCapability("metrics")) {
+    registerCreateMetricTool(server);
+  }
+
   // KV capability — namespaced Redis-like key/value (see src/be/migrations/061_kv_store.sql).
   // Enabled by default; opt out via `CAPABILITIES=...` without `kv`.
   if (hasCapability("kv")) {

package/src/slack/blocks.ts

@@ -5,7 +5,7 @@
  * across responses.ts, handlers.ts, thread-buffer.ts).
  */
 
-import type { TaskAttachment } from "../types";
+import type { AgentTaskStatus, TaskAttachment } from "../types";
 import { buildAgentFsLiveUrl, getAppUrl } from "../utils/constants";
 
 // Slack limits section text to 3000 chars; we use 2900 for safety
@@ -205,7 +205,7 @@ export function formatDuration(start: Date, end: Date): string {
 export interface TreeNode {
   taskId: string;
   agentName: string;
-  status: "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+  status: AgentTaskStatus;
   progress?: string;
   duration?: string;
   slackReplySent?: boolean;
@@ -342,12 +342,20 @@ export function buildBufferFlushBlocks(opts: {
 
 // --- Tree rendering ---
 
-const STATUS_ICON: Record<TreeNode["status"], string> = {
+type TreeStatusIcon = TreeNode["status"] | "superseded";
+
+const STATUS_ICON: Record<TreeStatusIcon, string> = {
+  backlog: "🗂️",
+  unassigned: "📭",
+  offered: "📨",
+  reviewing: "👀",
   pending: "📡",
   in_progress: "⏳",
+  paused: "⏸️",
   completed: "✅",
   failed: "❌",
   cancelled: "🚫",
+  superseded: "↪️",
 };
 
 const MAX_VISIBLE_CHILDREN = 8;
@@ -368,7 +376,7 @@ function truncateOutput(text: string): string {
  * Render a single node line: icon + bold name + task link + optional duration.
  */
 function renderNodeLine(node: TreeNode): string {
-  const icon = STATUS_ICON[node.status];
+  const icon = STATUS_ICON[node.status] ?? "•";
   const taskLink = getTaskLink(node.taskId);
   let line = `${icon} *${node.agentName}* (${taskLink})`;
   if (node.duration) line += ` · ${node.duration}`;

package/src/slack/watcher.ts

@@ -144,7 +144,7 @@ export function buildTreeNodes(tree: TreeMessageState): TreeNode[] {
         childNodes.push({
           taskId: child.id,
           agentName: childAgentName,
-          status: child.status as TreeNode["status"],
+          status: child.status,
           progress: child.progress ?? undefined,
           duration: childDuration,
           slackReplySent: child.slackReplySent,
@@ -164,7 +164,7 @@ export function buildTreeNodes(tree: TreeMessageState): TreeNode[] {
     nodes.push({
       taskId: task.id,
       agentName,
-      status: task.status as TreeNode["status"],
+      status: task.status,
       progress: task.progress ?? undefined,
       duration,
       slackReplySent: task.slackReplySent,
@@ -382,7 +382,7 @@ async function postInitialDMTreeMessage(task: AgentTask): Promise<string | undef
   const initialNode: TreeNode = {
     taskId: task.id,
     agentName: agent.name,
-    status: task.status as TreeNode["status"],
+    status: task.status,
     progress: task.progress ?? undefined,
     children: [],
   };

package/src/telemetry.ts

@@ -15,6 +15,7 @@ const TIMEOUT_MS = 5_000;
 let installationId: string | null = null;
 let source = "unknown";
 let cachedIsCloud = false;
+let cachedIsE2b = false;
 
 function isEnabled(): boolean {
   return process.env.ANONYMIZED_TELEMETRY !== "false";
@@ -41,6 +42,15 @@ function isCloudHostname(hostname: string): boolean {
   return CLOUD_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
 }
 
+/**
+ * Detect whether the current process is running inside an E2B sandbox.
+ * E2B automatically exposes `E2B_SANDBOX_ID` inside every sandbox.
+ * Exported for tests; not part of the public API.
+ */
+export function _isE2bSandbox(): boolean {
+  return typeof process.env.E2B_SANDBOX_ID === "string" && process.env.E2B_SANDBOX_ID.length > 0;
+}
+
 /**
  * Parse `MCP_BASE_URL` (or any candidate URL) into the cloud flag we ship on
  * every telemetry event. URL parsing — not substring match — so we never
@@ -100,7 +110,8 @@ export async function initTelemetry(
 
   const resolved = _resolveCloudMode(process.env.MCP_BASE_URL);
   cachedIsCloud = resolved.isCloud;
-  console.log(`telemetry: cloud=${cachedIsCloud}`);
+  cachedIsE2b = _isE2bSandbox();
+  console.log(`telemetry: cloud=${cachedIsCloud} e2b=${cachedIsE2b}`);
 
   try {
     const existing = await getConfig("telemetry_installation_id");
@@ -183,6 +194,7 @@ export function track(options: TrackOptions): void {
         // The hostname is intentionally NOT included — telemetry must stay
         // anonymous, and the boolean is sufficient to split cloud vs self-host.
         is_cloud: cachedIsCloud,
+        is_e2b: cachedIsE2b,
       },
       metadata: {
         transport: "https",
@@ -212,6 +224,7 @@ export function _resetTelemetryStateForTests(): void {
   installationId = null;
   source = "unknown";
   cachedIsCloud = false;
+  cachedIsE2b = false;
 }
 
 /** Test-only: read the resolved install ID. */

package/src/templates.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/tests/base-prompt.test.ts

@@ -272,6 +272,41 @@ describe("getBasePrompt — repoContext", () => {
     expect(result).toContain("Repository Guidelines (MANDATORY)");
     expect(result).toContain("Auto-merge: Allowed");
   });
+
+  test("surfaces swarm-autostash entries when present", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      repoContext: {
+        claudeMd: "Rules",
+        clonePath: "/workspace/my-repo",
+        autoStashes: [
+          {
+            ref: "stash@{0}",
+            message: "On main: swarm-autostash main 2026-06-01T13:00:00.000Z",
+          },
+        ],
+      },
+    });
+
+    expect(result).toContain("Pending auto-stashed work exists in this repo");
+    expect(result).toContain("stash@{0}: On main: swarm-autostash main");
+    expect(result).toContain("git stash apply <ref>");
+    expect(result).toContain("git stash pop <ref>");
+  });
+
+  test("does not mention auto-stashed work when no swarm-autostash entries exist", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      repoContext: {
+        claudeMd: "Rules",
+        clonePath: "/workspace/my-repo",
+        autoStashes: [],
+      },
+    });
+
+    expect(result).not.toContain("Pending auto-stashed work exists in this repo");
+    expect(result).not.toContain("git stash apply <ref>");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -605,6 +640,47 @@ describe("getBasePrompt — local providers unaffected", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Context-mode block — provider gating
+//
+// The context_mode block advertises the `ctx_*` MCP tools. It is included for
+// local providers that have context-mode wired into their per-session config
+// (claude, codex, opencode) and excluded for `pi`, which has no context-mode
+// wiring yet (deferred to DES-514). Remote-provider exclusion is covered by the
+// "remote provider excluded sections" suite above.
+// ---------------------------------------------------------------------------
+const localTraits: ProviderTraits = { hasMcp: true, hasLocalEnvironment: true };
+
+describe("getBasePrompt — context-mode provider gating", () => {
+  test("excludes context-mode block for pi provider", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      traits: localTraits,
+      provider: "pi",
+    });
+    expect(result).not.toContain("Context Window Management");
+    expect(result).not.toContain("context-mode");
+  });
+
+  for (const provider of ["claude", "codex", "opencode"] as const) {
+    test(`includes context-mode block for ${provider} provider`, async () => {
+      const result = await getBasePrompt({
+        ...minimalArgs,
+        traits: localTraits,
+        provider,
+      });
+      expect(result).toContain("Context Window Management");
+      expect(result).toContain("context-mode");
+    });
+  }
+
+  test("includes context-mode block when provider is unspecified (local default)", async () => {
+    const result = await getBasePrompt({ ...minimalArgs, traits: localTraits });
+    expect(result).toContain("Context Window Management");
+    expect(result).toContain("context-mode");
+  });
+});
+
 describe("getBasePrompt — conditional Slack templates", () => {
   test("omits Slack tool templates when Slack is disabled", async () => {
     disableSlackPromptTools();

package/src/tests/budget-claim-gate.test.ts

@@ -11,6 +11,7 @@ import {
   createAgent,
   createSessionCost,
   createTaskExtended,
+  createUser,
   getAgentById,
   getDb,
   incrementEmptyPollCount,
@@ -129,6 +130,31 @@ describe("Phase 3 — /api/poll budget admission gate", () => {
     expect((body.trigger as { taskId: string }).taskId).toBe(task.id);
   });
 
+  test("pending task trigger includes requester role and notes", async () => {
+    const worker = createAgent({ name: "w-requester", isLead: false, status: "idle", maxTasks: 1 });
+    const requester = createUser({
+      name: "Requester One",
+      email: "requester@example.com",
+      role: "engineering manager",
+      notes: "Include implementation detail and test coverage.",
+    });
+    createTaskExtended("profile-aware task", {
+      agentId: worker.id,
+      requestedByUserId: requester.id,
+    });
+
+    const { status, body } = await callPoll(worker.id);
+    expect(status).toBe(200);
+    if ("error" in body) throw new Error("unexpected error response");
+    expect(body.trigger?.type).toBe("task_assigned");
+    expect(body.trigger?.requestedBy).toEqual({
+      name: "Requester One",
+      email: "requester@example.com",
+      role: "engineering manager",
+      notes: "Include implementation detail and test coverage.",
+    });
+  });
+
   test("no budgets configured + no work → trigger=null", async () => {
     const worker = createAgent({ name: "w-empty", isLead: false, status: "idle", maxTasks: 1 });
     const { status, body } = await callPoll(worker.id);

package/src/tests/claude-adapter.test.ts

@@ -246,6 +246,23 @@ describe("mergeMcpConfig (issue #369)", () => {
     const merged = mergeMcpConfig({ mcpServers: {} }, {}, TASK_ID);
     expect(Object.keys(merged.mcpServers)).toHaveLength(0);
   });
+
+  test("preserves a context-mode entry through the merge", () => {
+    const base = {
+      mcpServers: {
+        "agent-swarm": {
+          type: "http",
+          url: "http://localhost:3013/mcp",
+          headers: { Authorization: "Bearer KEY", "X-Agent-ID": "a1" },
+        },
+        "plugin_context-mode_context-mode": { command: "context-mode" },
+      },
+    };
+    const merged = mergeMcpConfig(base, null, TASK_ID);
+    expect(merged.mcpServers["plugin_context-mode_context-mode"]).toEqual({
+      command: "context-mode",
+    });
+  });
 });
 
 describe("createSessionMcpConfig", () => {
@@ -323,7 +340,13 @@ describe("createSessionMcpConfig", () => {
     const written = await readWritten(path!);
     expect(written.mcpServers["agent-swarm"]).toBeDefined();
     expect(written.mcpServers.Datadog).toBeDefined();
-    expect(Object.keys(written.mcpServers).sort()).toEqual(["Datadog", "agent-swarm"]);
+    // context-mode is injected by default (see CONTEXT_MODE_DISABLED gate); the
+    // two differently-named .mcp.json servers still merge alongside it.
+    expect(Object.keys(written.mcpServers).sort()).toEqual([
+      "Datadog",
+      "agent-swarm",
+      "plugin_context-mode_context-mode",
+    ]);
   });
 
   test("ancestor wins over repo-local on agent-swarm key conflict", async () => {
@@ -402,4 +425,66 @@ describe("createSessionMcpConfig", () => {
     const written = await readWritten(path!);
     expect(written.mcpServers["from-api"]).toBeDefined();
   });
+
+  test("includes context-mode entry when CONTEXT_MODE_DISABLED is unset", async () => {
+    const prev = process.env.CONTEXT_MODE_DISABLED;
+    delete process.env.CONTEXT_MODE_DISABLED;
+    try {
+      await writeFile(
+        join(sandbox, ".mcp.json"),
+        JSON.stringify({
+          mcpServers: {
+            "agent-swarm": {
+              type: "http",
+              url: "http://swarm/mcp",
+              headers: { Authorization: "Bearer SWARM", "X-Agent-ID": "a1" },
+            },
+          },
+        }),
+      );
+      const cwd = join(sandbox, "repos", "foo");
+      await mkdir(cwd, { recursive: true });
+
+      const path = await createSessionMcpConfig(cwd, "task-ctx-on");
+      const written = await readWritten(path!);
+      expect(written.mcpServers["plugin_context-mode_context-mode"]).toEqual({
+        command: "context-mode",
+      });
+      // Coexists with the swarm entry.
+      expect(written.mcpServers["agent-swarm"]).toBeDefined();
+    } finally {
+      if (prev === undefined) delete process.env.CONTEXT_MODE_DISABLED;
+      else process.env.CONTEXT_MODE_DISABLED = prev;
+    }
+  });
+
+  test("excludes context-mode entry when CONTEXT_MODE_DISABLED='true'", async () => {
+    const prev = process.env.CONTEXT_MODE_DISABLED;
+    process.env.CONTEXT_MODE_DISABLED = "true";
+    try {
+      await writeFile(
+        join(sandbox, ".mcp.json"),
+        JSON.stringify({
+          mcpServers: {
+            "agent-swarm": {
+              type: "http",
+              url: "http://swarm/mcp",
+              headers: { Authorization: "Bearer SWARM", "X-Agent-ID": "a1" },
+            },
+          },
+        }),
+      );
+      const cwd = join(sandbox, "repos", "foo");
+      await mkdir(cwd, { recursive: true });
+
+      const path = await createSessionMcpConfig(cwd, "task-ctx-off");
+      const written = await readWritten(path!);
+      expect(written.mcpServers["plugin_context-mode_context-mode"]).toBeUndefined();
+      // The swarm entry is still present.
+      expect(written.mcpServers["agent-swarm"]).toBeDefined();
+    } finally {
+      if (prev === undefined) delete process.env.CONTEXT_MODE_DISABLED;
+      else process.env.CONTEXT_MODE_DISABLED = prev;
+    }
+  });
 });

package/src/tests/codex-adapter.test.ts

@@ -872,9 +872,21 @@ describe("computeCodexCostUsd", () => {
 describe("buildCodexConfig", () => {
   // Save and restore the global fetch so we don't leak mocks between tests.
   const originalFetch = globalThis.fetch;
+  // These tests assert the EXACT set of mcp_servers keys, which is only the
+  // installed-server merge logic. Disable the always-on context-mode entry so
+  // those exact-key assertions stay valid; a dedicated block below verifies
+  // the context-mode + features behavior. Save/restore the env to avoid leaks.
+  let prevContextModeDisabled: string | undefined;
+
+  beforeEach(() => {
+    prevContextModeDisabled = process.env.CONTEXT_MODE_DISABLED;
+    process.env.CONTEXT_MODE_DISABLED = "true";
+  });
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    if (prevContextModeDisabled === undefined) delete process.env.CONTEXT_MODE_DISABLED;
+    else process.env.CONTEXT_MODE_DISABLED = prevContextModeDisabled;
   });
 
   // Helper: build a ProviderSessionConfig pointed at a mock endpoint.
@@ -1098,6 +1110,83 @@ describe("buildCodexConfig", () => {
   });
 });
 
+// ─── Phase 3: buildCodexConfig — context-mode MCP + hook feature flags ───────
+
+describe("buildCodexConfig — context-mode + features", () => {
+  const originalFetch = globalThis.fetch;
+  // Explicitly own CONTEXT_MODE_DISABLED here. Save the ambient value up front
+  // and restore it after every test so we never leak the mutation to siblings.
+  let prevContextModeDisabled: string | undefined;
+
+  beforeEach(() => {
+    prevContextModeDisabled = process.env.CONTEXT_MODE_DISABLED;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    if (prevContextModeDisabled === undefined) delete process.env.CONTEXT_MODE_DISABLED;
+    else process.env.CONTEXT_MODE_DISABLED = prevContextModeDisabled;
+  });
+
+  function cfg(overrides: Partial<ProviderSessionConfig> = {}): ProviderSessionConfig {
+    return {
+      prompt: "hello",
+      systemPrompt: "",
+      model: "gpt-5.4",
+      role: "worker",
+      agentId: "agent-mcp-test",
+      taskId: "task-mcp-test",
+      apiUrl: "http://test.invalid",
+      apiKey: "test-key",
+      cwd: "",
+      logFile: `/tmp/codex-ctx-test-${Date.now()}-${Math.random().toString(36).slice(2)}.log`,
+      ...overrides,
+    };
+  }
+
+  function stubFetch(body: unknown, status = 200): typeof globalThis.fetch {
+    return async (): Promise<Response> => {
+      return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+  }
+
+  test("includes the 'context-mode' mcp_servers entry by default", async () => {
+    delete process.env.CONTEXT_MODE_DISABLED;
+    globalThis.fetch = stubFetch({ servers: [], total: 0 });
+    const merged = await buildCodexConfig(cfg(), "gpt-5.4", () => {});
+    const mcp = merged.mcp_servers as Record<string, Record<string, unknown>>;
+
+    expect(Object.keys(mcp).sort()).toEqual(["agent-swarm", "context-mode"]);
+    expect(mcp["context-mode"]?.command).toBe("context-mode");
+    expect(mcp["context-mode"]?.enabled).toBe(true);
+    expect(mcp["context-mode"]?.startup_timeout_sec).toBe(30);
+    expect(mcp["context-mode"]?.tool_timeout_sec).toBe(120);
+  });
+
+  test("excludes the 'context-mode' entry when CONTEXT_MODE_DISABLED=true", async () => {
+    process.env.CONTEXT_MODE_DISABLED = "true";
+    globalThis.fetch = stubFetch({ servers: [], total: 0 });
+    const merged = await buildCodexConfig(cfg(), "gpt-5.4", () => {});
+    const mcp = merged.mcp_servers as Record<string, Record<string, unknown>>;
+
+    expect(Object.keys(mcp)).toEqual(["agent-swarm"]);
+    expect(mcp["context-mode"]).toBeUndefined();
+  });
+
+  test("sets features.hooks and features.plugin_hooks to true", async () => {
+    delete process.env.CONTEXT_MODE_DISABLED;
+    globalThis.fetch = stubFetch({ servers: [], total: 0 });
+    const merged = await buildCodexConfig(cfg(), "gpt-5.4", () => {});
+
+    const features = merged.features as Record<string, unknown>;
+    expect(features.hooks).toBe(true);
+    expect(features.plugin_hooks).toBe(true);
+  });
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Phase 3 — session-end summarization
 // ─────────────────────────────────────────────────────────────────────────────