@commonlyai/cli 0.1.88 → 0.1.92

package/src/lib/daemon-supervisor.js

@@ -1,7 +1,10 @@
 import { isDeepStrictEqual } from 'node:util';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve as pathResolve } from 'node:path';
-import { auditDeclaredMcp, installedStdioEntries } from './declared-mcp-guard.js';
+import {
+  auditDeclaredMcp,
+  installedStdioEntries,
+} from './declared-mcp-guard.js';
 
 import { seatBaseline } from './default-environment.js';
 import { withholdGrantBroker } from './grant-broker-guard.js';
@@ -150,20 +153,28 @@ export const createDaemonSupervisor = ({
     return Object.keys(fallback).length ? { value: fallback, declared: false } : null;
   };
 
+  // `provider` is host-local authority: /assigned intentionally omits it.
+  // Ignore a provider field even if a future or malformed row carries one,
+  // then restore only the local token record's value during adoption.
+  const withoutServerProvider = (environment) => {
+    const safe = { ...(environment || {}) };
+    delete safe.provider;
+    return safe;
+  };
+
   // A declared environment runs on THIS machine as the operator. Refuse any
   // declared stdio command that is not the shipped commonly MCP server or one
-  // the operator already installed here, and any http server that would be
-  // handed the seat token off the instance's origin. Refusal keeps the current
-  // seat (or skips the mint) and says which server was kept off the machine;
-  // it never adopts a partial environment.
+  // the operator already installed here, and any http server that would
+  // receive the seat token off-origin. Provider blocks are ignored from rows;
+  // the host-local token record is their only source.
   const admitDeclared = (row, environment, existing) => {
-    const audit = auditDeclaredMcp(environment, {
+    const mcpAudit = auditDeclaredMcp(environment, {
       instanceUrl: existing?.instanceUrl || record.instanceUrl,
       allowedStdioEntries: installedStdioEntries(existing),
     });
-    if (audit.ok) return true;
+    if (mcpAudit.refusals.length === 0) return true;
     log(`[${row.agentName}] refusing the declared environment — it would not stay on this machine's terms:`);
-    for (const refusal of audit.refusals) log(`[${row.agentName}]   ${refusal}`);
+    for (const refusal of mcpAudit.refusals) log(`[${row.agentName}]   ${refusal}`);
     return false;
   };
 
@@ -222,10 +233,21 @@ export const createDaemonSupervisor = ({
         nextAdapter = declaredAdapter;
         adapterChanged = existing.adapter !== nextAdapter;
       }
+      if (existing.environment?.provider && nextAdapter !== 'opencode') {
+        log(`[${row.agentName}] host-local provider requires the opencode adapter — keeping the current seat`);
+        return false;
+      }
       if (wanted) {
+        const serverEnvironment = withoutServerProvider(wanted.value);
         const merged = wanted.declared
-          ? wanted.value
-          : { ...(existing.environment || {}), ...wanted.value };
+          ? serverEnvironment
+          : { ...(existing.environment || {}), ...serverEnvironment };
+        // The provider chooses a network endpoint and reads a host key file,
+        // so it is authored on this host. /assigned omits it; rehydrate the
+        // local block after applying the server's declared environment.
+        if (existing.environment?.provider) {
+          merged.provider = existing.environment.provider;
+        }
         // A server-declared environment replaces the local one, so a seat whose
         // declaration carries no mcp[] would come back tool-less. Re-apply the
         // shipped default here and below, or the seat silently loses every
@@ -325,7 +347,7 @@ export const createDaemonSupervisor = ({
     }
     if (!adapter) adapter = await resolveAdapter(row.runtime || null);
     if (!adapter) {
-      log(`[${row.agentName}] no usable CLI adapter on this machine — install claude or codex, or attach manually`);
+      log(`[${row.agentName}] no usable CLI adapter on this machine — install claude, codex, or opencode, or attach manually`);
       return false;
     }
     const environment = environmentFor(row);
@@ -335,7 +357,7 @@ export const createDaemonSupervisor = ({
     // operator-authored, so this seat also gets the sandbox default — the
     // self-serve install's seat used to be born unconfined (TASK-052).
     const recordEnvironment = derive(
-      environment ? environment.value : null,
+      environment ? withoutServerProvider(environment.value) : null,
       adapter,
       { sandbox: true },
     );

package/src/lib/declared-mcp-guard.js

@@ -1,5 +1,5 @@
 /**
- * Guard for a server-declared `environment.mcp` before the daemon adopts it.
+ * Guard server-declared `environment.mcp` before the daemon adopts it.
  *
  * The daemon projects `AgentInstallation.config.environment` onto the OWNER's
  * machine: every declared stdio server is spawned as the operator, and every

package/src/lib/default-environment.js

@@ -16,6 +16,7 @@
  *            codex agent posted through the operator's own CLI profile because
  *            it had no commonly_* tool of its own)
  *   pi     — stdio servers from the environment spec (adapters/pi.js)
+ *   opencode — per-spawn config file with local/remote MCP entries (adapters/opencode.js)
  * `stub` has no consumption path and must keep being handed `environment: null`.
  *
  * The placeholders are substituted at spawn time by the adapter, so the
@@ -24,7 +25,7 @@
 
 import { normalizeSandboxTrust } from './environment.js';
 
-export const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi']);
+export const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi', 'opencode']);
 
 /**
  * The adapters that can ENFORCE the default sandbox — a strict subset of the
@@ -41,7 +42,12 @@ export const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi']);
  * here and hoped for. A derived pi seat used to be exactly this shape and would
  * have failed every spawn with `public-trust seats are not supported`.
  */
-export const ADAPTERS_WITH_DEFAULT_SANDBOX = new Set(['claude', 'codex']);
+export const ADAPTERS_WITH_DEFAULT_SANDBOX = new Set(['claude', 'codex', 'opencode']);
+
+// The server has not yet admitted OpenCode to its grant-broker confinement
+// allowlist. Keep runtime sandbox support separate from the narrower set of
+// adapters that may receive a room grant.
+export const ADAPTERS_WITH_GRANT_BROKER = new Set(['claude', 'codex']);
 
 /**
  * The sandbox an unconfigured seat gets.
@@ -64,9 +70,11 @@ export const ADAPTERS_WITH_DEFAULT_SANDBOX = new Set(['claude', 'codex']);
  * moves a host fact into the database and breaks the day the seat is re-homed.
  * An explicit mode in a record still wins over the derived one.
  *
- * Confinement holds for claude and codex, and only they are ever handed this
- * block (ADAPTERS_WITH_DEFAULT_SANDBOX). A pi seat must never be: it fails
- * closed on a declared sandbox rather than run under a spec it cannot honour.
+ * Confinement holds for claude, codex, and opencode, and only they are handed
+ * this block (ADAPTERS_WITH_DEFAULT_SANDBOX). Grant-broker eligibility is
+ * narrower until the server admits OpenCode after its confinement proof.
+ * A pi seat must never be handed this block: it fails closed on a declared
+ * sandbox rather than run under a spec it cannot honour.
  */
 export const COMMONLY_DEFAULT_SANDBOX = Object.freeze({ trust: 'public' });
 

package/src/lib/enforcement.js

@@ -687,6 +687,41 @@ export const deliverChatReply = async ({
       ? { consecutive: response.consecutive }
       : {}),
   });
+  // The same route also answers HTTP 200 with `{ success: true, skipped: true,
+  // reason }` when it decided not to create a row: a duplicate inside the dedupe
+  // window, a silent or empty body, a heartbeat it keeps to itself. The wrapper
+  // used to read that as a delivery and log "posted … (single)" while nothing
+  // reached the pod (hq-support, 2026-10-09 08:10Z), so a silent seat could not
+  // be read from its own log. A skip is a completed request and not a delivery,
+  // exactly like a refusal, and it stops a sequence the same way.
+  const skipped = (response, messages, attemptedMessages) => {
+    const duplicate = response.duplicate && typeof response.duplicate === 'object'
+      ? response.duplicate
+      : null;
+    return {
+      mode: 'skipped',
+      messages,
+      attemptedMessages,
+      skipped: true,
+      reason: response.reason || 'message_skipped',
+      ...(duplicate
+        ? {
+          duplicate: {
+            ...(duplicate.id ? { id: String(duplicate.id) } : {}),
+            ...(typeof duplicate.dedupeWindowMinutes === 'number'
+              ? { dedupeWindowMinutes: duplicate.dedupeWindowMinutes }
+              : {}),
+          },
+        }
+        : {}),
+    };
+  };
+  const undelivered = (response) => response?.refused === true || response?.skipped === true;
+  const nonDelivery = (response, messages, attemptedMessages) => (
+    response?.refused === true
+      ? refused(response, messages, attemptedMessages)
+      : skipped(response, messages, attemptedMessages)
+  );
   // An atomic unit (a fenced block, an unbreakable word-run) can exceed the
   // limit by construction — splitForChat keeps it whole rather than breaking
   // its rendering. The tone contract's own rule covers it: over ~800 chars of
@@ -696,7 +731,7 @@ export const deliverChatReply = async ({
   const hasIndivisibleOversize = chunks.some((c) => c.length > attachThreshold);
   if (chunks.length <= 1 && !hasIndivisibleOversize) {
     const response = await postMessage({ content: chunks[0] ?? text });
-    if (response?.refused === true) return refused(response, 0, 1);
+    if (undelivered(response)) return nonDelivery(response, 0, 1);
     return { mode: 'single', messages: 1 };
   }
   if (chunks.length <= maxChunks && !hasIndivisibleOversize) {
@@ -704,7 +739,7 @@ export const deliverChatReply = async ({
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
       const response = await postMessage({ content: chunk }); // in order, so the reply reads top-down
-      if (response?.refused === true) return refused(response, messages, chunks.length);
+      if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
       messages += 1;
     }
     return { mode: 'split', messages };
@@ -724,7 +759,7 @@ export const deliverChatReply = async ({
     let posted = 0;
     try {
       const rootRes = await postMessage({ content: chunks[0] });
-      if (rootRes?.refused === true) return refused(rootRes, 0, chunks.length);
+      if (undelivered(rootRes)) return nonDelivery(rootRes, 0, chunks.length);
       posted = 1;
       // The runtime route answers `res.json(result)` with the created row on
       // `result.message`. Accept either id field; refuse to guess if neither
@@ -736,7 +771,7 @@ export const deliverChatReply = async ({
       for (const chunk of chunks.slice(1)) {
         // eslint-disable-next-line no-await-in-loop
         const response = await postMessage({ content: chunk, threadRootId: String(rootId) });
-        if (response?.refused === true) return refused(response, posted, chunks.length);
+        if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
         posted += 1;
       }
       return { mode: 'thread', messages: chunks.length, threadRootId: String(rootId) };
@@ -751,7 +786,7 @@ export const deliverChatReply = async ({
         for (const chunk of chunks.slice(posted)) {
           // eslint-disable-next-line no-await-in-loop
           const response = await postMessage({ content: chunk });
-          if (response?.refused === true) return refused(response, posted, chunks.length);
+          if (undelivered(response)) return nonDelivery(response, posted, chunks.length);
           posted += 1;
         }
         return { mode: 'thread-fallback', messages: chunks.length };
@@ -777,7 +812,7 @@ export const deliverChatReply = async ({
       ? chunks[0]
       : '(reply too large for chat — attached in full)';
     const response = await postMessage({ content: `${lead}\n\n${directive}` });
-    if (response?.refused === true) return refused(response, 0, 1);
+    if (undelivered(response)) return nonDelivery(response, 0, 1);
     return { mode: 'attach', messages: 1 };
   } catch (err) {
     log(`attach fallback failed (${err.message}) — posting ${chunks.length} split messages instead`);
@@ -785,7 +820,7 @@ export const deliverChatReply = async ({
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
       const response = await postMessage({ content: chunk });
-      if (response?.refused === true) return refused(response, messages, chunks.length);
+      if (undelivered(response)) return nonDelivery(response, messages, chunks.length);
       messages += 1;
     }
     return { mode: 'split-fallback', messages };

package/src/lib/environment.js

@@ -41,13 +41,26 @@ import { homedir } from 'os';
 // "persona and runtime are chosen separately" requires to mean anything for a
 // BYO seat, and what lets an identity card answer "what is this running".
 const ALLOWED_TOP_KEYS = new Set([
-  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model', 'effort',
+  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model', 'effort', 'provider',
 ]);
 const ALLOWED_SANDBOX_MODES = new Set([
   'none', 'workspace', 'read-only', 'bwrap', 'firejail', 'container', 'managed',
 ]);
 const ALLOWED_SANDBOX_TRUST = new Set(['public']);
 const ALLOWED_NETWORK_POLICIES = new Set(['unrestricted', 'restricted']);
+const INLINE_PROVIDER_CREDENTIAL_FIELD = /(?:key|token|secret|password|authorization|header|credential|auth)/i;
+
+const findInlineProviderCredentialField = (value, path) => {
+  if (!value || typeof value !== 'object') return null;
+  for (const [key, nested] of Object.entries(value)) {
+    const normalized = key.replace(/[-_]/g, '').toLowerCase();
+    const fieldPath = `${path}.${key}`;
+    if (INLINE_PROVIDER_CREDENTIAL_FIELD.test(normalized)) return fieldPath;
+    const nestedPath = findInlineProviderCredentialField(nested, fieldPath);
+    if (nestedPath) return nestedPath;
+  }
+  return null;
+};
 
 // `trust: 'internal'` was accepted by this schema and read by NO adapter. On the
 // attach path it could only name a mode the platform cannot resolve; on the
@@ -136,11 +149,24 @@ export const parseEnvironmentFile = async (absolutePath) => {
   // annotations. The caller is responsible for tracking envFileDir separately
   // (compute via `dirname(envPath)`) and passing it explicitly to
   // resolveWorkspace / mountSkills when relative paths in the spec need to
-  // resolve. This keeps the spec safe to serialize and ship to the backend
-  // (`config.environment` on AgentInstallation) without leaking $HOME layout.
+  // resolve. The provider block is host-local; API writers omit it entirely.
   return parsed;
 };
 
+/**
+ * Remove the host-local provider declaration before an environment spec is
+ * sent to the Commonly API. The full spec remains in the local token record so
+ * the daemon can bind it to this host and the adapter can resolve its key file.
+ */
+export const environmentForServer = (environment) => {
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)
+    || !Object.prototype.hasOwnProperty.call(environment, 'provider')) {
+    return environment;
+  }
+  const { provider: _hostLocalProvider, ...serverEnvironment } = environment;
+  return serverEnvironment;
+};
+
 // ── validateEnvironmentSpec ─────────────────────────────────────────────────
 
 export const validateEnvironmentSpec = (spec) => {
@@ -172,6 +198,70 @@ export const validateEnvironmentSpec = (spec) => {
     }
   }
 
+  if (spec.provider !== undefined) {
+    if (!spec.provider || typeof spec.provider !== 'object' || Array.isArray(spec.provider)) {
+      errors.push('provider must be an object');
+    } else {
+      const allowedProviderKeys = new Set(['id', 'baseURL', 'keyFile', 'models']);
+      for (const key of Object.keys(spec.provider)) {
+        if (!allowedProviderKeys.has(key)) {
+          errors.push(`unknown provider key: ${JSON.stringify(key)} (allowed: id, baseURL, keyFile, models)`);
+        }
+      }
+      const { id, baseURL, keyFile, models } = spec.provider;
+      if (typeof id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(id)) {
+        errors.push('provider.id must be a safe OpenCode provider id');
+      }
+      if (typeof baseURL !== 'string' || baseURL.trim() === '') {
+        errors.push('provider.baseURL must be an HTTP(S) URL');
+      } else {
+        try {
+          const url = new URL(baseURL);
+          if (!['http:', 'https:'].includes(url.protocol)
+            || !url.hostname
+            || url.username || url.password || url.search || url.hash) {
+            errors.push('provider.baseURL must be an HTTP(S) URL without credentials, query, or fragment');
+          }
+        } catch {
+          errors.push('provider.baseURL must be an HTTP(S) URL');
+        }
+      }
+      if (typeof keyFile !== 'string' || !isAbsolute(keyFile)) {
+        errors.push('provider.keyFile must be an absolute path');
+      } else if (/[\r\n}]/.test(keyFile)) {
+        errors.push('provider.keyFile contains characters that cannot be used in an OpenCode file reference');
+      }
+      if (models !== undefined) {
+        if (!models || typeof models !== 'object' || Array.isArray(models)) {
+          errors.push('provider.models must be an object keyed by bare model id');
+        } else {
+          for (const [modelId, modelConfig] of Object.entries(models)) {
+            if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(modelId)) {
+              errors.push(`provider.models key ${JSON.stringify(modelId)} must be a bare model id`);
+            }
+            if (!modelConfig || typeof modelConfig !== 'object' || Array.isArray(modelConfig)) {
+              errors.push(`provider.models[${JSON.stringify(modelId)}] must be an object`);
+            } else {
+              const credentialField = findInlineProviderCredentialField(
+                modelConfig,
+                `provider.models.${modelId}`,
+              );
+              if (credentialField) {
+                errors.push(`${credentialField} must not contain inline credentials; use provider.keyFile`);
+              }
+            }
+          }
+        }
+      }
+      if (spec.model === undefined) {
+        errors.push('model is required when provider is configured');
+      } else if (typeof spec.model === 'string'
+        && !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(spec.model)) {
+        errors.push('model must be a bare model id when provider is configured');
+      }
+    }
+  }
+
   // `effort` is the reasoning budget the claude adapter passes to `--effort`.
   // Unlike `model` it IS a closed set — the CLI documents exactly these — so a
   // typo fails here at attach time, not silently at the first spawn.

package/src/lib/grant-broker-guard.js

@@ -16,11 +16,11 @@
  * never reaches (a row naming no adapter, a backend older than the refusal, a
  * hand-written token file). Both halves emit the same `code`.
  *
- * THE ADAPTER IS THE HOST-INDEPENDENT FACT, so the set of adapters this daemon
- * can confine is the set that derives an enforced sandbox — `claude` and
- * `codex` (`ADAPTERS_WITH_DEFAULT_SANDBOX`, imported rather than retyped).
- * Anything else, `pi` included, confines on no host: `pi` refuses a declared
- * sandbox rather than honouring it, so an undeclared one is never derived.
+ * THE ADAPTER IS THE HOST-INDEPENDENT FACT, but sandbox support and broker
+ * admission are separate. OpenCode enforces a public sandbox locally; until
+ * the server allowlist admits its proven modes, only `claude` and `codex` may
+ * receive the grant broker. `pi` is also withheld because it refuses a declared
+ * sandbox rather than honouring it.
  *
  * ONE REASON THE SERVER DOES NOT HAVE: `sandbox_absent`. The server must ALLOW
  * an absent block (a daemon-provisioned seat's baseline is derived here and is
@@ -73,7 +73,7 @@
  * a foreign server cannot be drawn in by its spelling.
  */
 import { isGrantBrokerUrl } from './adapters/pi-mcp-client.mjs';
-import { ADAPTERS_WITH_DEFAULT_SANDBOX } from './default-environment.js';
+import { ADAPTERS_WITH_GRANT_BROKER } from './default-environment.js';
 import { effectiveSandboxTrust } from './environment.js';
 import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from './sandbox/mode.js';
 
@@ -177,7 +177,7 @@ export const declaresGrantBroker = (environment, opts) => (
  * The reason vocabulary mirrors the server's, plus `sandbox_absent`.
  */
 export const confinementReason = (environment, adapter, platform = process.platform) => {
-  if (!ADAPTERS_WITH_DEFAULT_SANDBOX.has(adapter)) return 'adapter_cannot_confine';
+  if (!ADAPTERS_WITH_GRANT_BROKER.has(adapter)) return 'adapter_cannot_confine';
 
   const sandbox = environment?.sandbox;
   if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return 'sandbox_absent';
@@ -192,8 +192,8 @@ export const confinementReason = (environment, adapter, platform = process.platf
 const detailFor = (reason, adapter, environment) => {
   const drop = 'or drop the grant broker from this seat';
   if (reason === 'adapter_cannot_confine') {
-    return `the seat runs the '${adapter || 'unresolved'}' adapter, which confines on no host — a declared sandbox is`
-      + ' refused rather than enforced, and an absent one is never derived; move this seat to the claude or codex'
+    return `the seat runs the '${adapter || 'unresolved'}' adapter, which is not approved to receive the grant broker;`
+      + ' move this seat to the claude or codex'
       + ` adapter, ${drop}`;
   }
   if (reason === 'sandbox_absent') {

package/src/lib/sandbox/seatbelt.js

@@ -1,20 +1,20 @@
 /**
- * macOS Seatbelt wrapper for public Claude Code agents.
+ * macOS Seatbelt wrapper for public local-CLI agents.
  *
  * `sandbox-exec` is deprecated as a public API, but remains the host-native
  * kernel boundary available to local CLI wrappers on current macOS. This
- * profile starts from deny-by-default, admits only the system runtime Claude
+ * profile starts from deny-by-default, admits only the system runtime the CLI
  * needs, and then grants explicit access to:
- *   - the selected Claude executable,
+ *   - the selected CLI executable,
  *   - one workspace (read/write or read-only),
- *   - one isolated, token-free Claude state directory, and
+ *   - one isolated state directory, and
  *   - the adapter-owned transient MCP config directory (read-only).
  *
  * The static platform baseline is adapted from OpenAI Codex's Apache-2.0
  * Seatbelt policy:
  * https://github.com/openai/codex/tree/main/codex-rs/sandboxing/src
  *
- * Public Claude still needs outbound network access for the Anthropic API and
+ * Public seats still need outbound network access for their provider API and
  * declared MCP transports. Host confidentiality therefore comes from the
  * filesystem boundary, not a claim that all network syscalls are disabled.
  */
@@ -132,13 +132,11 @@ const PLATFORM_BASELINE = String.raw`
 (allow file-read-metadata (subpath "/var"))
 (allow file-read-metadata (subpath "/private/var"))
 
-; The native Claude binary and declared MCP launchers may execute children.
-; Claude bootstraps stdio MCP servers through /bin/sh, whose interpreter is
-; /bin/bash on current macOS. An executable-level shell deny would therefore
-; disable the declared capability too. The built-in Bash tool is denied in
-; Claude argv; any trusted child that does run inherits this same Seatbelt
-; profile, so host-secret reads and out-of-workspace writes remain kernel
-; denied.
+; The wrapper and declared MCP launchers may execute children. Claude
+; bootstraps stdio MCP servers through /bin/sh, whose interpreter is /bin/bash
+; on current macOS. An executable-level shell deny would therefore disable
+; declared MCP capability too. Each adapter denies its built-in shell tool in
+; its own config; any declared child inherits this Seatbelt profile.
 
 (allow file-read-data file-read-metadata (subpath "/bin"))
 (allow file-read-data file-read-metadata (subpath "/sbin"))
@@ -264,7 +262,7 @@ const PLATFORM_BASELINE = String.raw`
   (local-name "com.apple.cfprefsd.agent"))
 (allow user-preference-read)
 
-; Claude itself and declared MCP transports need outbound network. The model's
+; The selected provider and declared MCP transports need outbound network. The model's
 ; WebSearch/WebFetch/Bash tools are denied independently in the adapter argv.
 (allow network-outbound)
 (allow system-socket
@@ -329,29 +327,39 @@ export const detectSeatbelt = () => {
 export const buildSeatbeltProfile = ({
   workspacePath,
   workspaceAccess = 'write',
-  claudePath,
+  executablePath,
   statePath,
   mcpConfigDir = null,
   executablePaths = [],
+  readOnlyPaths = [],
+  loopbackNetworkPorts = [],
+  allowClaudeRuntimeAccess = false,
 }) => {
   for (const [path, label] of [
     [workspacePath, 'workspacePath'],
-    [claudePath, 'claudePath'],
+    [executablePath, 'executablePath'],
     [statePath, 'statePath'],
   ]) {
     assertAbsolutePath(path, label);
   }
   if (mcpConfigDir) assertAbsolutePath(mcpConfigDir, 'mcpConfigDir');
+  for (const path of readOnlyPaths) assertAbsolutePath(path, 'readOnlyPaths entry');
+  for (const port of loopbackNetworkPorts) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error('Seatbelt loopbackNetworkPorts entries must be valid TCP ports');
+    }
+  }
   if (!['read', 'write'].includes(workspaceAccess)) {
     throw new Error('Seatbelt workspaceAccess must be read or write');
   }
 
   const resolvedWorkspace = realpathOrSelf(workspacePath);
-  const resolvedClaude = realpathOrSelf(claudePath);
+  const resolvedExecutable = realpathOrSelf(executablePath);
   const resolvedState = realpathOrSelf(statePath);
   const resolvedMcpConfig = mcpConfigDir ? realpathOrSelf(mcpConfigDir) : null;
+  const resolvedReadOnlyPaths = [...new Set(readOnlyPaths.map(realpathOrSelf))];
   const executables = [...new Set(
-    [resolvedClaude, process.execPath, ...executablePaths]
+    [resolvedExecutable, process.execPath, ...executablePaths]
       .filter(Boolean)
       .map(realpathOrSelf),
   )];
@@ -369,9 +377,27 @@ export const buildSeatbeltProfile = ({
   const mcpRule = resolvedMcpConfig
     ? `(allow file-read* file-test-existence ${subpath(resolvedMcpConfig)})`
     : '';
-  const claudeTmp = `/private/tmp/claude-${typeof process.getuid === 'function' ? process.getuid() : '0'}`;
-  const userKeychains = join(homedir(), 'Library', 'Keychains');
-  const textEncoding = join(homedir(), '.CFUserTextEncoding');
+  const readOnlyRules = resolvedReadOnlyPaths.map((path) => (
+    `(allow file-read* file-test-existence ${literal(path)})`
+  )).join('\n');
+  const loopbackNetworkRules = [...new Set(loopbackNetworkPorts)].map((port) => (
+    `(allow network-outbound (remote tcp "localhost:${port}"))`
+  )).join('\n');
+  const claudeRuntimeRules = allowClaudeRuntimeAccess ? (() => {
+    const claudeTmp = `/private/tmp/claude-${typeof process.getuid === 'function' ? process.getuid() : '0'}`;
+    const userKeychains = join(homedir(), 'Library', 'Keychains');
+    const textEncoding = join(homedir(), '.CFUserTextEncoding');
+    return [
+      // Native Claude uses a uid-scoped /private/tmp directory. Admit that
+      // exact runtime directory; every sibling remains denied by default.
+      `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(claudeTmp)}"))`,
+      `(allow file-read* file-test-existence file-write* ${literal(claudeTmp)} ${subpath(claudeTmp)})`,
+      // Claude's security helper needs the encrypted login-keychain database
+      // and this non-secret locale file. Other wrappers do not get this access.
+      `(allow file-read* file-test-existence ${subpath(userKeychains)} ${literal(textEncoding)})`,
+      `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(userKeychains)}"))`,
+    ];
+  })() : [];
 
   return [
     PLATFORM_BASELINE.trim(),
@@ -380,22 +406,15 @@ export const buildSeatbeltProfile = ({
     `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(resolvedState)}"))`,
     workspaceRule,
     `(allow file-read* file-test-existence file-write* ${subpath(resolvedState)})`,
+    loopbackNetworkRules,
     mcpRule,
+    readOnlyRules,
     // The workspace is intentionally readable, but credential-like nested
     // paths are not. Explicit deny wins over the broad workspace allow.
     `(deny file-read* file-write* ${subpath(join(resolvedWorkspace, '.commonly'))})`,
     `(deny file-read* file-write* ${subpath(join(resolvedWorkspace, '.codex'))})`,
     `(deny file-read* file-write* ${literal(join(resolvedWorkspace, '.env'))})`,
-    // Native Claude uses a uid-scoped /private/tmp directory even when
-    // TMPDIR points elsewhere. Admit that exact runtime directory; every
-    // sibling under /private/tmp remains denied by the default policy.
-    `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(claudeTmp)}"))`,
-    `(allow file-read* file-test-existence file-write* ${literal(claudeTmp)} ${subpath(claudeTmp)})`,
-    // OAuth remains in macOS Keychain rather than a bearer-token file or
-    // child environment variable. Claude's `security` helper needs the
-    // encrypted login-keychain database plus this non-secret locale file.
-    `(allow file-read* file-test-existence ${subpath(userKeychains)} ${literal(textEncoding)})`,
-    `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(userKeychains)}"))`,
+    ...claudeRuntimeRules,
   ].filter(Boolean).join('\n\n');
 };