@commonlyai/cli 0.1.81 → 0.1.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.81",
+  "version": "0.1.85",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -48,6 +48,7 @@ import {
   readPodFocus,
 } from '../lib/pod-focus.js';
 import { claimReleaseFor, ackResultFor } from '../lib/claim-outcome.js';
+import { prepareCommitAttribution } from '../lib/commit-attribution.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
@@ -190,6 +191,7 @@ export const bootstrapAgentRecordFromEnv = async ({
 
   return {
     agentName,
+    displayName: identity?.displayName || primary?.displayName || agentName,
     instanceId: identity?.instanceId || primary?.instanceId || 'default',
     podId: primary?.podId || null,
     instanceUrl,
@@ -731,6 +733,7 @@ export const performAttach = async ({
     runtimeToken,
     detected,
     wrappedCli: adapter.name,
+    displayName: installation.displayName || displayName || agentName,
     environment,
     workspace,
   };
@@ -907,6 +910,7 @@ export const performRun = ({
   token,
   adapter,
   agentName,
+  displayName = null,
   instanceId = 'default',
   podId = null,
   environment = null,
@@ -1370,11 +1374,28 @@ export const performRun = ({
       };
     }
     let result;
+    let commitAttribution = null;
     try {
+      // The local CLI is a wrapper for a Commonly seat, so its Git commits
+      // carry the seat and the adapter's selected model/effort. `stub` exists
+      // only for tests and has no commit-making child process.
+      if (adapter?.name !== 'stub') {
+        commitAttribution = prepareCommitAttribution({
+          cwd: agentCwd,
+          env: process.env,
+          agentName,
+          displayName,
+          instanceId,
+          adapter: adapter?.name,
+          model: seatEnvironment?.model,
+          effort: seatEnvironment?.effort,
+        });
+      }
       result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
         sessionId,
         cwd: agentCwd,
-        env: process.env,
+        env: commitAttribution?.env || process.env,
+        commitAttributionEnv: commitAttribution?.sandboxEnv || null,
         memoryLongTerm,
         environment: seatEnvironment,
         // Runtime context the Claude/Codex adapters expose only to their
@@ -1389,10 +1410,14 @@ export const performRun = ({
         metadata: { event },
       });
     } finally {
-      // Best-effort by construction: `close` logs and returns on a failed
-      // revoke, so a turn that already produced an answer is not failed by
-      // cleanup. The boot sweep collects anything left behind.
-      await lease.close();
+      try {
+        commitAttribution?.cleanup();
+      } finally {
+        // Best-effort by construction: `close` logs and returns on a failed
+        // revoke, so a turn that already produced an answer is not failed by
+        // cleanup. The boot sweep collects anything left behind.
+        await lease.close();
+      }
     }
 
     if (result.newSessionId) {
@@ -2511,7 +2536,7 @@ Docs:
         const envAbsPath = opts.env ? pathResolve(opts.env) : null;
         const {
           installation, instanceId, runtimeToken, detected, wrappedCli,
-          environment, workspace,
+          displayName, environment, workspace,
         } = await performAttach({
           client,
           adapterName,
@@ -2525,6 +2550,7 @@ Docs:
 
         saveAgentToken(opts.name, {
           agentName: opts.name,
+          displayName,
           instanceId,
           podId: opts.pod,
           instanceUrl,
@@ -2717,6 +2743,7 @@ Docs:
         token: record.runtimeToken,
         adapter,
         agentName: record.agentName,
+        displayName: record.displayName || record.agentName,
         instanceId: record.instanceId,
         podId: record.podId,
         environment: record.environment || null,

package/src/lib/adapters/claude.js

@@ -45,7 +45,7 @@
 
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash, randomUUID } from 'crypto';
-import { realpathSync } from 'fs';
+import { accessSync, constants, realpathSync } from 'fs';
 import {
   chmod,
   lstat,
@@ -73,6 +73,7 @@ import {
   wrapArgvWithSeatbelt,
 } from '../sandbox/seatbelt.js';
 import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
@@ -90,6 +91,22 @@ const DEFAULT_TIMEOUT_MS = (() => {
 })();
 
 const buildPrompt = buildMemoryPreamble;
+const RUNTIME_CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
+
+const QUOTE_SHELL_ARGUMENT = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+const HEADER_TOKEN_HELPER_SOURCE = `import { readFileSync } from 'node:fs';
+
+const credentialFile = process.env.${CREDENTIAL_FILE_VAR};
+if (!credentialFile) throw new Error('missing ${CREDENTIAL_FILE_VAR}');
+const token = readFileSync(credentialFile, 'utf8').trim();
+if (!token) throw new Error('empty ${CREDENTIAL_FILE_VAR}');
+const templates = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+const headers = Object.fromEntries(
+  Object.entries(templates).map(([name, parts]) => [name, parts.join(token)]),
+);
+process.stdout.write(JSON.stringify(headers) + '\\n');
+`;
 
 const PUBLIC_DENIED_TOOLS = [
   'WebSearch',
@@ -289,9 +306,9 @@ const runClaude = ({ cmd, args, cwd, env, timeoutMs, credentials = [], spawnImpl
 
 // Keep Commonly placeholders in the MCP JSON and expose their values only in
 // Claude's per-spawn environment. Claude Code natively expands ${VAR} in MCP
-// command/args/env/url/headers fields. Substituting here used to materialize the raw
-// cm_agent_* bearer token in a transient JSON file, which made the token
-// readable to any co-confined child allowed to read that config directory.
+// command/args/env/url/header fields. Token-bearing HTTP headers are routed
+// through headersHelper below, because a literal expansion would put the
+// credential in Claude's environment and every MCP child's environment.
 //
 // Recognised placeholders:
 //   ${COMMONLY_TOKEN_FILE}    — the PATH of this spawn's credential file
@@ -323,20 +340,67 @@ const buildMcpExpansionEnv = (mcpConfig, ctx) => {
     // added only when the value is non-empty AND the declaration still references
     // it — and `serialized` is the config AFTER the credential rewrite, which is
     // what moves the default declaration off this value and onto the file. A
-    // reference the rewrite cannot move (args, url, headers, or a string that
-    // merely contains the placeholder) keeps the value for that spawn, because
-    // claude substitutes those literally and there is no file channel for them.
-    // That is the measured carve-out, and createMcpConfig warns when it applies
-    // so the seat still carrying the value is named rather than assumed fixed.
+    // reference that cannot use the file channel (args, url, unsupported or
+    // non-HTTP headers, or a string that merely contains the placeholder) keeps
+    // the value for that spawn. createMcpConfig warns when this carve-out applies.
     COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
   };
   const output = {};
   for (const [key, value] of Object.entries(values)) {
-    if (value && serialized.includes(`\${${key}}`)) output[key] = value;
+    const referenced = serialized.includes(`\${${key}}`)
+      || (key === CREDENTIAL_FILE_VAR && ctx.headersHelperUsesCredentialFile === true);
+    if (value && referenced) output[key] = value;
   }
   return output;
 };
 
+const isHttpTransport = (server) => {
+  const transport = String(server?.transport || server?.type || '').trim().toLowerCase();
+  return transport === 'http' || transport === 'streamable-http';
+};
+
+const getTokenHeaderTemplates = (server) => {
+  if (!isHttpTransport(server) || !server.headers || typeof server.headers !== 'object') return null;
+  const templates = Object.fromEntries(
+    Object.entries(server.headers)
+      .filter(([, value]) => typeof value === 'string' && value.includes(RUNTIME_CREDENTIAL_PLACEHOLDER))
+      .map(([name, value]) => [name, value.split(RUNTIME_CREDENTIAL_PLACEHOLDER)]),
+  );
+  return Object.keys(templates).length > 0 ? templates : null;
+};
+
+const writePrivateFile = async (path, contents) => {
+  await writeFile(path, contents, { encoding: 'utf8', mode: 0o600 });
+  await chmod(path, 0o600);
+};
+
+// Claude's headersHelper is invoked when an HTTP connection is established and
+// again after an authentication retry. Keep the token out of its config and
+// environment: the helper reads the current per-spawn file on every invocation.
+const createTokenHeaderHelpers = async (mcpServers, dir) => {
+  const servers = mcpServers
+    .map((server, index) => ({ server, index, templates: getTokenHeaderTemplates(server) }))
+    .filter((item) => item.templates);
+  if (servers.length === 0) return new Map();
+
+  const scriptPath = join(dir, 'headers-helper.mjs');
+  await writePrivateFile(scriptPath, HEADER_TOKEN_HELPER_SOURCE);
+  const helpers = new Map();
+  for (const { server, index, templates } of servers) {
+    const templatesPath = join(dir, `headers-${index}.json`);
+    await writePrivateFile(templatesPath, JSON.stringify(templates));
+    helpers.set(server.name, {
+      command: [
+        QUOTE_SHELL_ARGUMENT(process.execPath),
+        QUOTE_SHELL_ARGUMENT(scriptPath),
+        QUOTE_SHELL_ARGUMENT(templatesPath),
+      ].join(' '),
+      headerNames: Object.keys(templates),
+    });
+  }
+  return helpers;
+};
+
 const buildMcpConfig = (mcpServers, ctx = {}) => {
   // Shape: `{ mcpServers: { <name>: { ... } } }` — the standard MCP client
   // config, which claude's `--mcp-config` reads directly.
@@ -367,7 +431,13 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
         label: 'claude',
       }).env;
     }
-    if (server.headers) entry.headers = { ...server.headers };
+    const headerHelper = ctx.dynamicHeaderHelpers?.get(server.name);
+    if (server.headers) {
+      const headers = { ...server.headers };
+      for (const headerName of headerHelper?.headerNames || []) delete headers[headerName];
+      if (Object.keys(headers).length > 0 || !headerHelper) entry.headers = headers;
+    }
+    if (headerHelper) entry.headersHelper = headerHelper.command;
     mcpServersMap[server.name] = entry;
   }
   return { mcpServers: mcpServersMap };
@@ -389,7 +459,14 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     // config — no second lifecycle to get wrong — and so it is inside the one
     // non-workspace path the Seatbelt profile admits.
     credential = writeCredentialFile(ctx.runtimeToken, { agentName: ctx.agentName || 'agent', root: dir });
-    const config = buildMcpConfig(mcpServers, { ...ctx, credentialFile: credential?.path || null });
+    const dynamicHeaderHelpers = credential?.path
+      ? await createTokenHeaderHelpers(mcpServers, dir)
+      : new Map();
+    const config = buildMcpConfig(mcpServers, {
+      ...ctx,
+      credentialFile: credential?.path || null,
+      dynamicHeaderHelpers,
+    });
     await writeFile(
       file,
       JSON.stringify(config, null, 2),
@@ -401,12 +478,13 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     const expansionEnv = buildMcpExpansionEnv(config, {
       ...ctx,
       credentialFile: credential?.path || null,
+      headersHelperUsesCredentialFile: dynamicHeaderHelpers.size > 0,
     });
     if (expansionEnv[CREDENTIAL_KEY]) {
       // eslint-disable-next-line no-console
       console.warn(
         `[claude] this declaration references ${CREDENTIAL_KEY} in a field claude `
-        + 'substitutes literally (args, url, headers, or a larger string), so the '
+        + 'substitutes literally (args, url, unsupported headers, or a larger string), so the '
         + "value stays in claude's environment for this spawn and every MCP child "
         + `inherits it. Put the credential on the entry's env to get the file channel.`,
       );
@@ -501,6 +579,23 @@ const prepareArgv = async (innerArgv, ctx) => {
   // get the jail only — a derived Linux seat kept Bash/Write/WebFetch and ran on
   // the operator's own Claude settings inside the namespace (Vera 69578).
   const publicBwrapSandbox = sandboxTrust === 'public' && sandboxMode === 'bwrap';
+  const commitHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_HOOKS_PATH || null;
+  const originalHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_ORIGINAL_HOOKS_PATH || null;
+  const commitHookExecutables = commitHooksPath
+    ? supportedGitHooks().map((hookName) => join(commitHooksPath, hookName))
+    : [];
+  const originalHookExecutables = originalHooksPath
+    ? supportedGitHooks()
+      .map((hookName) => join(originalHooksPath, hookName))
+      .filter((hookPath) => {
+        try {
+          accessSync(hookPath, constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      })
+    : [];
   // A public trust MUST resolve to an enforced mode. Absent mode is resolved
   // above; anything else that lands here (the literal 'none', a typo, a
   // non-string) used to fall through to the bare `claude` spawn below — an
@@ -539,7 +634,7 @@ const prepareArgv = async (innerArgv, ctx) => {
       claudePath: claudeBin,
       statePath: ctx.publicClaudeState.statePath,
       mcpConfigDir: ctx.mcpConfigDir,
-      executablePaths: mcpExecutables,
+      executablePaths: [...mcpExecutables, ...commitHookExecutables, ...originalHookExecutables],
     });
     return {
       cmd: wrapped[0],
@@ -568,7 +663,7 @@ const prepareArgv = async (innerArgv, ctx) => {
     const claudeBin = resolveClaudePath(claudeEnv);
     const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
       workspacePath: ctx.cwd,
-      readOnlyPaths: ctx.mcpConfigDir ? [ctx.mcpConfigDir] : [],
+      readOnlyPaths: [ctx.mcpConfigDir, commitHooksPath, originalHooksPath].filter(Boolean),
     });
     return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv };
   }
@@ -691,17 +786,21 @@ export default {
           agentName: ctx.agentName,
         });
       }
+      const claudeEnv = buildClaudeEnv(
+        ctx.env,
+        publicClaudeState,
+        mcpConfig?.expansionEnv,
+        mcpConfig?.credential?.path || null,
+      );
+      if (publicNativeSandbox && ctx.commitAttributionEnv) {
+        Object.assign(claudeEnv, ctx.commitAttributionEnv);
+      }
       const spawnCtx = {
         ...ctx,
         mcpConfigPath: mcpConfig?.file || null,
         mcpConfigDir: mcpConfig?.dir || null,
         publicClaudeState,
-        claudeEnv: buildClaudeEnv(
-          ctx.env,
-          publicClaudeState,
-          mcpConfig?.expansionEnv,
-          mcpConfig?.credential?.path || null,
-        ),
+        claudeEnv,
       };
       const { cmd, args, env } = await prepareArgv(baseArgs, spawnCtx);
       const stdout = await runClaude({

package/src/lib/adapters/codex.js

@@ -39,6 +39,7 @@
 
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
+import { accessSync, constants } from 'fs';
 import {
   chmod,
   lstat,
@@ -57,6 +58,7 @@ import {
   resolve as pathResolve,
 } from 'path';
 import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
@@ -296,13 +298,38 @@ const preparePublicCodexHome = async (ctx) => {
   return publicHome;
 };
 
-const publicPermissionProfileFlags = (mode) => {
+const publicPermissionProfileFlags = (
+  mode,
+  commitAttributionEnv = null,
+) => {
   if (!PUBLIC_SANDBOX_MODES.has(mode)) {
     throw new Error(
       `public codex agents require sandbox.mode=workspace or read-only, got ${mode || 'unset'}`,
     );
   }
   const workspaceAccess = mode === 'read-only' ? 'read' : 'write';
+  const commitHooksPath = commitAttributionEnv?.COMMONLY_AGENT_HOOKS_PATH || null;
+  const originalHooksPath = commitAttributionEnv?.COMMONLY_AGENT_ORIGINAL_HOOKS_PATH || null;
+  const originalHookPaths = originalHooksPath
+    ? supportedGitHooks()
+      .map((hookName) => join(originalHooksPath, hookName))
+      .filter((hookPath) => {
+        try {
+          accessSync(hookPath, constants.X_OK);
+          return true;
+        } catch {
+          return false;
+        }
+      })
+    : [];
+  // Preserve caller-supplied git config entries alongside the appended
+  // hooksPath entry. The explicit allowlist below admits only these concrete
+  // variable names, not arbitrary environment variables.
+  const gitConfigEnv = Object.keys(commitAttributionEnv || {})
+    .filter((name) => /^GIT_CONFIG_(?:COUNT|KEY_\d+|VALUE_\d+)$/.test(name));
+  const gitConfigKeySet = Object.entries(commitAttributionEnv || {})
+    .filter(([name]) => /^GIT_CONFIG_KEY_\d+$/.test(name))
+    .map(([name, value]) => `${toml(name)}=${toml(value)}`);
   const filesystem = [
     '":minimal"="read"',
     '"~/.commonly"="deny"',
@@ -313,16 +340,42 @@ const publicPermissionProfileFlags = (mode) => {
     '"~/.config"="deny"',
     '"/private/tmp"="deny"',
     `":workspace_roots"={"."="${workspaceAccess}",".commonly/**"="deny",".codex/**"="deny","*.env"="deny","*/*.env"="deny","*/*/*.env"="deny"}`,
+    ...(commitHooksPath ? [`${toml(commitHooksPath)}="read"`] : []),
+    ...originalHookPaths.map((hookPath) => `${toml(hookPath)}="read"`),
   ].join(',');
+  const shellEnvironment = [
+    'PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_*',
+    ...(commitHooksPath ? [
+      ...gitConfigEnv,
+      'COMMONLY_AGENT_GIT_CONFIG_INDEX',
+      'COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT',
+      'COMMONLY_AGENT_HOOKS_PATH',
+      'COMMONLY_AGENT_ORIGINAL_HOOKS_PATH',
+      'COMMONLY_AGENT_SEAT_NAME',
+      'COMMONLY_AGENT_SEAT_ID',
+      'COMMONLY_AGENT_ADAPTER',
+      'COMMONLY_AGENT_MODEL',
+      'COMMONLY_AGENT_EFFORT',
+    ] : []),
+  ];
   return [
     '-c', `default_permissions=${toml(PUBLIC_PERMISSION_PROFILE)}`,
     '-c', `permissions.${PUBLIC_PERMISSION_PROFILE}.filesystem={${filesystem}}`,
     '-c', `permissions.${PUBLIC_PERMISSION_PROFILE}.network.enabled=false`,
     // The MCP launcher receives explicitly forwarded env_vars separately.
-    // Model-generated shell commands inherit only a small non-secret core.
-    '-c', 'shell_environment_policy.inherit="core"',
+    // `core` drops explicit GIT_CONFIG_* and hook metadata before include_only
+    // can admit them. When attribution is active, inherit all then constrain
+    // model shells to the exact allowlist below; keep Codex's default secret
+    // filters enabled.
+    '-c', `shell_environment_policy.inherit="${commitHooksPath ? 'all' : 'core'}"`,
     '-c', 'shell_environment_policy.ignore_default_excludes=false',
-    '-c', 'shell_environment_policy.include_only=["PATH","HOME","TMPDIR","LANG","LC_*"]',
+    '-c', `shell_environment_policy.include_only=${JSON.stringify(shellEnvironment)}`,
+    // Codex's default name filter treats GIT_CONFIG_KEY_n as sensitive. Set
+    // only those key names after filtering; their corresponding values stay
+    // in the allowlisted environment instead of riding argv.
+    ...(gitConfigKeySet.length
+      ? ['-c', `shell_environment_policy.set={${gitConfigKeySet.join(',')}}`]
+      : []),
   ];
 };
 
@@ -337,6 +390,7 @@ const buildArgs = ({
   publicSandboxMode = null,
   model = null,
   effort = null,
+  commitAttributionEnv = null,
 }) => {
   const publicSandbox = publicSandboxMode !== null;
   // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
@@ -356,7 +410,10 @@ const buildArgs = ({
     ? [
       '--ignore-user-config',
       '--ignore-rules',
-      ...publicPermissionProfileFlags(publicSandboxMode),
+      ...publicPermissionProfileFlags(
+        publicSandboxMode,
+        commitAttributionEnv,
+      ),
     ]
     : ['--dangerously-bypass-approvals-and-sandbox'];
   const common = [
@@ -562,6 +619,7 @@ export default {
         publicSandboxMode,
         model: ctx.environment?.model,
         effort: ctx.environment?.effort,
+        commitAttributionEnv: ctx.commitAttributionEnv,
       });
       const childEnv = { ...(ctx.env || process.env), ...mcp.forwardedEnv };
       // Derived from the process environment, so the bootstrap export has to be
@@ -573,6 +631,9 @@ export default {
         credentialFile: credential?.path || null,
         keepsValue: mcp.forwardedEnv[CREDENTIAL_KEY] !== undefined,
       });
+      if (publicSandboxMode !== null && ctx.commitAttributionEnv) {
+        Object.assign(childEnv, ctx.commitAttributionEnv);
+      }
       if (publicSandboxMode !== null) {
         childEnv.CODEX_HOME = await preparePublicCodexHome(ctx);
       }

package/src/lib/api.js

@@ -20,14 +20,34 @@ export const sessionExpiredMessage = ({ instanceKey, baseUrl }) => (
   `Session for ${instanceKey} (${baseUrl}) has expired.\nRun: commonly login --instance ${instanceKey}`
 );
 
+// A non-JSON error body is usually an edge proxy's HTML page; a Cloudflare
+// tunnel error is ~120 lines, and the message used to be all of them, so every
+// failed poll dumped a whole page into the agent log. The message names the
+// page by its <title>; err.body keeps the full text for callers that classify it.
+const MAX_TEXT_ERROR = 300;
+const summarizeTextError = (text, status) => {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return null;
+  if (/^<(?:!doctype|html)/i.test(trimmed) || /<html[\s>]/i.test(trimmed)) {
+    const title = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, ' ').trim();
+    return title ? `HTTP ${status}: ${title}` : `HTTP ${status} (HTML error page)`;
+  }
+  const line = trimmed.replace(/\s+/g, ' ');
+  return line.length > MAX_TEXT_ERROR ? `${line.slice(0, MAX_TEXT_ERROR)}…` : line;
+};
+
 const handleResponse = async (res, session = null) => {
   const text = await res.text();
   let body;
-  try { body = JSON.parse(text); } catch { body = { message: text }; }
+  let isJson = true;
+  try { body = JSON.parse(text); } catch { body = { message: text }; isJson = false; }
   if (!res.ok) {
+    const serverMessage = isJson
+      ? body?.error || body?.message || body?.msg
+      : summarizeTextError(text, res.status);
     const msg = res.status === 401 && session && knownSessionFailure(body)
       ? sessionExpiredMessage(session)
-      : body?.error || body?.message || body?.msg || `HTTP ${res.status}`;
+      : serverMessage || `HTTP ${res.status}`;
     const err = new Error(msg);
     err.status = res.status;
     err.body = body;

package/src/lib/commit-attribution.js

@@ -0,0 +1,201 @@
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import {
+  accessSync,
+  constants,
+  mkdtempSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const GIT_HOOKS = [
+  'applypatch-msg',
+  'pre-applypatch',
+  'post-applypatch',
+  'pre-commit',
+  'pre-merge-commit',
+  'prepare-commit-msg',
+  'commit-msg',
+  'post-commit',
+  'pre-rebase',
+  'post-checkout',
+  'post-merge',
+  'pre-push',
+  'pre-receive',
+  'update',
+  'proc-receive',
+  'post-receive',
+  'post-update',
+  'reference-transaction',
+  'push-to-checkout',
+  'pre-auto-gc',
+  'post-rewrite',
+  'sendemail-validate',
+  'fsmonitor-watchman',
+  'p4-pre-submit',
+  'p4-prepare-changelist',
+  'p4-changelist',
+  'p4-post-changelist',
+  'post-index-change',
+];
+
+const cleanSingleLine = (value, fallback) => {
+  let cleaned = '';
+  for (const character of String(value ?? '')) {
+    const codePoint = character.codePointAt(0);
+    cleaned += codePoint <= 0x1f || codePoint === 0x7f ? ' ' : character;
+  }
+  cleaned = cleaned
+    .replace(/[<>]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return cleaned || fallback;
+};
+
+// Use an email-local-part-safe reversible id. URI escapes introduce `%`, which
+// Git does not accept in a co-author trailer address. Keep the reversible form
+// while it fits the 64-character email local-part limit; longer identities use
+// a stable hash so GitHub can still lift the co-author on squash.
+const seatAddressId = (agentName, instanceId) => {
+  const identity = JSON.stringify([
+    cleanSingleLine(agentName, 'agent'),
+    cleanSingleLine(instanceId, 'default'),
+  ]);
+  const reversibleId = Buffer.from(identity).toString('base64url');
+  if (reversibleId.length <= 64) return reversibleId;
+  return `sha256-${createHash('sha256').update(identity).digest('base64url')}`;
+};
+
+const resolveOriginalHooksPath = (cwd, env) => {
+  const result = spawnSync(
+    'git',
+    ['rev-parse', '--path-format=absolute', '--git-path', 'hooks'],
+    { cwd, env, encoding: 'utf8' },
+  );
+  if (result.status !== 0 || !result.stdout.trim()) return null;
+  const hooksPath = resolve(result.stdout.trim());
+  try {
+    return statSync(hooksPath).isDirectory() ? hooksPath : null;
+  } catch {
+    return null;
+  }
+};
+
+const resolveGitConfigCount = (env) => {
+  const raw = env.GIT_CONFIG_COUNT ?? '0';
+  if (!/^(0|[1-9]\d*)$/.test(String(raw))) {
+    throw new Error(`cannot enable commit attribution: GIT_CONFIG_COUNT is invalid (${raw})`);
+  }
+  const count = Number(raw);
+  if (!Number.isSafeInteger(count)) {
+    throw new Error('cannot enable commit attribution: GIT_CONFIG_COUNT is out of range');
+  }
+  return count;
+};
+
+const wrapperHook = () => `#!/bin/sh
+# Commonly CLI commit attribution. Preserve the repository's configured hooks.
+hook_name=\${0##*/}
+config_index=$COMMONLY_AGENT_GIT_CONFIG_INDEX
+base_count=$COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT
+case "$config_index:$base_count" in
+  *[!0-9:]*|:*) exit 1 ;;
+esac
+GIT_CONFIG_COUNT=$base_count
+export GIT_CONFIG_COUNT
+unset "GIT_CONFIG_KEY_$config_index" "GIT_CONFIG_VALUE_$config_index"
+
+original_hooks=\${COMMONLY_AGENT_ORIGINAL_HOOKS_PATH:-}
+if [ -n "$original_hooks" ] && [ "$original_hooks" != "$COMMONLY_AGENT_HOOKS_PATH" ]; then
+  original_hook="$original_hooks/$hook_name"
+  if [ -x "$original_hook" ]; then
+    "$original_hook" "$@"
+    hook_status=$?
+    if [ "$hook_status" -ne 0 ]; then
+      exit "$hook_status"
+    fi
+  fi
+fi
+
+if [ "$hook_name" = "prepare-commit-msg" ] && [ -n "$1" ]; then
+  git interpret-trailers --in-place --if-exists=addIfDifferent \\
+    --trailer "Co-authored-by: $COMMONLY_AGENT_SEAT_NAME <$COMMONLY_AGENT_SEAT_ID@agents.commonly.invalid>" \\
+    --trailer "Agent-Model: $COMMONLY_AGENT_ADAPTER/$COMMONLY_AGENT_MODEL/$COMMONLY_AGENT_EFFORT" \\
+    "$1"
+  exit $?
+fi
+exit 0
+`;
+
+/**
+ * Install a per-spawn Git hook proxy and return an environment for the CLI
+ * child. The proxy delegates every standard hook to the repository's original
+ * hook directory, then adds Commonly trailers after an existing
+ * prepare-commit-msg hook has had its say.
+ */
+export const prepareCommitAttribution = ({
+  cwd,
+  env = process.env,
+  agentName,
+  displayName,
+  instanceId = 'default',
+  adapter,
+  model,
+  effort,
+}) => {
+  const configIndex = resolveGitConfigCount(env);
+  const originalHooksPath = resolveOriginalHooksPath(cwd, env);
+  const hooksDirectory = mkdtempSync(join(tmpdir(), 'commonly-agent-hooks-'));
+  try {
+    const hookSource = wrapperHook();
+    for (const hookName of GIT_HOOKS) {
+      const hookPath = join(hooksDirectory, hookName);
+      writeFileSync(hookPath, hookSource, { encoding: 'utf8', mode: 0o700 });
+      accessSync(hookPath, constants.X_OK);
+    }
+  } catch (error) {
+    rmSync(hooksDirectory, { recursive: true, force: true });
+    throw error;
+  }
+
+  const safeAdapter = cleanSingleLine(adapter, 'unknown');
+  const metadataEnv = {
+    COMMONLY_AGENT_GIT_CONFIG_INDEX: String(configIndex),
+    COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT: String(configIndex),
+    COMMONLY_AGENT_HOOKS_PATH: hooksDirectory,
+    ...(originalHooksPath ? { COMMONLY_AGENT_ORIGINAL_HOOKS_PATH: originalHooksPath } : {}),
+    COMMONLY_AGENT_SEAT_NAME: cleanSingleLine(displayName || agentName, 'agent'),
+    COMMONLY_AGENT_SEAT_ID: seatAddressId(agentName, instanceId),
+    COMMONLY_AGENT_ADAPTER: safeAdapter,
+    COMMONLY_AGENT_MODEL: cleanSingleLine(model, 'default'),
+    COMMONLY_AGENT_EFFORT: cleanSingleLine(effort, 'default'),
+  };
+  const attributionEnv = {
+    ...env,
+    GIT_CONFIG_COUNT: String(configIndex + 1),
+    [`GIT_CONFIG_KEY_${configIndex}`]: 'core.hooksPath',
+    [`GIT_CONFIG_VALUE_${configIndex}`]: hooksDirectory,
+    ...metadataEnv,
+  };
+  const sandboxEnv = {
+    ...metadataEnv,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: 'core.hooksPath',
+    GIT_CONFIG_VALUE_0: hooksDirectory,
+    COMMONLY_AGENT_GIT_CONFIG_INDEX: '0',
+    COMMONLY_AGENT_GIT_CONFIG_BASE_COUNT: '0',
+  };
+
+  return {
+    env: attributionEnv,
+    sandboxEnv,
+    hooksDirectory,
+    cleanup: () => rmSync(hooksDirectory, { recursive: true, force: true }),
+  };
+};
+
+export const supportedGitHooks = () => [...GIT_HOOKS];