@ravefox/space 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,345 @@
+/**
+ * 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, but sandbox support and broker
+ * admission are separate: only ADAPTERS_WITH_GRANT_BROKER may receive the grant
+ * broker (claude, codex, OpenCode since F175a, pi since F175c, Qwen and Goose
+ * since F175d). pi, Qwen and Goose are admitted on a narrower rule
+ * (ADAPTERS_WITH_PUBLIC_ONLY_GRANT): a public seat in a jail this host has (for
+ * pi, macOS Seatbelt only), and every other declaration is
+ * `adapter_confines_public_only`, which a named grant (F94) does not lift.
+ *
+ * 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_GRANT_BROKER, ADAPTERS_WITH_PUBLIC_ONLY_GRANT } from './default-environment.js';
+import { effectiveSandboxTrust } 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';
+
+/**
+ * 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))
+);
+
+/**
+ * F175c: the one reason naming (F94) does not lift for an adapter on the grant
+ * list. pi, Qwen and Goose hold a grant only on a public seat in a jail, so
+ * every declaration of theirs short of that is this reason, not a sandbox
+ * reason a consent could waive. Same literal as the server's.
+ */
+export const PUBLIC_ONLY_REASON = 'adapter_confines_public_only';
+
+const publicOnlyReason = (environment, rule, platform) => {
+  const sandbox = environment?.sandbox;
+  if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return PUBLIC_ONLY_REASON;
+  if (sandbox.mode === 'none' || effectiveSandboxTrust(sandbox.trust) !== 'public') return PUBLIC_ONLY_REASON;
+  // D245: a public declaration on native Windows reads the same for every adapter.
+  if (platform === 'win32') return 'sandbox_mode_unenforceable';
+  const modes = Object.hasOwn(rule, platform) ? rule[platform] : null;
+  if (!modes) return PUBLIC_ONLY_REASON;
+  const mode = resolvePublicSandboxMode(sandbox, platform);
+  return typeof mode === 'string' && modes.has(mode) ? null : PUBLIC_ONLY_REASON;
+};
+
+/**
+ * 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_GRANT_BROKER.has(adapter)) return 'adapter_cannot_confine';
+  const publicOnly = ADAPTERS_WITH_PUBLIC_ONLY_GRANT.get(adapter);
+  if (publicOnly) return publicOnlyReason(environment, publicOnly, platform);
+
+  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 (effectiveSandboxTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
+  // D245: native Windows has no OS jail for any adapter. Claude there runs
+  // only by the user's --unsandboxed (policy without a jail), and a public
+  // Codex seat is refused there outright (host-check.js), so neither carries a
+  // grant.
+  if (platform === 'win32') return 'sandbox_mode_unenforceable';
+  const mode = resolvePublicSandboxMode(declared, platform);
+  if (typeof mode !== 'string' || !ENFORCING_MODES.has(mode)) return 'sandbox_mode_unenforceable';
+  return null;
+};
+
+/** "claude, codex or opencode": the broker set, as a remedy names it. */
+const brokerAdapterList = () => {
+  const names = [...ADAPTERS_WITH_GRANT_BROKER];
+  return names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}` : names.join('');
+};
+
+const detailFor = (reason, adapter, environment, platform = process.platform) => {
+  const drop = 'or drop the grant broker from this seat';
+  if (reason === 'sandbox_mode_unenforceable' && platform === 'win32') {
+    return 'native Windows has no sandbox Space can enforce, so no agent on this computer gets connector grants;'
+      + ` run the agent on macOS or Linux to use grants, ${drop}`;
+  }
+  if (reason === PUBLIC_ONLY_REASON) {
+    const jails = Object.keys(ADAPTERS_WITH_PUBLIC_ONLY_GRANT.get(adapter) || {});
+    const macOnly = jails.length === 1 && jails[0] === 'darwin';
+    return `the seat runs the '${adapter}' adapter, which carries a grant only on a public seat confined by the`
+      + `${macOnly ? ' macOS' : ''} sandbox; declare sandbox.trust 'public'${macOnly ? ' and run it on a Mac' : ''},`
+      + ` or move it to an adapter that confines this host, ${drop} (naming the agent on the grant does not lift this)`;
+  }
+  if (reason === 'adapter_cannot_confine') {
+    return `the seat runs the '${adapter || 'unresolved'}' adapter, which is not approved to receive the grant broker;`
+      + ` move this seat to the ${brokerAdapterList()} adapter, ${drop}`;
+  }
+  if (reason === 'sandbox_absent') {
+    return 'this seat declares no sandbox block and none was derived for it,'
+      + ` 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(effectiveSandboxTrust(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;
+
+  // F94: the server flags a broker whose grant names this seat (the granter's
+  // own agent, with consent) so it rides a seat no sandbox confines. Delivery
+  // only; the broker checks the naming on every call. Never on native Windows,
+  // and never for an adapter not approved for the broker.
+  const rides = (server) => server?.byoNamed === true
+    && reason !== 'adapter_cannot_confine' && reason !== PUBLIC_ONLY_REASON && platform !== 'win32';
+  const isWithheld = (server) => isOurGrantBroker(server, { instanceUrl }) && !rides(server);
+  if (!environment.mcp.some(isWithheld)) return environment;
+
+  const kept = environment.mcp.filter((server) => !isWithheld(server));
+  const withheld = environment.mcp
+    .filter(isWithheld)
+    .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, platform),
+    }, withheld);
+  }
+  return { ...environment, mcp: kept };
+};
+
+/**
+ * Merge the server's grant-broker entries into a seat environment, the way the
+ * daemon's work list does it (`GET /api/agent-binding/assigned` in
+ * `backend/routes/agentBinding.ts`): an existing entry with a broker's name is
+ * replaced, the brokers are appended, and a seat with no environment gets one
+ * holding only them. Used by `agent run` without a daemon (F150), whose
+ * `GET /api/agents/runtime/grant-brokers` returns the same per-seat projection.
+ *
+ * Merge only. The caller runs `withholdGrantBroker` on the result, so the
+ * client-side refusal still applies to whatever the server sent.
+ * Identity is preserved when there is nothing to merge.
+ */
+export const mergeGrantBrokers = (environment, servers) => {
+  const brokers = Array.isArray(servers)
+    ? servers.filter((server) => server && typeof server === 'object' && !Array.isArray(server))
+    : [];
+  if (!brokers.length) return environment;
+  if (!environment) return { mcp: brokers };
+  const existing = Array.isArray(environment.mcp) ? environment.mcp : [];
+  return {
+    ...environment,
+    mcp: [
+      ...existing.filter((server) => !brokers.some((broker) => broker.name === server?.name)),
+      ...brokers,
+    ],
+  };
+};
+
+export default {
+  GRANT_BROKER_REFUSAL_CODE,
+  PUBLIC_ONLY_REASON,
+  ENFORCING_MODES,
+  isOurGrantBroker,
+  declaresGrantBroker,
+  confinementReason,
+  withholdGrantBroker,
+  mergeGrantBrokers,
+};

