@ours.network/fleet 0.19.0-nightly.8 → 1.0.0

package/dist/docs.js

@@ -271,6 +271,9 @@ roles:
       add_dirs: [/data/shared]
       config:
         model_reasoning_effort: high
+      mcp_servers:                       # claude-code: per-role MCP servers, additive by default
+        ours: { command: ours-mcp, args: [proxy] }
+      mcp_servers_only: false            # true = ONLY these; drops user/project/plugin servers
     bio: Public role card and when peers should engage it.
     persona: Local operating contract, boundaries, and escalation policy.
     briefing_file: /absolute/custom-briefing.md
@@ -315,6 +318,68 @@ Role values override defaults. \`\${name}\` substitutes entries from \`vars\`.
 Other role fields include \`max_tokens\`, \`autocompact_pct\`, and \`isolation\`.
 Use README.md for the complete isolation policy and resource-cap schema.
 
+Supervised roles connect to the operator-configured ours daemon; they do not own its
+lifecycle. Fleet forces \`OURS_AUTOSTART=0\` in tmux and ACP child processes after role
+environment overlays. Start the shared daemon only through an explicit operator or
+installer/setup flow.
+
+## Rooms and tasks
+
+Rooms always use \`ours-cowork\`; there is no room-provider selector. Configure
+the cowork daemon connection and room owner directly:
+
+\`\`\`yaml
+rooms:
+  cowork:
+    config: /home/me/.ours-cowork/config.json
+  owner:
+    expected_cid: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+    public_invite_file: /home/me/.ours-fleet/owner-room-invite.txt
+  defaults:
+    template: team
+    attach_owner: true
+    close_when_task_done: true
+tasks:
+  default_room_template: team
+  create_mode: start
+  close_room_on_done: true
+\`\`\`
+
+Human task and room results use the same compact Markdown presentation in the
+CLI and authenticated owner channel: a short heading, icon-plus-word status,
+code-formatted identifiers, bounded summaries, and actionable recovery or error
+steps. Untrusted prose is context-escaped and control characters are neutralized;
+Messenger-bound results are capped at 3,500 Unicode code points and 12,000 UTF-8
+bytes with structural omission notices. \`--json\` bypasses this presentation layer
+and retains the versioned machine schema and serialization order.
+
+Older prerelease files with the exact legacy \`provider: cowork\` key under
+\`rooms:\` still load, but the key is ignored and omitted from resolved
+configuration. Remove it when editing the file. Any other legacy value is an
+error. The optional \`rooms.owner.provider\` setting is separate and defaults to
+\`messenger-server\`.
+
+Finish and Delete are distinct terminal task actions:
+
+\`ours-fleet task finish <id>\` moves an active or review task to \`done\` and
+deletes its associated Cowork room after retiring its members. The room then
+disappears from normal Fleet and Cowork views; its brief, messages, repository
+references, and attachments are not retained as an inspectable archive.
+The prerelease configuration names \`tasks.close_room_on_done\` and
+\`rooms.defaults.close_when_task_done\` are retained for compatibility, but
+\`true\` now means this close-then-delete behavior.
+
+\`ours-fleet room delete <id> <id>\` is the canonical destructive room command.
+\`room close <id> <id>\` remains a deprecated alias with identical deletion
+semantics. Older prerelease \`closed\` room records are deleted directly the next
+time \`room list\` reconciles Fleet with Cowork.
+
+\`ours-fleet task delete <id> <id>\` removes only a \`done\` task's Fleet backlog
+record. The exact task ID is required twice for confirmation. Delete rejects every
+other task state, never changes any room state, and reports an already-missing
+task as an idempotent no-op. The Owner-channel equivalent is
+\`/task delete <id> <id>\`.
+
 ## Permissions
 
 Prefer the harness-neutral \`permissions\` block:
@@ -400,10 +465,14 @@ permissions through its harness and check the result against a fixed floor:
 deny those requests with nobody to see it; with \`unattended: wait\` it warns,
 because a human can still attach and answer.
 
-Security meaning: \`ask\` maps to Codex \`untrusted\` and Claude \`default\`;
-\`auto\` maps to Codex \`on-request\` and Claude \`acceptEdits\`; and
-\`approval: allow\` maps to Codex \`never\` and Claude \`bypassPermissions\`,
-which genuinely permits the actions the role was authorized to take —
+Security meaning: \`ask\` maps to Codex \`untrusted\` and Claude \`default\`.
+\`auto\` selects Codex ACP \`agent\` (\`on-request\` + \`workspace-write\`) and
+Claude \`acceptEdits\`. \`approval: allow\` selects Codex ACP's fully
+non-interactive yolo mode, reported as \`agent-full-access\` (\`never\` +
+\`danger-full-access\`), and Claude \`bypassPermissions\`. Codex tmux retains
+independent approval and sandbox flags: \`auto\` is \`on-request\`, \`allow\`
+is \`never\`, and \`filesystem\` still selects the sandbox. These modes genuinely
+permit the actions the role was authorized to take —
 \`dontAsk\` only suppresses the prompt while still refusing the action. Nothing
 other than an explicit \`allow\` becomes non-interactive. Legacy \`deny\` keeps
 its conservative Codex \`on-request\` / Claude \`plan\` translation. \`allow\` is therefore a real grant and
@@ -414,20 +483,45 @@ ACP carries agent-advertised session mode IDs and \`session/set_mode\`, but thos
 IDs are agent-specific and ACP defines no portable permission-policy capability.
 Fleet therefore uses the ACP primitive where an adapter exposes a matching mode
 and otherwise performs the harness translation above. The bundled Codex ACP
-adapter couples approval and sandboxing in its advertised mode IDs, so fleet
-keeps the selected sandbox preset and enforces the independently translated
-approval policy on the app-server turn request. For example, \`allow\` plus
-\`workspace\` is really \`approval=never sandbox=workspace-write\`; it is never
-widened to \`danger-full-access\`. The live session reports both its effective
-normalized mode and the ACP sandbox-preset ID.
+adapter couples approval and sandboxing in its advertised mode IDs. Neutral
+\`allow\` therefore selects \`agent-full-access\` and widens \`filesystem:
+workspace\` or \`read-only\` to \`danger-full-access\`; neutral \`auto\` selects
+\`agent\` and \`workspace-write\` even when the neutral filesystem value differs.
+An explicit \`harness_options.sandbox\` selects its corresponding ACP preset and
+still wins, as does an explicit native approval override. \`config\` and
+\`doctor\` report a coupled-mode mismatch as approximate. Use per-role
+\`isolation:\` as the outer boundary for an \`allow\` ACP role. The live session
+reports both its effective normalized mode and the exact native mode selected.
 
 See also: \`spawn --approval/--filesystem/--unattended\` set this intent at
 creation, and \`ours-fleet config\` prints each role's neutral settings, their
 native translation, and any warning — the same text \`doctor\` reports.
 
 Claude \`harness_options\`: \`permission_mode\` (default, acceptEdits, plan,
-dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`, and
-\`mem_palace_midsession_autosave\`.
+dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`,
+\`mem_palace_midsession_autosave\`, \`mcp_servers\` and \`mcp_servers_only\`.
+
+\`mcp_servers\` declares MCP servers for the role, in \`.mcp.json\`'s own shape
+(a map of name to \`{ command, args, env }\`, or \`{ type: http|sse, url,
+headers }\`). By default they are ADDED to whatever the OS user running the role
+already has configured, on both session types: tmux passes \`--mcp-config\`, and
+ACP sends them in \`session/new\`.
+
+\`mcp_servers_only: true\` makes the declared set EXCLUSIVE — \`--strict-mcp-config\`
+on tmux, \`strictMcpConfig\` on ACP. It is all-or-nothing and it ignores every
+other MCP configuration: project \`.mcp.json\`, user settings, and **plugins**.
+The ours connector is normally installed as a plugin, so a strict role that does
+not re-declare it has no \`send_message\` and no \`get_messages\` — it cannot even
+report that it has gone mute. Fleet therefore refuses a strict role whose
+\`mcp_servers\` does not name the connector; declare it explicitly, e.g.
+\`ours: { command: ours-mcp, args: [proxy] }\`.
+
+Both options, and \`plugins\`, reach an ACP session through the bundled Claude ACP
+agent's \`_meta\` vocabulary. A role that sets \`session_options.acp.command\` runs
+an agent fleet did not choose and cannot be promised them, so that combination is
+refused at validation rather than accepted and dropped. This narrows a role's
+tool surface; it does not stop the harness deferring tool schemas, which is the
+harness's own decision.
 
 Codex \`harness_options\`: \`launcher\` (auto, ours-codex, codex), \`sandbox\`
 (read-only, workspace-write, danger-full-access), \`approval\` or
@@ -522,12 +616,11 @@ owner of that authenticated source wire instead of the latest conversation.
 Every other CID is rejected and warned about without reflecting its body. Fleet sends
 accepted/queued/progress/interrupted/failure notices and routes the ACP turn's
 final assistant text back to the authenticated sender with its source wire ID.
-For file replies, fleet injects a request-specific outbox path into the owner
-prompt. The agent copies completed artifacts there; fleet sends every regular
-file from the channel identity with the same source wire ID and removes the
-temporary outbox only after successful delivery. For proactive or in-turn agent
-attachments, the agent calls ours \`send_file\` to the channel identity and may
-pair it with a reply-linked caption; fleet, not the agent, chooses the owner.
+For file replies of every kind — a response artifact, a proactive note, or an
+in-turn attachment — the agent calls ours \`send_file\` to the channel identity
+and may pair it with a reply-linked caption; fleet, not the agent, chooses the
+owner. That is the only delivery route an agent is given: a tool call either
+delivers or reports an error, where a file written to disk does neither.
 Owner messages whose trimmed text starts with \`/\` are deterministic
 supervisor commands and never enter the model: \`/help\` (alias \`/commands\`),
 \`/status\`, \`/comments [status|on|off]\`, \`/interrupt\`, \`/clear\`,
@@ -674,10 +767,38 @@ escape hatch.
 
 ## Bounded worklogs, auth proxy, and model recovery
 
-An optional \`worklog: { max_kb, keep_tail_kb, max_archives }\` policy rotates a
-stable snapshot at fleet-owned lifecycle points. Concurrent changes defer
-rotation. Archives remain beside WORKLOG.md with the same sensitive-state
-boundary; retention deletes only recognized fleet archive names.
+WORKLOG rotation is enabled by default with
+\`worklog: { max_kb: 1024, keep_tail_kb: 256, max_archives: 12 }\`. Maps may
+override individual values; \`worklog: false\` on a role or in defaults opts out.
+Fleet rotates only at that role's launch/resume lifecycle boundary. Concurrent
+changes defer rotation. The active file keeps a bounded UTF-8 tail and advances
+to a line boundary when a complete line fits. If one logical line alone exceeds
+the budget, its newest suffix remains and the rotation manifest records the
+mid-line start and omitted byte count. The complete prior inode receives a
+collision-safe UTC archive name, and
+\`.worklog-rotation.json\` records restart provenance. \`max_archives\` bounds
+recent archives beside WORKLOG.md; older complete archives move to
+\`WORKLOG.archives/\` without deletion. All archives share the role's sensitive
+state boundary. Fleet refuses a symlinked/non-regular live log or a symlinked
+cold-archive boundary before replacing the live path and best-effort removes a
+duplicate publication left by a detected failure while the original inode is
+still available. The manifest records SHA-256 digests for the archive and live
+bytes observed when it is written. These checks address ordinary path hazards,
+not intentional path mutation by a malicious concurrent process with the same
+Unix authority; that is outside the threat model and requires OS-level isolation.
+
+ACP tool diffs are bounded before entering web conversation events. Existing
+small before/after diffs are unchanged. Oversized whole-file snapshots are
+reduced to the actual changed region plus path, operation, original byte counts,
+digest, and omission metadata. Each retained side is a newest-content UTF-8 tail
+of at most 64 KiB, advanced to a line boundary when a complete line fits. An
+overlong single line keeps its newest suffix and explicitly records a mid-line
+start. Paths retain at most a 4 KiB suffix with byte count, digest, and omitted
+prefix metadata; the complete normalized update is capped at 320 KiB. A large
+append therefore retains current appended content, not the historical prefix.
+The live web-console transcript includes only the current runner generation and
+excludes adapter session/load replay. Replayed events remain durable with
+agent_replay provenance for diagnosis and recovery.
 
 \`auth_proxy: { kind: anthropic, base_url, required, health_url }\` is Claude-only
 and loopback-only. Fleet injects only ANTHROPIC_BASE_URL and doctor rejects
@@ -694,7 +815,7 @@ fail-closed and held down. Change the declared chain/model and restart to
 reconcile explicitly; no chain preserves detection-only behavior.
 `;
 /**
- * What every shipped spawn-skill variant must say, and must not say (7.1).
+ * What every shipped spawn-skill variant must say, and must not say.
  *
  * The skills are separate markdown files in two published plugins, written for
  * two different harnesses, so they cannot literally be one file. This is the
@@ -724,7 +845,7 @@ export const SPAWN_SKILL_CONTRACT = {
         // The only intent that clears the floor, and the honest alternative.
         '--approval allow',
         '--unattended wait',
-        // Creation-time isolation (6.3) — the one new operator input this release adds.
+        // Creation-time isolation — the one new operator input this release adds.
         '--isolation-file',
     ],
     /**

package/dist/doctor.js

@@ -106,7 +106,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 ok: true,
                 detail: `warning: ${diagnostic.message}`,
             });
-    // ── Rooms/tasks checks (§5.3) ────────────────────────────────────────
+    // ── Rooms/tasks checks ────────────────────────────────────────
     if (loaded.ok && loaded.rooms) {
         const rooms = loaded.rooms;
         // Cowork socket reachability
@@ -183,7 +183,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                     : `cowork config not found: ${rooms.cowork.config}`,
             });
         }
-        // Hard prerelease capability check
+        // Hard room-management capability check
         try {
             const { createCoworkAdapter } = await import('./rooms-tasks/cowork-adapter.js');
             const adapter = createCoworkAdapter({ configPath: coworkConfig });
@@ -199,7 +199,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             checks.push({
                 name: 'rooms: capability', ok: false,
                 detail: isProto
-                    ? `cowork does not support room management protocol — upgrade ours-cowork to prerelease`
+                    ? `cowork does not support room management protocol — upgrade ours-cowork to a version that supports the room management protocol`
                     : `room management check failed: ${msg}`,
             });
         }
@@ -271,7 +271,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 : `no XDG_RUNTIME_DIR and /run/user/<uid> missing — systemctl --user cannot reach the user manager; enable linger: sudo loginctl enable-linger ${user}`,
         });
     }
-    // Per-role permission translation (2.3). Rendered from the same analysis the
+    // Per-role permission translation. Rendered from the same analysis the
     // `config` command prints, so the two commands cannot disagree.
     for (const analysis of analyzeFleetPermissions(roles)) {
         if (!analysis.supported) {
@@ -290,13 +290,13 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 ? `${summary} — ${analysis.warnings.join('; ')}`
                 : `${summary} (exact)`,
         });
-        // A role that states its permission intent twice, in two disagreeing places
-        // (2.4). Quiet when there is a single source of intent.
+        // Report a role that states its permission intent twice in disagreeing places.
+        // Stay quiet when there is a single source of intent.
         for (const conflict of analysis.conflicts ?? [])
             checks.push({
                 name: `permission conflict: ${analysis.role}`, ok: true, detail: conflict.warning,
             });
-        // The floor is checked BEFORE start (2.1): an under-permissioned unattended
+        // The floor is checked BEFORE start: an under-permissioned unattended
         // role never reports its own failure, because the denial happens inside the
         // harness with nobody attached to see it.
         const floor = analysis.floor;
@@ -342,7 +342,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         });
     }
     // Isolation reporting (AC-9). Backend availability is advisory — isolation is
-    // opt-in per role (OQ-1), so a missing bwrap must not fail doctor for fleets that
+    // opt-in per role, so a missing bwrap must not fail doctor for fleets that
     // don't use it. Only a role that DECLARES isolation and cannot get it under
     // `strict` is a hard failure.
     const bw = await makeBubblewrapBackend(exec).available();
@@ -355,7 +355,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     if (platform === 'linux')
         checks.push({ name: 'isolation: cgroup delegation', ok: true, detail: cgroupDelegationDetail() });
     for (const r of roles.filter(r => r.isolation)) {
-        // A refused mount is a launch-blocking policy error (5.2), not a warning.
+        // A refused mount is a launch-blocking policy error, not a warning.
         let policy;
         try {
             policy = resolveIsolation(r.isolation, isolationContextFor(r));
@@ -385,7 +385,7 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             detail = `backend=${policy.backend} (not yet implemented)`;
         checks.push({ name: `isolation: ${r.name}`, ok, detail });
     }
-    // Monitor daemon-API reachability (design §5): only when a role is supervised.
+    // Probe monitor daemon-API reachability only when a role is supervised.
     // /state-dir is unauthenticated (liveness); /identities exercises the token so a
     // shared-mode misconfig (401) surfaces here rather than as a silent deaf monitor.
     const monitorProfiles = resolveMonitorProfiles(roles);

package/dist/duration.js

@@ -1,4 +1,4 @@
-/** Parse `30s | 10m | 2h` duration strings to milliseconds (spec §2). */
+/** Parse `30s | 10m | 2h` duration strings to milliseconds. */
 const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
 const RE = /^(\d+)([smhd])$/;
 export function parseDuration(text, opts = {}) {

package/dist/fleet-proxy.d.ts

@@ -12,6 +12,11 @@ export interface ManagedFleetSpawnResult {
     session: 'tmux' | 'acp';
     model?: string;
     monitor: Pick<MonitorConfig, 'mode' | 'interrupt'>;
+    /** Adapter-resolved portable policy and exact native runtime mode. */
+    permissionMode?: {
+        fleetMode: 'ask' | 'auto' | 'allow';
+        nativeMode: string;
+    };
     inherited: string[];
     creationActionId: string;
 }

package/dist/harness/acp-agent.js

@@ -1,18 +1,23 @@
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 const require = createRequire(import.meta.url);
 export function resolveBundledAcpAgent(packageName, binName, fallbackCommand) {
     try {
         const manifestPath = require.resolve(`${packageName}/package.json`);
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-        const relative = typeof manifest.bin === 'string'
+        const declaredEntrypoint = typeof manifest.bin === 'string'
             ? manifest.bin
             : manifest.bin?.[binName];
-        if (!relative)
+        if (!declaredEntrypoint)
             return { argv: [fallbackCommand], bundled: false };
-        const entrypoint = resolve(dirname(manifestPath), relative);
-        if (!existsSync(entrypoint))
+        const packageRoot = realpathSync(dirname(manifestPath));
+        const entrypoint = realpathSync(resolve(packageRoot, declaredEntrypoint));
+        const entrypointFromRoot = relative(packageRoot, entrypoint);
+        if (entrypointFromRoot === '..'
+            || entrypointFromRoot.startsWith(`..${sep}`)
+            || isAbsolute(entrypointFromRoot)
+            || !statSync(entrypoint).isFile())
             return { argv: [fallbackCommand], bundled: false };
         return {
             argv: [process.execPath, entrypoint], bundled: true, manifestPath,

package/dist/harness/claude-code.js

@@ -6,8 +6,98 @@ import { registerAdapter } from './registry.js';
 import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
 import { harnessRuntimeDir } from '../isolation/policy.js';
 import { bundledAcpAgent } from './acp-agent.js';
-const OPTION_KEYS = ['plugins', 'mem_palace', 'mem_palace_midsession_autosave', 'permission_mode', 'effort'];
+const OPTION_KEYS = [
+    'plugins', 'mem_palace', 'mem_palace_midsession_autosave', 'permission_mode', 'effort',
+    'mcp_servers', 'mcp_servers_only',
+];
 const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+/** `.mcp.json` server types. Absent means stdio, as the file format has it. */
+const MCP_SERVER_TYPES = ['stdio', 'http', 'sse'];
+/** A role that names its own ACP command runs a process fleet did not choose. */
+const customAcpCommand = (role) => role.session === 'acp' && role.session_options?.acp?.command != null;
+/**
+ * Does this server set include the ours connector?
+ *
+ * Load-bearing, and the reason it is a check rather than a doc line:
+ * `mcp_servers_only` maps to `--strict-mcp-config`, which ignores EVERY other MCP
+ * configuration — project `.mcp.json`, user settings, and **plugins**. On a
+ * normal install the ours connector arrives as a plugin
+ * (`~/.claude/plugins/.../plugin.json` declares `ours`), so a role that turns
+ * strict mode on without re-declaring it loses `send_message` and `get_messages`
+ * and cannot report that it has: a mute agent looks exactly like a quiet one.
+ *
+ * Matched on the command line rather than the server's NAME, because the name is
+ * the operator's to choose and would make this trivially satisfiable by writing
+ * `ours:` above the wrong command.
+ */
+const declaresOursConnector = (servers) => Object.values(servers).some(s => [s.command ?? '', ...(s.args ?? [])].some(part => /(^|[/\\])ours-mcp($|\s)|@ours\.network[/\\]mcp/.test(part)));
+/** Shape-check `harness_options.mcp_servers` against `.mcp.json`'s own rules. */
+function validateMcpServers(servers) {
+    if (servers == null)
+        return [];
+    const at = (k = '') => ({ path: `harness_options.mcp_servers${k}` });
+    if (typeof servers !== 'object' || Array.isArray(servers))
+        return [{ ...at(), message: 'must be a map of server name to server definition' }];
+    const entries = Object.entries(servers);
+    if (!entries.length)
+        return [{ ...at(), message: 'must declare at least one server, or be omitted' }];
+    const errors = [];
+    for (const [name, raw] of entries) {
+        const p = `.${name}`;
+        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+            errors.push({ ...at(p), message: 'server name must be [A-Za-z0-9_-]' });
+            continue;
+        }
+        if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push({ ...at(p), message: 'must be a map' });
+            continue;
+        }
+        const s = raw;
+        if (s.type != null && !MCP_SERVER_TYPES.includes(s.type))
+            errors.push({ ...at(`${p}.type`), message: `must be one of: ${MCP_SERVER_TYPES.join(', ')}` });
+        const remote = s.type === 'http' || s.type === 'sse';
+        if (remote) {
+            if (typeof s.url !== 'string' || !s.url.trim())
+                errors.push({ ...at(`${p}.url`), message: `must be a non-empty URL for a ${s.type} server` });
+            if (s.command != null)
+                errors.push({ ...at(`${p}.command`), message: `must not be set for a ${s.type} server` });
+        }
+        else {
+            if (typeof s.command !== 'string' || !s.command.trim())
+                errors.push({ ...at(`${p}.command`), message: 'must be a non-empty command for a stdio server' });
+            if (s.args != null && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string')))
+                errors.push({ ...at(`${p}.args`), message: 'must be an array of strings' });
+            if (s.url != null)
+                errors.push({ ...at(`${p}.url`), message: 'must not be set for a stdio server' });
+        }
+        for (const key of ['env', 'headers']) {
+            const v = s[key];
+            if (v == null)
+                continue;
+            if (typeof v !== 'object' || Array.isArray(v)
+                || Object.values(v).some(x => typeof x !== 'string'))
+                errors.push({ ...at(`${p}.${key}`), message: 'must be a map of string to string' });
+        }
+    }
+    return errors;
+}
+/** `harness_options.mcp_servers` in ACP's `session/new` array shape. */
+function acpMcpServersFor(servers) {
+    if (!servers)
+        return [];
+    // `env` and `headers` are REQUIRED arrays in the protocol, so they are always
+    // sent — empty when the role declared none.
+    const pairs = (r) => Object.entries(r ?? {}).map(([name, value]) => ({ name, value }));
+    return Object.entries(servers).map(([name, s]) => {
+        if (s.type === 'http' || s.type === 'sse')
+            return { name, type: s.type, url: s.url, headers: pairs(s.headers) };
+        // Stdio carries NO `type` field: ACP's stdio variant is the one without it,
+        // and the bundled agent keys on exactly that (claude-agent-acp
+        // acp-agent.js:4058, `!("type" in server)`), so sending `type: 'stdio'`
+        // would drop the server on the floor.
+        return { name, command: s.command, args: s.args ?? [], env: pairs(s.env) };
+    });
+}
 /** Claude Code's accepted --permission-mode values. */
 const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPermissions'];
 /**
@@ -149,7 +239,7 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     }],
             };
         },
-        validateOptions(opts) {
+        validateOptions(opts, role) {
             if (opts == null)
                 return [];
             if (typeof opts !== 'object' || Array.isArray(opts))
@@ -157,9 +247,44 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             const errors = Object.keys(opts)
                 .filter(k => !OPTION_KEYS.includes(k))
                 .map(k => ({ path: `harness_options.${k}`, message: `unknown option; allowed: ${OPTION_KEYS.join(', ')}` }));
-            const effort = opts.effort;
+            const o = opts;
+            const effort = o.effort;
             if (effort != null && !EFFORT_LEVELS.includes(effort))
                 errors.push({ path: 'harness_options.effort', message: `must be one of: ${EFFORT_LEVELS.join(', ')}` });
+            if (o.mcp_servers_only != null && typeof o.mcp_servers_only !== 'boolean')
+                errors.push({ path: 'harness_options.mcp_servers_only', message: 'must be a boolean' });
+            errors.push(...validateMcpServers(o.mcp_servers));
+            if (o.mcp_servers_only === true && !o.mcp_servers)
+                errors.push({
+                    path: 'harness_options.mcp_servers_only',
+                    message: 'requires harness_options.mcp_servers; on its own it would leave the role with no MCP servers at all',
+                });
+            // The muteness gate. Only when the declared set is otherwise well-formed —
+            // a shape error already told the operator to look here.
+            if (o.mcp_servers_only === true && o.mcp_servers && errors.length === 0
+                && !declaresOursConnector(o.mcp_servers))
+                errors.push({
+                    path: 'harness_options.mcp_servers',
+                    message: 'mcp_servers_only ignores every other MCP configuration, INCLUDING plugins — and the ours '
+                        + 'connector is normally a plugin, so this role would have no send_message or get_messages and no way '
+                        + 'to report that. Declare it explicitly, e.g. ours: { command: ours-mcp, args: [proxy] }',
+                });
+            // Session-aware refusals. Both options reach an ACP session through the
+            // bundled agent's `_meta` vocabulary, so a role that launches a DIFFERENT
+            // ACP agent cannot be promised either one. Refuse rather than send it and
+            // hope: silently dropping the config is the defect being fixed here.
+            if (role && customAcpCommand(role)) {
+                for (const key of ['plugins', 'mcp_servers', 'mcp_servers_only']) {
+                    if (o[key] == null)
+                        continue;
+                    errors.push({
+                        path: `harness_options.${key}`,
+                        message: 'cannot be honoured with session_options.acp.command: it is delivered through the bundled '
+                            + 'Claude ACP agent\'s _meta vocabulary, which another agent has no reason to read. Drop the '
+                            + 'custom ACP command, or drop this option',
+                    });
+                }
+            }
             return errors;
         },
         async prepareSession(role, dirs) {
@@ -178,22 +303,48 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: String(autocompactPct(role)),
                 MEMPALACE_HOOKS_AUTO_SAVE: 'false',
                 MEMPALACE_MIDSESSION_AUTOSAVE: o.mem_palace_midsession_autosave ? 'true' : 'false',
+                // The role's identity, for the ours connector to bind at startup instead of
+                // the briefing telling the MODEL to call choose_identity. Both launches
+                // return `prep.env`, so this one line covers tmux and ACP alike.
+                //
+                // The bind the connector performs is PLAIN and fail-closed: it can never
+                // evict a live session, and a role whose identity does not exist yet simply
+                // boots unbound and falls through to the briefing's create-if-missing step.
+                // Nothing here may ever grow a force flag.
+                OURS_BIND_IDENTITY: role.identity,
             };
             if (!memPalace)
                 env.MEMPALACE_DISABLED = 'true';
-            // Per-role harness runtime home (5.1). Created before sandbox entry so the
+            // Per-role harness runtime home. Created before sandbox entry so the
             // bind has something to mount; harmless for un-isolated roles.
             // Only a role that declares `isolation:` gets a sandbox, and only a
             // sandbox needs this directory to exist before entry.
             if (role.isolation)
                 mkdirSync(harnessRuntimeDir(dirs.stateDir, 'claude'), { recursive: true });
             const argv = [];
+            let settingsOverlay;
             if (Object.keys(enabledPlugins).length) {
-                const overlay = join(dirs.stateDir, '.settings-overlay.json');
-                writeFileSync(overlay, JSON.stringify({ enabledPlugins }, null, 2));
-                argv.push('--settings', overlay);
+                settingsOverlay = join(dirs.stateDir, '.settings-overlay.json');
+                writeFileSync(settingsOverlay, JSON.stringify({ enabledPlugins }, null, 2));
+                argv.push('--settings', settingsOverlay);
             }
-            return { argv, env };
+            // `harness_options.mcp_servers` — the tmux delivery. `--mcp-config` ADDS the
+            // file's servers; `--strict-mcp-config` is what makes the set exclusive, and
+            // it is opt-in per role because it drops everything else the user has,
+            // plugins included (see `declaresOursConnector`).
+            let mcpConfigFile;
+            if (o.mcp_servers) {
+                mcpConfigFile = join(dirs.stateDir, '.mcp-config.json');
+                writeFileSync(mcpConfigFile, JSON.stringify({ mcpServers: o.mcp_servers }, null, 2), { mode: 0o600 });
+                argv.push('--mcp-config', mcpConfigFile);
+                if (o.mcp_servers_only === true)
+                    argv.push('--strict-mcp-config');
+            }
+            return {
+                argv, env,
+                ...(settingsOverlay ? { settingsOverlay } : {}),
+                ...(mcpConfigFile ? { mcpConfigFile } : {}),
+            };
         },
         buildLaunch(role, mode, s, prep) {
             const stateDir = roleStateDir(role);
@@ -223,6 +374,46 @@ export function makeClaudeCodeAdapter(exec = realExec) {
         acpPermissionModeId(role) {
             return permissionMode(role);
         },
+        /**
+         * Deliver, over ACP, the two things the tmux launch delivers as flags.
+         *
+         * `buildAcpLaunch` builds its own argv and cannot carry `prep.argv`: the
+         * process it launches is the ACP agent, not `claude`, and it takes none of
+         * claude's flags. That is why `harness_options.plugins` did nothing at all on
+         * an ACP role — the overlay was written and then dropped, and the mem-palace
+         * toggle rode `prep.env` and survived, so the failure was silent AND
+         * selective.
+         *
+         * `_meta.claudeCode.options` is the bundled agent's own passthrough into the
+         * Claude Agent SDK (@agentclientprotocol/claude-agent-acp, acp-agent.js:4092
+         * → the `options` object at :4144). `settings` takes the same overlay path
+         * `--settings` takes; `strictMcpConfig` is the SDK's spelling of
+         * `--strict-mcp-config`. Both are spread BEFORE the fields the agent forces,
+         * so neither is overwritten.
+         *
+         * ⚠ RETURNS NOTHING FOR A ROLE THAT NAMES ITS OWN ACP COMMAND. That process
+         * is not the bundled agent and has no reason to read this vocabulary; sending
+         * it anyway would be the silent drop again, one level down. `validateOptions`
+         * refuses those roles instead.
+         */
+        acpSessionMeta(role, prep) {
+            if (customAcpCommand(role))
+                return undefined;
+            const options = {};
+            if (prep.settingsOverlay)
+                options.settings = prep.settingsOverlay;
+            if (role.harness_options?.mcp_servers_only === true)
+                options.strictMcpConfig = true;
+            return Object.keys(options).length ? { claudeCode: { options } } : undefined;
+        },
+        /**
+         * The declared servers, in ACP's array shape. Sent on `session/new` and on
+         * resume/load, because the SDK builds its server set once per session and a
+         * resumed session that dropped them would quietly lose its tools.
+         */
+        acpMcpServers(role) {
+            return acpMcpServersFor(role.harness_options?.mcp_servers);
+        },
         isolationPaths(_role, _dirs) {
             const claudeHome = join(home(), '.claude');
             return {
@@ -285,6 +476,8 @@ export function makeClaudeCodeAdapter(exec = realExec) {
             currentIdentityTool: 'current_identity',
             sendTool: 'send_message',
             getMessagesTool: 'get_messages',
+            listHistoryTool: 'list_history',
+            getHistoryItemTool: 'get_history_item',
             monitorInstruction: id => {
                 const m = armMonitor(id);
                 return `${m.charAt(0).toUpperCase()}${m.slice(1)}.`;

package/dist/harness/codex.d.ts

@@ -1,10 +1,13 @@
 import { type Exec } from '../exec.js';
-import type { HarnessAdapter, UnattendedCapability } from './types.js';
+import type { AcpLaunch, HarnessAdapter, UnattendedCapability } from './types.js';
+import { type AcpAgentResolution } from './acp-agent.js';
 /**
  * What an unattended role can actually do under Codex's native settings.
  * `on-request` and `untrusted` stop to ask, and with no console attached that
  * request is refused rather than answered — so the role can only read.
  */
 export declare function codexCapabilities(approval: string, sandbox: string): UnattendedCapability[];
+/** Bind launch argv and metadata provenance to one already-completed resolution. */
+export declare function codexAcpLaunchForResolution(resolution: AcpAgentResolution): Pick<AcpLaunch, 'argv' | 'permissionMetadataSource'>;
 export declare function makeCodexAdapter(exec?: Exec): HarnessAdapter;
 export declare const codexAdapter: HarnessAdapter;