@commonlyai/cli 0.1.61 → 0.1.64

package/src/lib/adapters/pi.js

@@ -40,6 +40,8 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { GRANT_BROKER_REFUSAL, isGrantBrokerUrl } from './pi-mcp-client.mjs';
+import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { removeCredentialFile, writeCredentialFile } from '../credential-file.js';
 
 const DEFAULT_TIMEOUT_MS = (() => {
   const fallback = 15 * 60 * 1000;
@@ -68,12 +70,17 @@ const BRIDGE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'pi-commonly-m
 // Same substitution contract as claude.js / codex.js: ${COMMONLY_*}
 // placeholders in the declared MCP env are the wrapper's per-(agent, pod)
 // runtime values, filled at spawn time.
-const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_TOKEN_FILE', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
 const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
 const substitutePlaceholders = (value, ctx) => {
   if (typeof value !== 'string' || !value.includes('${COMMONLY_')) return value;
   const subs = {
     COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    // The PATH of this spawn's credential file. The bridge reads the file and
+    // hands the VALUE to the server on fd 3, so the token still never reaches a
+    // child's environment — but the payload that travels to the bridge carries a
+    // path rather than the secret (TASK-083).
+    COMMONLY_TOKEN_FILE: ctx.credentialFile || '',
     COMMONLY_API_URL: ctx.instanceUrl || '',
     COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
   };
@@ -198,7 +205,14 @@ export const resolveMcpServers = (mcpServers, ctx = {}) => {
       carried.push({
         name: server.name,
         command: server.command.map((a) => substitutePlaceholders(a, ctx)),
-        env: Object.fromEntries(Object.entries(server.env || {}).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
+        // Rewritten before substitution, so our own server is handed the file
+        // (whose value the bridge pipes) instead of the token itself.
+        env: Object.fromEntries(Object.entries(
+          deliverSeatCredential(server, {
+            credentialFile: ctx.credentialFile,
+            label: 'pi',
+          }).env,
+        ).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
       });
       continue;
     }
@@ -384,27 +398,55 @@ export default {
     const fullPrompt = buildMemoryPreamble(prompt, ctx.memoryLongTerm, { freshSession: !isResume });
     await writeFile(join(agentDir, 'models.json'), `${JSON.stringify(buildModelsJson(provider, model), null, 2)}\n`, { mode: 0o600 });
 
-    const servers = resolveMcpServers(ctx.environment?.mcp, ctx);
-    const childEnv = {
-      ...baseEnv,
-      PI_CODING_AGENT_DIR: agentDir,
-      PI_SKIP_VERSION_CHECK: '1',
-    };
-    const args = buildArgs({
-      prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
-      bridge: servers.length ? (ctx._bridgePath || BRIDGE_PATH) : null,
+    // One credential file per spawn, inside this seat's own 0700 home — pi has no
+    // enforced sandbox, so the seat's home is the narrowest place that is still
+    // readable by the bridge. The value the server receives still travels on fd 3
+    // (pi-mcp-client's fd channel); the file is where the launcher puts it.
+    const credential = writeCredentialFile(ctx.runtimeToken, {
+      agentName: ctx.agentName || 'agent',
+      root: join(home, 'credentials'),
     });
+    try {
+      const servers = resolveMcpServers(ctx.environment?.mcp, {
+        ...ctx,
+        credentialFile: credential?.path || null,
+      });
+      const childEnv = {
+        ...baseEnv,
+        PI_CODING_AGENT_DIR: agentDir,
+        PI_SKIP_VERSION_CHECK: '1',
+      };
+      // `baseEnv` is normally the process environment, which carries the
+      // bootstrap export. Nothing below this process needs the value: the bridge
+      // is handed the servers, their resolved values included, over fd 3. It has
+      // to come out rather than merely stop being added, because pi's `bash`
+      // tool spawns children with `{ ...process.env }`, so a copy here is a copy
+      // in the seat's shell — and the file path goes in, so a hook resolves its
+      // credential without the value.
+      withholdRuntimeCredential(childEnv, {
+        credentialFile: credential?.path || null,
+      });
+      const args = buildArgs({
+        prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
+        bridge: servers.length ? (ctx._bridgePath || BRIDGE_PATH) : null,
+      });
 
-    const reply = await runPi({
-      args,
-      cwd: ctx.cwd,
-      env: childEnv,
-      payload: servers.length ? JSON.stringify(servers) : undefined,
-      timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
-      spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
-    });
-    // Empty text with a clean exit is a silent turn; the run loop treats it
-    // as NO_REPLY-shaped and re-delivers on its own rules.
-    return { text: reply.text, newSessionId: sessionId };
+      const reply = await runPi({
+        args,
+        cwd: ctx.cwd,
+        env: childEnv,
+        payload: servers.length ? JSON.stringify(servers) : undefined,
+        timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
+      });
+      // Empty text with a clean exit is a silent turn; the run loop treats it
+      // as NO_REPLY-shaped and re-delivers on its own rules.
+      return { text: reply.text, newSessionId: sessionId };
+    } finally {
+      // Best effort: the bridge has already read what it needs by the time the
+      // turn ends, and a token file that outlives its turn is a token file that
+      // sits in a home for the next one.
+      removeCredentialFile(credential);
+    }
   },
 };

package/src/lib/credential-file.js

@@ -0,0 +1,78 @@
+/**
+ * A per-spawn credential file: the launcher channel for the runtime token
+ * (TASK-082/083, ruled 2026-09-19 — "a credential file, only its PATH in the
+ * env").
+ *
+ * WHY A FILE AND NOT THE ENVIRONMENT. The token used to ride the runtime's own
+ * environment (claude expands `${COMMONLY_AGENT_TOKEN}` from it, codex forwards
+ * it through `mcp_servers.*.env_vars`), which means every child of the runtime
+ * inherited it — measured on 2026-09-19: a `@playwright/mcp` process held the
+ * seat's `COMMONLY_AGENT_TOKEN`, and a pi seat's MCP child held the daemon's
+ * `COMMONLY_LITELLM_KEY`. A PATH is not a secret, so handing the path to the
+ * runtime is safe even though the token it names is not, and an unrelated MCP
+ * server that inherits the runtime's environment gets nothing it can use.
+ *
+ * WHY PER SPAWN. The file lives only as long as one spawn of one runtime, in a
+ * directory only its owner can traverse (0700), with the file itself 0600. A
+ * fixed path would widen the window to "since the first spawn" and would let two
+ * concurrent seats share one credential by accident.
+ *
+ * The reader side is `readToken` in `commonly-mcp/src/client.js`, which resolves
+ * fd, then file, then environment — by declaration, and refuses to fall through
+ * from a declared source that cannot be read.
+ */
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+/** The variable a child reads to find the credential. Never carries the token. */
+export const CREDENTIAL_FILE_VAR = 'COMMONLY_TOKEN_FILE';
+
+/**
+ * The variable that USED to carry the token itself, and still does for a server
+ * that cannot read anything else. Kept beside the file var so the two channels
+ * are named in one place rather than one per adapter.
+ */
+export const CREDENTIAL_KEY = 'COMMONLY_AGENT_TOKEN';
+
+/** Default root: inside the CLI's own state directory, not a world-readable /tmp. */
+export const credentialRoot = () => join(homedir(), '.commonly', 'credentials');
+
+/**
+ * Write `token` to a fresh 0600 file and return its path, or null when there is
+ * no token to write (a seat bootstrapping without one).
+ *
+ * `fs` is injectable so tests can assert the mode and the path shape without
+ * writing into the operator's home.
+ */
+export const writeCredentialFile = (token, {
+  agentName = 'agent',
+  root = credentialRoot(),
+  fs = { mkdirSync, writeFileSync, chmodSync, rmSync },
+  now = () => Date.now(),
+  random = () => randomBytes(4).toString('hex'),
+} = {}) => {
+  const value = typeof token === 'string' ? token.trim() : '';
+  if (!value) return null;
+  const dir = join(root, `${agentName}-${now()}-${random()}`);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, 'token');
+  fs.writeFileSync(path, value, { mode: 0o600 });
+  // writeFileSync's mode is subject to the process umask, so a 0022 umask still
+  // produces 0644. chmod is the assertion, not a courtesy.
+  fs.chmodSync(path, 0o600);
+  return { path, dir };
+};
+
+/** Best-effort removal once the spawn that owns the file has ended. */
+export const removeCredentialFile = (written, { fs = { rmSync } } = {}) => {
+  const dir = typeof written === 'string' ? dirname(written) : written?.dir;
+  if (!dir) return false;
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/lib/daemon-supervisor.js

@@ -4,6 +4,7 @@ import { isAbsolute, resolve as pathResolve } from 'node:path';
 import { auditDeclaredMcp, installedStdioEntries } from './declared-mcp-guard.js';
 
 import { seatBaseline } from './default-environment.js';
+import { withholdGrantBroker } from './grant-broker-guard.js';
 
 /**
  * ADR-026 Phase 2, slice 2: the resident supervision loop behind
@@ -172,6 +173,27 @@ export const createDaemonSupervisor = ({
   // Returns 'ready' | 'changed' (record updated — the seat must restart to
   // load it) | false.
   const ensureToken = async (row) => {
+    // One derive for this seat, so the broker refusal cannot be applied at three
+    // of four sites: `seatBaseline` is where an environment becomes the one the
+    // seat RUNS under, and `withholdGrantBroker` asks the same question the
+    // server asks (`can this seat confine a granter's authority?`) for the cases
+    // the server cannot see — a row naming no adapter, a backend older than the
+    // refusal, a record written by hand. Entry-level per wren 69829: the broker
+    // entry is withheld and the seat still starts, because it was never promised
+    // confinement. `record.instanceUrl` is what makes the injected url
+    // identifiable at all — the record holds the UNRESOLVED
+    // `${COMMONLY_API_URL}/api/mcp/grants/<id>` placeholder.
+    const derive = (environment, adapter, options) => withholdGrantBroker(
+      seatBaseline(environment, adapter, options),
+      adapter,
+      {
+        instanceUrl: record.instanceUrl,
+        onRefuse: (refusal, names) => log(
+          `[${row.agentName}] ${refusal.code} (${refusal.reason}) — withholding ${names.join(', ')}: ${refusal.detail}`,
+        ),
+      },
+    );
+
     const existing = loadToken(row.agentName);
     if (existing) {
       // A model changed in the UI reaches the seat here: update the record,
@@ -214,7 +236,7 @@ export const createDaemonSupervisor = ({
         // defaults to 'none' in the adapters, so an omitted block is an
         // unconfined seat (TASK-052). A local record with no environment at
         // all is in the same position — nobody has authored anything.
-        const nextEnvironment = seatBaseline(merged, nextAdapter, {
+        const nextEnvironment = derive(merged, nextAdapter, {
           sandbox: wanted.declared || !existing.environment,
         });
         const workspacePath = workspacePathFor(nextEnvironment);
@@ -235,7 +257,7 @@ export const createDaemonSupervisor = ({
       if (adapterChanged) {
         // An adapter that consumes mcp[] must not be started on a record that
         // declares none, even when only the adapter itself changed.
-        const nextEnvironment = seatBaseline(existing.environment, nextAdapter, {
+        const nextEnvironment = derive(existing.environment, nextAdapter, {
           sandbox: !existing.environment,
         });
         saveToken(row.agentName, {
@@ -254,7 +276,7 @@ export const createDaemonSupervisor = ({
         // stays tool-less for as long as it runs. Heal it here, and only when
         // the environment actually changed — otherwise every tick rewrites the
         // file and restarts the seat forever.
-        const nextEnvironment = seatBaseline(existing.environment, existing.adapter, {
+        const nextEnvironment = derive(existing.environment, existing.adapter, {
           sandbox: !existing.environment,
         });
         if (!isDeepStrictEqual(existing.environment || null, nextEnvironment || null)) {
@@ -312,7 +334,7 @@ export const createDaemonSupervisor = ({
     // tools and cannot post. See lib/default-environment.js. Nothing here is
     // 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 = seatBaseline(
+    const recordEnvironment = derive(
       environment ? environment.value : null,
       adapter,
       { sandbox: true },

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

@@ -0,0 +1,268 @@
+/**
+ * Withhold the grant broker from a seat this daemon cannot confine (TASK-063).
+ *
+ * The grant arrives as an injected MCP server, and confinement is declared in a
+ * different field — `sandbox` — so the two can disagree: a seat can be handed a
+ * granter's authority and no confinement. wren's ruling (69799) is REFUSE, not
+ * derive, and it is ENTRY-level (69829): the broker entry is withheld and the
+ * seat runs, because the seat was never promised confinement — a seat-level
+ * refusal is #1727's case only (a declared sandbox the host cannot enforce).
+ *
+ * This is the daemon half of one refusal with TWO emitters. The server refuses
+ * at the projection (`backend/services/grantBrokerConfinement.ts`) for rows it
+ * can judge host-independently; the daemon decides the rest, because it is the
+ * layer that knows this host, that resolved the adapter locally, and that holds
+ * the record the seat actually runs from — including records the projection
+ * 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.
+ *
+ * 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
+ * not visible from the installation row — `quill` carries no sandbox key), so
+ * absence is this layer's to judge. Reaching it here means the baseline did not
+ * supply one, which happens for a local record with no environment of its own
+ * (`sandbox: !existing.environment` at the derive sites): nobody authored a
+ * sandbox and nothing derived one, so the seat would run unconfined.
+ *
+ * THE URL IS THE FACT, AND THE URL THIS LAYER HOLDS USUALLY CANNOT BE PARSED.
+ * Measured on the live fleet: the broker url in a token record is the
+ * UNRESOLVED placeholder `"${COMMONLY_API_URL}/api/mcp/grants/<id>"` (c4-smoke,
+ * the only record declaring one). `new URL()` throws on that string, so
+ * `isGrantBrokerUrl` — which the pi adapter calls AFTER substituting — returns
+ * false here. A daemon-side predicate that reused it unchanged would match
+ * nothing and refuse nothing while reading as if it enforced something. So the
+ * known placeholders are resolved to this instance first, and an entry counts
+ * only when it is OUR broker: our origin, or a relative/placeholder-prefixed
+ * path. A foreign server that happens to live under `/api/mcp/grants/` is not
+ * our grant and is left alone.
+ *
+ * AND A MISS HERE IS FAIL-OPEN, so the path is NORMALIZED before it is judged.
+ * Measured (vera, 70369): a bound instance spelled `https://api.commonly.me/`
+ * turns `"${COMMONLY_API_URL}/api/mcp/grants/g1"` into
+ * `https://api.commonly.me//api/mcp/grants/g1`, whose pathname starts `//api/`
+ * and matches nothing — the entry goes unrecognised and the broker RIDES into a
+ * seat this daemon just decided it cannot confine. Reachable: `agent.js` takes
+ * `instanceUrl` from `COMMONLY_API_URL` with a bare `.trim()`, while `config.js`
+ * is what strips the slash.
+ *
+ * The enforcement is ONE mechanism: duplicate slashes are collapsed before the
+ * path predicate sees them. It covers the doubled slash whichever side produced
+ * it — the join, a hand-written record, and a protocol-relative spelling OF THE
+ * PATH (`//api/mcp/grants/g1`, which collapses to the broker's path) — where
+ * stripping the instance's trailing slash covers only the join, and a mutation
+ * showed the two were redundant here (removing the strip reddened nothing).
+ *
+ * A URL WITH NO SCHEME HAS TWO READINGS, and both are taken (vera, 70372, who
+ * corrected a first draft of this paragraph for claiming the second was
+ * covered). Collapsing alone reads `//api.commonly.me/api/mcp/grants/g1` as the
+ * PATH `/api.commonly.me/api/...`, which is not the broker's path and measures
+ * false — a fail-open, because URL semantics say that string names THIS
+ * instance. So a schemeless value is also resolved against the bound instance,
+ * and counts when that reading lands on our origin and the broker's path. A
+ * foreign host is left alone under either reading; the path reading is what the
+ * shipped declarations use, and a record is free to hold the other.
+ *
+ * Collapsing can only turn a miss into a match, and a match here means WITHHOLD,
+ * so it moves in the safe direction; origin equality is still required first, so
+ * 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 { LEGACY_SANDBOX_TRUST } from './environment.js';
+import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from './sandbox/mode.js';
+
+/** One typed code, two emitters (`decidedBy` says which one spoke). */
+export const GRANT_BROKER_REFUSAL_CODE = 'grant_broker_unconfined';
+
+/**
+ * Every mode an adapter enforces for a public seat: the cli's own public set
+ * ({workspace, read-only}) plus `bwrap`, which `resolvePublicSandboxMode`
+ * resolves to on Linux and claude implements there. Derived from the cli's
+ * constants rather than restated, so a mode added to one is not silently
+ * missing from the other.
+ */
+export const ENFORCING_MODES = new Set([...PUBLIC_SANDBOX_MODES, 'bwrap']);
+
+const URL_PLACEHOLDERS = ['${COMMONLY_API_URL}', '${COMMONLY_INSTANCE_URL}'];
+const PARSE_ANCHOR = 'https://grant-declaration.invalid';
+
+/** `internal` → `public`; anything else (including absent) is itself. */
+const effectiveTrust = (trust) => (
+  typeof trust === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, trust)
+    ? LEGACY_SANDBOX_TRUST[trust]
+    : trust
+);
+
+/**
+ * A bound instance is only trimmed here (`agent.js` does the same). Any
+ * trailing slash it carries is deliberately left alone: the doubled slash it
+ * would manufacture is answered by `collapseSlashes` below, one mechanism for
+ * every spelling rather than two that a mutation cannot tell apart.
+ */
+const resolveInstance = (instanceUrl) => (
+  typeof instanceUrl === 'string' ? instanceUrl.trim() : ''
+);
+
+/**
+ * `//api/mcp/grants/g1` and `/api/mcp/grants/g1` are the same path written two
+ * ways, and only one of them is ours to withhold — the absolute branch needs it
+ * for a doubled slash after the origin, the relative branch for a
+ * protocol-relative spelling of the path, i.e. one that names no host (a
+ * protocol-relative URL naming a HOST is a different string and is not ours).
+ * Collapsing is one-directional (a miss becomes a match) and never widens the
+ * ORIGIN check above it.
+ */
+const collapseSlashes = (path) => path.replace(/\/{2,}/g, '/');
+
+const parseUrl = (value, baseUrl) => {
+  try {
+    return baseUrl ? new URL(value, baseUrl) : new URL(value);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Does this one declaration name the grant broker WE inject?
+ *
+ * Resolves the declaration's own placeholders against the instance this daemon
+ * is bound to, then asks the same path predicate the adapters use — so the
+ * expanded spelling and the placeholder spelling agree, and an entry on another
+ * origin does not match just because its path resembles ours.
+ */
+export const isOurGrantBroker = (server, { instanceUrl } = {}) => {
+  const url = server?.url;
+  if (typeof url !== 'string' || url === '') return false;
+
+  const base = resolveInstance(instanceUrl);
+  let resolvedUrl = url;
+  for (const placeholder of URL_PLACEHOLDERS) {
+    if (!resolvedUrl.includes(placeholder)) continue;
+    // A placeholder we cannot resolve is not ours to judge; an entry that is
+    // only a placeholder has no origin to compare and no path to match.
+    if (base === '') return false;
+    resolvedUrl = resolvedUrl.split(placeholder).join(base);
+  }
+
+  const parsed = parseUrl(resolvedUrl);
+  const ours = base === '' ? null : parseUrl(base);
+  const onOurOrigin = (url) => url.origin + collapseSlashes(url.pathname) + url.search;
+
+  // Every candidate below is first proven to be on OUR origin, so an entry that
+  // merely resembles the broker is left alone; a match means WITHHOLD.
+  const candidates = [];
+  if (parsed) {
+    // An absolute url: our origin, or it is not our grant however its path reads.
+    if (ours && parsed.origin === ours.origin) candidates.push(onOurOrigin(parsed));
+  } else if (resolvedUrl.startsWith('/')) {
+    // A schemeless url, read BOTH ways — as a path (anchored so its path can be
+    // judged), and as a protocol-relative reference to the bound instance.
+    candidates.push(PARSE_ANCHOR + collapseSlashes(resolvedUrl));
+    const against = ours ? parseUrl(resolvedUrl, base) : null;
+    if (against && against.origin === ours.origin) candidates.push(onOurOrigin(against));
+  }
+  // An unparseable value that is neither — an unknown `${...}` expansion, a
+  // malformed string — is not an entry this daemon can identify as the broker
+  // it injects, and the injected spelling is one of the two handled above.
+  return candidates.some((candidate) => isGrantBrokerUrl(candidate));
+};
+
+/** True when the environment declares our grant broker at all. */
+export const declaresGrantBroker = (environment, opts) => (
+  Array.isArray(environment?.mcp) && environment.mcp.some((server) => isOurGrantBroker(server, opts))
+);
+
+/**
+ * Why this daemon cannot confine a seat running `adapter` with this
+ * environment — or `null` when confinement is enforced and the broker may ride.
+ * 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';
+
+  const sandbox = environment?.sandbox;
+  if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return 'sandbox_absent';
+  const declared = sandbox;
+  if (declared.mode === 'none') return 'sandbox_mode_none';
+  if (effectiveTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
+  const mode = resolvePublicSandboxMode(declared, platform);
+  if (typeof mode !== 'string' || !ENFORCING_MODES.has(mode)) return 'sandbox_mode_unenforceable';
+  return null;
+};
+
+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'
+      + ` adapter, ${drop}`;
+  }
+  if (reason === 'sandbox_absent') {
+    return 'this seat declares no sandbox block and this daemon derives one only for the claude and codex adapters,'
+      + ` so it would run with a granter's authority and no confinement; declare sandbox.trust 'public' ${drop}`;
+  }
+  if (reason === 'sandbox_mode_none') {
+    return "the declared sandbox.mode is 'none', which no host confines; declare a confining mode"
+      + ` (e.g. 'workspace') ${drop}`;
+  }
+  if (reason === 'sandbox_mode_unenforceable') {
+    const shown = typeof environment?.sandbox?.mode === 'string'
+      ? `'${environment.sandbox.mode}'`
+      : (JSON.stringify(environment?.sandbox?.mode) ?? String(environment?.sandbox?.mode));
+    return `the declared sandbox.mode is ${shown}, which no adapter enforces on any host;`
+      + " declare one of 'workspace' / 'read-only' (or 'bwrap' on Linux)" + ` ${drop}`;
+  }
+  const trust = environment?.sandbox?.trust;
+  const shown = trust === undefined ? 'absent' : `'${String(trust)}'`;
+  return `the declared sandbox.trust is ${shown}${shown === 'absent' ? '' : ` (effective '${String(effectiveTrust(trust))}')`},`
+    + " and no host confines a seat whose trust is not 'public'; declare sandbox.trust 'public'" + ` ${drop}`;
+};
+
+/**
+ * The env a seat may actually run with: the same environment when it declares
+ * no broker WE injected, or when this daemon can confine it; otherwise the same
+ * environment minus the broker, with the refusal handed to `onRefuse`.
+ *
+ * Identity is preserved when nothing is withheld — the derive sites use
+ * `isDeepStrictEqual` against the stored record as their dirty check, so
+ * returning a fresh object every tick would rewrite the record and restart the
+ * seat forever.
+ */
+export const withholdGrantBroker = (environment, adapter, {
+  instanceUrl,
+  onRefuse,
+  platform = process.platform,
+} = {}) => {
+  if (!declaresGrantBroker(environment, { instanceUrl })) return environment;
+  const reason = confinementReason(environment, adapter, platform);
+  if (!reason) return environment;
+
+  const kept = environment.mcp.filter((server) => !isOurGrantBroker(server, { instanceUrl }));
+  const withheld = environment.mcp
+    .filter((server) => isOurGrantBroker(server, { instanceUrl }))
+    .map((server) => (typeof server?.name === 'string' && server.name ? server.name : '(unnamed)'));
+  if (typeof onRefuse === 'function') {
+    onRefuse({
+      code: GRANT_BROKER_REFUSAL_CODE,
+      decidedBy: 'daemon',
+      reason,
+      detail: detailFor(reason, adapter, environment),
+    }, withheld);
+  }
+  return { ...environment, mcp: kept };
+};
+
+export default {
+  GRANT_BROKER_REFUSAL_CODE,
+  ENFORCING_MODES,
+  isOurGrantBroker,
+  declaresGrantBroker,
+  confinementReason,
+  withholdGrantBroker,
+};

package/src/lib/hooks-config.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from
 import { dirname, join, resolve as pathResolve, isAbsolute, relative } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
+import { CREDENTIAL_FILE_VAR } from './credential-file.js';
 
 export const HOOK_EVENTS = ['PreToolUse', 'PostToolUse', 'Stop', 'SubagentStop'];
 export const DEFAULT_HOOK_TIMEOUT_MS = 3000;
@@ -155,9 +156,39 @@ export const writeHooksConfig = ({
  * positive decision returned by the Commonly endpoint; D7 does not let a
  * missing/slow ledger become an accidental write blocker.
  */
+/**
+ * The hook's credential, resolved the way the runtime it runs inside resolves it.
+ *
+ * A hook is a child process of the seat's runtime, so it sees that runtime's
+ * environment — which is exactly the environment TASK-083 emptied of the token.
+ * Reading only COMMONLY_AGENT_TOKEN would therefore leave every hook on a
+ * migrated seat with no credential, and because this path fails open by design
+ * (the `hook_unavailable` return below), the symptom would be a tool-policy hook
+ * that silently stopped deciding anything. So the launcher file comes first, and
+ * the value variable stays as the fallback for a seat whose declaration has not
+ * migrated.
+ *
+ * Unlike the MCP reader, a declared-but-unreadable file does NOT throw here: a
+ * hook that dies is a hook the runtime reports as broken, and this function's
+ * documented posture is to fail open rather than become an accidental blocker.
+ */
+export const resolveHookToken = ({
+  env = process.env,
+  readTokenFile = (path) => readFileSync(path, 'utf8'),
+} = {}) => {
+  const path = env[CREDENTIAL_FILE_VAR];
+  if (typeof path === 'string' && path.trim() !== '') {
+    try {
+      const fromFile = readTokenFile(path).trim();
+      if (fromFile) return fromFile;
+    } catch { /* fall through to the value channel */ }
+  }
+  return env.COMMONLY_AGENT_TOKEN;
+};
+
 export const forwardHookEvent = async ({
   endpoint,
-  token = process.env.COMMONLY_AGENT_TOKEN,
+  token = resolveHookToken(),
   input = '',
   timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
   fetchImpl = globalThis.fetch,