package/src/lib/hooks-config.js

@@ -0,0 +1,238 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'fs';
+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;
+export const MAX_HOOK_TIMEOUT_MS = 5000;
+
+export const clampHookTimeoutMs = (value) => Math.min(
+  MAX_HOOK_TIMEOUT_MS,
+  Math.max(250, Math.trunc(Number.isFinite(Number(value)) ? Number(value) : DEFAULT_HOOK_TIMEOUT_MS)),
+);
+
+const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/**
+ * Keep hook commands free of bearer material.  The dispatcher reads
+ * COMMONLY_AGENT_TOKEN from the process environment at invocation time.
+ */
+export const buildHookCommand = ({ agentName, timeoutMs = DEFAULT_HOOK_TIMEOUT_MS }) => (
+  `commonly agent hooks-forward ${shellQuote(agentName)} --timeout ${clampHookTimeoutMs(timeoutMs)}`
+);
+
+const hookEntry = ({ agentName, timeoutMs }) => ({
+  matcher: '',
+  hooks: [{
+    type: 'command',
+    command: buildHookCommand({ agentName, timeoutMs }),
+    // Claude interprets this as seconds.  Keep it short so a dead backend
+    // cannot stall every tool call for the 600s default.
+    timeout: Math.ceil(clampHookTimeoutMs(timeoutMs) / 1000),
+  }],
+});
+
+const stableJson = (value) => {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+};
+
+const digestArgs = (value) => createHash('sha256').update(stableJson(value ?? {})).digest('hex');
+
+/** Resolve a caller-side path and emit the repo-relative POSIX wire form. */
+const localPath = (value, root = process.cwd()) => {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) return null;
+  if (value.trim().split(/[\\/]/).includes('..')) return null;
+  const resolvedRoot = pathResolve(root);
+  const rootReal = (() => {
+    try { return realpathSync(resolvedRoot); } catch { return resolvedRoot; }
+  })();
+  const absolute = isAbsolute(value) ? pathResolve(value) : pathResolve(resolvedRoot, value);
+  if (absolute !== resolvedRoot && !absolute.startsWith(`${resolvedRoot}/`)) return null;
+  let current = absolute;
+  const suffix = [];
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) return null;
+    suffix.unshift(current.slice(parent.length + 1));
+    current = parent;
+  }
+  let resolved;
+  try { resolved = realpathSync(current); } catch { resolved = current; }
+  const candidate = pathResolve(resolved, ...suffix);
+  if (candidate !== rootReal && !candidate.startsWith(`${rootReal}/`)) return null;
+  const repoPath = relative(rootReal, candidate).replaceAll('\\', '/');
+  return repoPath || '.';
+};
+
+const inputPaths = (input = {}) => {
+  const values = [input.path, input.file_path, input.filePath, input.target_file, input.paths]
+    .flatMap((value) => Array.isArray(value) ? value : [value]);
+  return values.filter((value) => typeof value === 'string' && value.trim());
+};
+
+/** Strip raw tool arguments before they leave the local harness. */
+export const sanitizeHookPayload = (payload = {}, { cwd = process.cwd() } = {}) => {
+  const event = payload.event || payload.hook_event_name || payload.event_name || '';
+  const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+  const tool = payload.tool || payload.tool_name || payload.toolName;
+  const root = payload.cwd || cwd;
+  const declaredPaths = [payload.paths, payload.resolvedPaths]
+    .flatMap((value) => Array.isArray(value) ? value : [value])
+    .filter((value) => typeof value === 'string');
+  const paths = [...inputPaths(input), ...declaredPaths]
+    .map((value) => localPath(value, root)).filter(Boolean);
+  return {
+    ...(event ? { event } : {}),
+    ...(payload.eventId || payload.event_id ? { eventId: payload.eventId || payload.event_id } : {}),
+    ...(typeof tool === 'string' && tool ? { tool } : {}),
+    argsDigest: payload.argsDigest || payload.args_digest || digestArgs(input),
+    ...(paths.length > 0 ? { paths: Array.from(new Set(paths)) } : {}),
+  };
+};
+
+/** Merge Commonly hooks into settings while preserving every user setting. */
+export const mergeHooksConfig = (
+  existing = {},
+  { agentName, events = HOOK_EVENTS, timeoutMs = DEFAULT_HOOK_TIMEOUT_MS } = {},
+) => {
+  if (!agentName) throw new Error('agentName is required');
+  const source = existing && typeof existing === 'object' ? existing : {};
+  const hooks = source.hooks && typeof source.hooks === 'object' ? { ...source.hooks } : {};
+  for (const event of events) {
+    const prior = Array.isArray(hooks[event]) ? hooks[event] : [];
+    // Replace only the entry generated for this agent; unrelated matchers and
+    // command hooks remain byte-for-byte represented in the resulting JSON.
+    const retained = prior.filter((entry) => !entry?.hooks?.some((h) => (
+      h?.command?.includes(`commonly agent hooks-forward '${String(agentName).replaceAll("'", "'\\''")}'`)
+    )));
+    hooks[event] = [...retained, hookEntry({ agentName, timeoutMs })];
+  }
+  return { ...source, hooks };
+};
+
+export const settingsPathForScope = ({ scope = 'project', cwd = process.cwd(), home = homedir() } = {}) => {
+  if (scope === 'user') return join(home, '.claude', 'settings.json');
+  if (scope !== 'project') throw new Error("scope must be 'project' or 'user'");
+  return join(cwd, '.claude', 'settings.local.json');
+};
+
+export const readJsonSettings = (filePath, fsApi = { readFileSync, existsSync }) => {
+  if (!fsApi.existsSync(filePath)) return {};
+  try {
+    const parsed = JSON.parse(fsApi.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    throw new Error(`Could not parse ${filePath}: ${error.message}`);
+  }
+};
+
+export const writeHooksConfig = ({
+  filePath,
+  agentName,
+  scope = 'project',
+  cwd = process.cwd(),
+  home = homedir(),
+  timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
+  fsApi = { readFileSync, writeFileSync, mkdirSync, existsSync },
+} = {}) => {
+  const target = filePath || settingsPathForScope({ scope, cwd, home });
+  const existing = readJsonSettings(target, fsApi);
+  const next = mergeHooksConfig(existing, { agentName, timeoutMs });
+  fsApi.mkdirSync(dirname(target), { recursive: true });
+  fsApi.writeFileSync(target, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  return { filePath: target, config: next };
+};
+
+/**
+ * Execute one hook event.  It is intentionally dependency-light so the
+ * generated Claude command works on a fresh CLI install (Node 20's fetch).
+ * On any transport failure, fail open with no output.  A deny is only the
+ * 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 = resolveHookToken(),
+  input = '',
+  timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
+  fetchImpl = globalThis.fetch,
+  stdout = (value) => process.stdout.write(value),
+} = {}) => {
+  let payload;
+  try { payload = typeof input === 'string' ? JSON.parse(input || '{}') : input; } catch {
+    payload = {};
+  }
+  const event = payload?.event || payload?.hook_event_name || payload?.event_name || '';
+  const preTool = event === 'PreToolUse';
+  if (!endpoint || !token || !fetchImpl) {
+    return { acknowledged: false, reason: 'hook_unavailable' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), clampHookTimeoutMs(timeoutMs));
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(sanitizeHookPayload(payload)),
+      signal: controller.signal,
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    if (preTool && body.permissionDecision === 'deny') {
+      // Claude Code reads a PreToolUse decision only from `hookSpecificOutput`. The top-level
+      // `{permissionDecision}` this printed before was ignored and the tool ran (measured on
+      // Claude Code 2.1.296, 2026-10-14, issue #2145).
+      stdout(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          ...(body.reason ? { permissionDecisionReason: body.reason } : {}),
+        },
+      }));
+    }
+    return body;
+  } catch (error) {
+    // Deliberately silent and exit-0 for every failure.  Claude's default is
+    // fail-open, and an unavailable advisory hook must not block a tool.
+    void error;
+    return { acknowledged: false, reason: 'hook_unavailable' };
+  } finally {
+    clearTimeout(timer);
+  }
+};