@commonlyai/cli 0.1.183 → 0.1.185

package/node_modules/@commonlyai/seats/src/record/format.js

@@ -371,7 +371,13 @@ const CHECKS = {
     optionalArgsDigest(data, 'tool.call');
     return data;
   },
-  'credential.granted': (data) => ({ ...data, names: envNames(data.names ?? [], 'credential.granted.names') }),
+  'credential.granted': (data) => {
+    const names = envNames(data.names ?? [], 'credential.granted.names');
+    if (data.injected === undefined) return { ...data, names };
+    const injected = envNames(data.injected, 'credential.granted.injected');
+    if (!injected.every((name) => names.includes(name))) fail('credential.granted.injected must be a subset of names');
+    return { ...data, names, injected };
+  },
   'credential.denied': (data) => {
     envNames([data.name], 'credential.denied.name');
     return data;

package/node_modules/@commonlyai/seats/src/trace/events.js

@@ -23,8 +23,8 @@ export const EVENT_TYPES = Object.freeze([
   'usage', // { inputTokens?, outputTokens?, totalTokens?, cost? }  null-not-zero when unknown
   'liveness.stalled', // { idleMs, windowMs }
   'liveness.recovery', // { action: 'cancel'|'kill'|'retry', attempt }
-  'credential.granted', // { names: [...] }  names only, never values
-  'credential.denied', // { name, reason?: 'not_granted'|'unresolved'|'too_short' }
+  'credential.granted', // { names: [...], injected?: [...] }  names only, never values
+  'credential.denied', // { name, reason?: 'not_granted'|'unresolved'|'too_short'|'no_upstream' }
   'process.exited', // { code, signal }
   // Record kinds with no earlier trace name (docs/record-v1.md has the full data).
   'task.claimed', // { leaseUntil? }  mirrors the board's claim; the board stays the source of truth

package/node_modules/@commonlyai/seats/src/valet/env.js

@@ -19,6 +19,7 @@ import { traceOf } from '../trace/events.js';
 import { runFailure } from '../failures.js';
 import { MIN_CREDENTIAL_LENGTH } from '../upstream-refusal.js';
 import { validateGrant } from './grant.js';
+import { startProviderProxy } from '../wire/provider-proxy.js';
 
 // Same spirit as the goose adapter's SAFE_ENV: locale, terminal and TLS trust
 // only. USER/LOGNAME are left out on purpose; they name the account whose
@@ -104,8 +105,8 @@ const grantIssued = (meta) => {
 };
 
 /**
- * prepareRunEnv({ grant, baseEnv, resolveSecret, root?, require?, trace?, ctx?, grantMeta? })
- *   → { env, home, cleanup, granted: [names], grantId? }
+ * prepareRunEnv({ grant, baseEnv, resolveSecret, root?, require?, trace?, ctx?, grantMeta?, upstreams? })
+ *   → { env, home, cleanup, granted: [names], injected: { NAME: { baseURL, wire } }, grantId? }
  *
  * `require` lists credential names the adapter cannot run without; one the
  * grant does not name fails the run as credential_denied before any spawn.
@@ -114,14 +115,25 @@ const grantIssued = (meta) => {
  * silently lacks its key fails later and less legibly, and a value that short
  * would slip past the refusal-text reader's redaction.
  *
+ * A credential the grant marks `inject: true` never reaches the env. The host
+ * names its provider in `upstreams[NAME]` ({ baseURL, wire }, wire defaulting
+ * to openai-chat); the run gets a loopback provider proxy holding the value in
+ * memory, env[NAME] becomes that proxy's token, and `injected[NAME].baseURL`
+ * is where the host points the CLI. cleanup() closes the proxies. One with no
+ * upstream fails as credential_denied (no_upstream) before it is resolved.
+ * The proxy listens on 127.0.0.1, so a run without the host's network
+ * (bwrap --unshare-net) cannot reach it yet.
+ *
  * Events go to `trace`, else ctx.trace: grant.issued (only with grantMeta,
- * first), then credential.granted {names} or credential.denied {name, reason}.
+ * first), then credential.granted {names, injected?} or credential.denied
+ * {name, reason}. `injected` lists the names held by a proxy; the rest of
+ * `names` are held by the run.
  * Values never enter an event or a message, and a hook that offers
- * redact(values) is handed the resolved values so the record can scrub them
- * out of agent text too.
+ * redact(values) is handed the resolved values and each proxy token, so the
+ * record can scrub them out of agent text too.
  */
 export const prepareRunEnv = async ({
-  grant, baseEnv = {}, resolveSecret, root, require: required = [], trace, ctx, grantMeta,
+  grant, baseEnv = {}, resolveSecret, root, require: required = [], trace, ctx, grantMeta, upstreams = {},
 } = {}) => {
   const valid = validateGrant(grant);
   const hook = trace && typeof trace.emit === 'function' ? trace : traceOf(ctx);
@@ -132,6 +144,7 @@ export const prepareRunEnv = async ({
     not_granted: 'is not in the run grant',
     unresolved: 'could not be resolved',
     too_short: `resolved to a value shorter than ${MIN_CREDENTIAL_LENGTH} characters`,
+    no_upstream: 'is marked inject, but the host named no upstream for it',
   };
   const deny = (name, reason, values) => {
     hook.emit('credential.denied', { name, reason });
@@ -143,11 +156,18 @@ export const prepareRunEnv = async ({
   if (missing) throw deny(missing, 'not_granted', []);
 
   const { home, dirs } = await makeHome(root);
-  const cleanup = () => rm(home, { recursive: true, force: true });
+  const proxies = [];
+  const cleanup = async () => {
+    await Promise.all(proxies.splice(0).map((proxy) => proxy.close()));
+    await rm(home, { recursive: true, force: true });
+  };
   const env = { ...pickBaseEnv(baseEnv, realHomes), HOME: home, ...dirs };
   const values = [];
+  const injected = {};
   try {
     for (const spec of valid.credentials) {
+      const upstream = spec.inject ? upstreams[spec.name] : undefined;
+      if (spec.inject && !upstream) throw deny(spec.name, 'no_upstream', values);
       let value;
       // A resolver's error text may quote the secret it failed on; drop it.
       try { value = await resolveOne(spec, { baseEnv, resolveSecret }); } catch { value = undefined; }
@@ -156,14 +176,26 @@ export const prepareRunEnv = async ({
       // refusal-text reader would not redact it. Refuse it here, before spawn.
       if (value.length < MIN_CREDENTIAL_LENGTH) throw deny(spec.name, 'too_short', values);
       values.push(value);
-      env[spec.name] = value;
+      if (upstream) {
+        const wire = upstream.wire ?? 'openai-chat';
+        const proxy = await startProviderProxy({
+          provider: { baseURL: upstream.baseURL }, keyMaterial: value, wire, adapterLabel: 'Valet',
+        });
+        proxies.push(proxy);
+        env[spec.name] = proxy.token;
+        injected[spec.name] = { baseURL: proxy.baseURL, wire };
+      } else {
+        env[spec.name] = value;
+      }
     }
   } catch (error) {
     await cleanup();
     throw error;
   }
-  if (typeof hook.redact === 'function') hook.redact(values);
+  // A proxy token authorizes provider calls until cleanup, so the record scrubs it too.
+  if (typeof hook.redact === 'function') hook.redact([...values, ...proxies.map((proxy) => proxy.token)]);
   const names = valid.credentials.map((c) => c.name);
-  hook.emit('credential.granted', { names });
-  return { env, home, cleanup, granted: names, ...(issued ? { grantId: issued.grantId } : {}) };
+  const proxied = Object.keys(injected);
+  hook.emit('credential.granted', proxied.length ? { names, injected: proxied } : { names });
+  return { env, home, cleanup, granted: names, injected, ...(issued ? { grantId: issued.grantId } : {}) };
 };

package/node_modules/@commonlyai/seats/src/valet/grant.js

@@ -3,7 +3,7 @@
  * and which tool calls it may make without asking, only after asking, or never.
  *
  *   {
- *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref? }],
+ *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref?, inject? }],
  *     tools: { allow: [pattern], ask: [pattern], deny: [pattern] },
  *   }
  *
@@ -11,6 +11,10 @@
  * path in `ref`; `from: 'resolver'` asks the host's resolveSecret(name, spec),
  * with `ref` as an opaque hint for it.
  *
+ * `inject: true` keeps the value out of the run: its env gets a per-run proxy
+ * token under the name instead, and a loopback provider proxy adds the real
+ * key to outbound requests. Default false: the run holds the value.
+ *
  * A tool pattern is `<kind>` or `<kind>:<title glob>`, where kind is one of
  * ACP's ToolKind values or `*`. `execute` matches every execute call;
  * `execute:git status*` matches execute calls whose title starts that way;
@@ -61,8 +65,8 @@ const parsePattern = (pattern, where) => {
 const validateCredential = (credential, index, seen) => {
   const where = `credentials[${index}]`;
   if (!isPlainObject(credential)) fail(`${where} must be an object`);
-  refuseUnknownKeys(credential, ['name', 'from', 'ref'], `${where}.`);
-  const { name, from, ref } = credential;
+  refuseUnknownKeys(credential, ['name', 'from', 'ref', 'inject'], `${where}.`);
+  const { name, from, ref, inject } = credential;
   if (typeof name !== 'string' || !ENV_NAME.test(name)) fail(`${where}.name must be an ENV_NAME (A-Z, 0-9, _)`);
   if (RESERVED_NAME.test(name)) fail(`${where}.name ${name} is reserved for the run env`);
   if (seen.has(name)) fail(`${where}.name ${name} is granted twice`);
@@ -71,7 +75,8 @@ const validateCredential = (credential, index, seen) => {
   if (ref !== undefined && (typeof ref !== 'string' || !ref)) fail(`${where}.ref must be a non-empty string`);
   if (from === 'env' && ref !== undefined && !ENV_NAME.test(ref)) fail(`${where}.ref must be an ENV_NAME for from: env`);
   if (from === 'file' && (ref === undefined || !ref.startsWith('/'))) fail(`${where}.ref must be an absolute path for from: file`);
-  return Object.freeze(ref === undefined ? { name, from } : { name, from, ref });
+  if (inject !== undefined && typeof inject !== 'boolean') fail(`${where}.inject must be true or false`);
+  return Object.freeze({ name, from, ...(ref === undefined ? {} : { ref }), ...(inject ? { inject } : {}) });
 };
 
 /** Validate and freeze a grant. Throws on the first problem; never repairs one. */

package/node_modules/@commonlyai/seats/src/wire/provider-proxy.js

@@ -1,6 +1,6 @@
 import { Transform } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
-/** The per-spawn loopback proxy shared by OpenAI-compatible CLI adapters. */
+/** The per-spawn loopback proxy that holds a provider key for a CLI (OpenAI chat, Anthropic Messages, OpenAI Responses). */
 import { randomBytes, timingSafeEqual } from 'crypto';
 import { constants as fsConstants, realpathSync } from 'fs';
 import { createServer, request as httpRequest } from 'http';
@@ -167,11 +167,30 @@ const readProviderKey = async (keyFile, adapterLabel) => {
   }
 };
 
+// The routes a CLI on each wire may call, relative to the configured base
+// path, and the header the real key goes out in. Anything else is refused.
+const WIRES = Object.freeze({
+  'openai-chat': { routes: [['POST', 'chat/completions'], ['GET', 'models']], auth: 'bearer' },
+  'anthropic-messages': {
+    routes: [['POST', 'v1/messages'], ['POST', 'v1/messages/count_tokens'], ['GET', 'v1/models']],
+    auth: 'x-api-key',
+  },
+  'openai-responses': { routes: [['POST', 'responses'], ['GET', 'models']], auth: 'bearer' },
+});
+export const PROVIDER_WIRES = Object.freeze(Object.keys(WIRES));
+
+const presents = (value, expected) => {
+  const supplied = Buffer.from(typeof value === 'string' ? value : '');
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+};
+
 export const startProviderProxy = async ({
-  provider, keyFile, keyMaterial, tokenFile, socketPath, isolatedPort, adapterLabel = 'OpenCode',
+  provider, keyFile, keyMaterial, tokenFile, socketPath, isolatedPort, adapterLabel = 'OpenCode', wire = 'openai-chat',
   // When set, every completion must request this model and be served by it.
   pinnedModel,
 }) => {
+  const wireSpec = WIRES[wire];
+  if (!wireSpec) throw new Error(`${adapterLabel} provider wire must be one of ${PROVIDER_WIRES.join(', ')}`);
   if (pinnedModel !== undefined && (typeof pinnedModel !== 'string' || !pinnedModel.trim())) {
     throw new Error(`${adapterLabel} pinnedModel must be a non-empty string`);
   }
@@ -189,8 +208,13 @@ export const startProviderProxy = async ({
   const upstreamKey = keyMaterial === undefined ? await readProviderKey(keyFile, adapterLabel) : keyMaterial;
   if (typeof upstreamKey !== 'string' || !upstreamKey || /[\r\n]/.test(upstreamKey)) throw new Error('Invalid provider key');
   const proxyToken = randomBytes(32).toString('base64url');
-  await writeFile(tokenFile, proxyToken, { encoding: 'utf8', mode: 0o600 });
-  await chmod(tokenFile, 0o600);
+  // A caller that hands the token to its child in memory needs no file.
+  if (tokenFile) {
+    await writeFile(tokenFile, proxyToken, { encoding: 'utf8', mode: 0o600 });
+    await chmod(tokenFile, 0o600);
+  }
+  const bearerToken = Buffer.from(`Bearer ${proxyToken}`);
+  const bareToken = Buffer.from(proxyToken);
 
   const logRefusedRequest = (method, requestPath) => {
     let normalizedPath = '/';
@@ -204,29 +228,34 @@ export const startProviderProxy = async ({
     process.stderr.write(`[${adapterLabel.toLowerCase()}] provider proxy refused ${safeMethod} ${normalizedPath}\n`);
   };
 
+  // A refusal answers before the request body has been read. A keep-alive
+  // client that reuses that socket can have its next request reset, so every
+  // refusal on every wire also closes the connection.
+  const refuse = (incoming, outgoing, status, headers = {}, body = undefined) => {
+    incoming.resume();
+    outgoing.writeHead(status, { ...headers, connection: 'close' });
+    outgoing.end(body);
+  };
+
   const server = createServer((incoming, outgoing) => {
-    const supplied = Buffer.from(incoming.headers.authorization || '');
-    const expected = Buffer.from(`Bearer ${proxyToken}`);
-    if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
-      incoming.resume();
-      outgoing.writeHead(401).end();
+    // Anthropic clients send their key as x-api-key, the others as a Bearer.
+    if (!presents(incoming.headers.authorization, bearerToken)
+      && !presents(incoming.headers['x-api-key'], bareToken)) {
+      refuse(incoming, outgoing, 401);
       return;
     }
     if (!['GET', 'POST'].includes(incoming.method || '')) {
-      incoming.resume();
-      outgoing.writeHead(405).end();
+      refuse(incoming, outgoing, 405);
       return;
     }
     const rejectRoute = (path) => {
       logRefusedRequest(incoming.method, path);
-      incoming.resume();
-      outgoing.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-      outgoing.end(`Unsupported provider request: ${incoming.method || 'UNKNOWN'} ${path}`);
+      refuse(incoming, outgoing, 403, { 'content-type': 'text/plain; charset=utf-8' },
+        `Unsupported provider request: ${incoming.method || 'UNKNOWN'} ${path}`);
     };
     const rejectBadRequest = () => {
       logRefusedRequest(incoming.method, incoming.url);
-      incoming.resume();
-      outgoing.writeHead(400).end();
+      refuse(incoming, outgoing, 400);
     };
 
     let target;
@@ -241,8 +270,8 @@ export const startProviderProxy = async ({
         return;
       }
       // The CLI owns this local request path, so never use it as an outbound
-      // URL. The OpenAI-compatible chat provider needs only these fixed routes;
-      // parse the incoming URL against a loopback sentinel, then select a
+      // URL. Each wire needs only the fixed routes in WIRES; parse the
+      // incoming URL against a loopback sentinel, then select a
       // constant endpoint after matching the configured base path exactly.
       // This keeps a CLI request from turning the proxy into an arbitrary
       // path/URL fetcher (including paths on a local provider host).
@@ -252,17 +281,13 @@ export const startProviderProxy = async ({
         return;
       }
       const configuredPath = basePath === '/' ? '' : basePath;
-      let endpoint;
-      if (incoming.method === 'POST'
-        && requested.pathname === `${configuredPath}/chat/completions`) {
-        endpoint = 'chat/completions';
-      } else if (incoming.method === 'GET'
-        && requested.pathname === `${configuredPath}/models`) {
-        endpoint = 'models';
-      } else {
+      const route = wireSpec.routes.find(([method, path]) => incoming.method === method
+        && requested.pathname === `${configuredPath}/${path}`);
+      if (!route) {
         rejectRoute(requested.pathname);
         return;
       }
+      const endpoint = route[1];
       target = {
         path: `${configuredPath}/${endpoint}`,
         protocol: upstream.protocol,
@@ -281,7 +306,8 @@ export const startProviderProxy = async ({
         'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade',
         'x-api-key',
       ].includes(name.toLowerCase())));
-    headers.authorization = `Bearer ${upstreamKey}`;
+    if (wireSpec.auth === 'x-api-key') headers['x-api-key'] = upstreamKey;
+    else headers.authorization = `Bearer ${upstreamKey}`;
     headers.host = target.host;
     headers['accept-encoding'] = 'identity';
     const pinned = pinnedModel !== undefined && target.path.endsWith('/chat/completions');
@@ -378,6 +404,12 @@ export const startProviderProxy = async ({
     });
   });
 
+  // A WebSocket client (codex on the Responses wire) falls back to HTTP SSE on
+  // 426. Nothing is relayed over an upgrade, so no token check is needed first.
+  server.on('upgrade', (_incoming, socket) => {
+    socket.end('HTTP/1.1 426 Upgrade Required\r\nconnection: close\r\ncontent-length: 0\r\n\r\n');
+  });
+
   await new Promise((resolve, reject) => {
     server.once('error', reject);
     const started = () => {
@@ -399,6 +431,7 @@ export const startProviderProxy = async ({
   const proxyBaseURL = new URL(upstream.pathname, `http://127.0.0.1:${port}`).toString();
   return {
     baseURL: proxyBaseURL,
+    token: proxyToken,
     tokenFile,
     socketPath,
     port,

package/package.json

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

package/src/lib/adapters/claude.js

@@ -55,8 +55,10 @@ import {
   lstat,
   mkdir,
   mkdtemp,
+  open,
   readFile,
   readlink,
+  rename,
   rm,
   symlink,
   unlink,
@@ -208,6 +210,29 @@ const statOrNull = async (path) => {
   }
 };
 
+// The non-secret account metadata Claude needs from ~/.claude.json to find its
+// login, and nothing else from that file.
+const claudeAuthMetadata = async () => {
+  const operatorConfigPath = join(homedir(), '.claude.json');
+  const sourceStat = await statOrNull(operatorConfigPath);
+  let source = {};
+  if (sourceStat) {
+    if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+      throw new Error(`refusing non-regular operator Claude config: ${operatorConfigPath}`);
+    }
+    try {
+      source = JSON.parse(await readFile(operatorConfigPath, 'utf8'));
+    } catch (err) {
+      throw new Error(`failed to read operator Claude auth metadata: ${err.message}`);
+    }
+  }
+  const sanitized = { hasCompletedOnboarding: true };
+  for (const key of ['installMethod', 'userID', 'machineID', 'oauthAccount']) {
+    if (source[key] !== undefined) sanitized[key] = source[key];
+  }
+  return sanitized;
+};
+
 // Claude's macOS OAuth credential lives in Keychain, but Claude also needs a
 // small amount of non-secret account metadata from ~/.claude.json to locate
 // it. Never bind or copy the operator's full file: it contains project paths,
@@ -248,35 +273,102 @@ const preparePublicClaudeState = async (ctx) => {
     await symlink(operatorKeychains, stateKeychains);
   }
 
-  const operatorConfigPath = join(homedir(), '.claude.json');
-  const sourceStat = await statOrNull(operatorConfigPath);
-  let source = {};
-  if (sourceStat) {
-    if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
-      throw new Error(`refusing non-regular operator Claude config: ${operatorConfigPath}`);
-    }
-    try {
-      source = JSON.parse(await readFile(operatorConfigPath, 'utf8'));
-    } catch (err) {
-      throw new Error(`failed to read operator Claude auth metadata: ${err.message}`);
-    }
-  }
-
-  const sanitized = {
-    hasCompletedOnboarding: true,
-  };
-  for (const key of ['installMethod', 'userID', 'machineID', 'oauthAccount']) {
-    if (source[key] !== undefined) sanitized[key] = source[key];
-  }
   await writeFile(
     configPath,
-    `${JSON.stringify(sanitized, null, 2)}\n`,
+    `${JSON.stringify(await claudeAuthMetadata(), null, 2)}\n`,
     { encoding: 'utf8', mode: 0o600 },
   );
   await chmod(configPath, 0o600);
   return { statePath, tmpPath, configPath };
 };
 
+// Writes a 0600 file into a directory the confined child can also write. The
+// directory must still be a real directory, and the file is written beside the
+// target and renamed over it, so a symlink the child left at either name is
+// replaced, never followed into another of the person's files.
+const replacePrivateFile = async (dir, name, content) => {
+  const dirStat = await statOrNull(dir);
+  if (!dirStat || dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+    throw new Error(`refusing to write Claude state into a non-directory: ${dir}`);
+  }
+  const target = join(dir, name);
+  const staged = join(dir, `.${name}.${randomUUID()}.tmp`);
+  await writeFile(staged, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  try {
+    await chmod(staged, 0o600);
+    await rename(staged, target);
+  } catch (err) {
+    await rm(staged, { force: true });
+    throw err;
+  }
+  return target;
+};
+
+// A workspace seat on Linux runs under bwrap, which has no keychain. Claude
+// Code on Linux keeps its login in <config dir>/.credentials.json, so the
+// seat's own state dir gets a copy of the person's, taken fresh each spawn:
+// their own credential on their own machine, the exposure the macOS keychain
+// arm already has. Only the copy is inside the jail. Nothing is written back:
+// the jail can write its copy, and a write-back would let it replace the
+// person's login with one of its choosing. A missing login removes the copy,
+// so a person who logged out is not still signed in here.
+const claudeLoginSource = (env) => join(
+  env?.CLAUDE_CONFIG_DIR || process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'),
+  '.credentials.json',
+);
+
+// Opened once, without following a symlink, and checked on the open handle,
+// so the file read is the file checked (a FIFO cannot hold the open either).
+const carryClaudeLogin = async (env, configDir) => {
+  const source = claudeLoginSource(env);
+  const refuse = () => new Error(`refusing a Claude login that is not a regular file: ${source}`);
+  let handle;
+  try {
+    handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      await rm(join(configDir, '.credentials.json'), { force: true });
+      return null;
+    }
+    if (err?.code === 'ELOOP') throw refuse();
+    throw err;
+  }
+  try {
+    if (!(await handle.stat()).isFile()) throw refuse();
+    return replacePrivateFile(configDir, '.credentials.json', await handle.readFile('utf8'));
+  } finally {
+    await handle.close();
+  }
+};
+
+// State for a workspace seat under bwrap: the same per-seat folder the macOS
+// path uses, outside the person's project, with the auth metadata whitelist
+// and the login copy. The jail binds this folder writable and makes it HOME,
+// so transcripts land here rather than in the project.
+const prepareWorkspaceBwrapClaudeState = async (ctx) => {
+  const identity = ctx.agentName || ctx.cwd || 'anonymous';
+  const identityHash = createHash('sha256').update(identity).digest('hex').slice(0, 20);
+  const statePath = ctx._publicClaudeState || publicClaudeStateRoot(identityHash);
+  const tmpPath = join(statePath, 'tmp');
+  const configDir = join(statePath, '.claude');
+  await mkdir(statePath, { recursive: true, mode: 0o700 });
+  await chmod(statePath, 0o700);
+  for (const dir of [tmpPath, configDir]) {
+    const existing = await statOrNull(dir);
+    if (existing && (existing.isSymbolicLink() || !existing.isDirectory())) {
+      throw new Error(`refusing Claude state path that is not a directory: ${dir}`);
+    }
+    if (!existing) await mkdir(dir, { mode: 0o700 });
+    await chmod(dir, 0o700);
+  }
+
+  const configPath = await replacePrivateFile(
+    statePath, '.claude.json', `${JSON.stringify(await claudeAuthMetadata(), null, 2)}\n`,
+  );
+  const loginPath = await carryClaudeLogin(ctx.env, configDir);
+  return { statePath, tmpPath, configPath, loginPath };
+};
+
 const buildClaudeEnv = (input, state, expansionEnv = {}, credentialFile = null, publicSeat = false) => {
   const source = input || process.env;
   const output = state || publicSeat ? {} : { ...source };
@@ -732,6 +824,9 @@ 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';
+  // A workspace seat on Linux: the same jail, with the workspace tier's policy
+  // and a HOME of its own outside the project.
+  const workspaceBwrapSandbox = sandboxTrust === 'workspace' && sandboxMode === 'bwrap';
   const commitHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_HOOKS_PATH || null;
   const originalHooksPath = ctx.commitAttributionEnv?.COMMONLY_AGENT_ORIGINAL_HOOKS_PATH || null;
   const commitHookExecutables = commitHooksPath
@@ -754,12 +849,6 @@ const prepareArgv = async (innerArgv, ctx) => {
   // non-string) used to fall through to the bare `claude` spawn below — an
   // unconfined seat with a public record, which is how a record can claim
   // confinement it never applies (Vera 69548).
-  // bwrap points the child's HOME at its folder (childHome below), so a
-  // workspace seat's transcripts would be written into the person's project.
-  if (sandboxTrust === 'workspace' && sandboxMode === 'bwrap') {
-    throw new Error('workspace Claude agents run on macOS only for now: under bwrap '
-      + 'their transcripts would be written into the project folder');
-  }
   if (isConfinedTrust(sandboxTrust) && !publicNativeSandbox && sandboxMode !== 'bwrap') {
     throw new Error(
       `${sandboxTrust} Claude agents require an enforced sandbox mode `
@@ -818,23 +907,71 @@ const prepareArgv = async (innerArgv, ctx) => {
     };
   }
 
-  if (publicBwrapSandbox) {
+  if (publicBwrapSandbox || workspaceBwrapSandbox) {
     // The mode is chosen here, so the mechanism is verified here: a missing
     // bwrap must fail the seat's derivation with an actionable message, not
     // every one of its spawns with a bare ENOENT (Wren 69586). On a non-Linux
     // host this reports the macOS-only message, same as the wrapper would.
     const bwrap = (ctx._detectBwrap || detectBwrap)();
     if (!bwrap.available) {
-      throw new Error(`public Claude agents require bwrap: ${bwrap.error}`);
+      throw new Error(`${sandboxTrust} Claude agents require bwrap: ${bwrap.error}`);
+    }
+    if (workspaceBwrapSandbox && !ctx.publicClaudeState) {
+      throw new Error('workspace Claude state was not prepared before argv construction');
     }
     innerArgv = [
       ...innerArgv,
-      ...buildPublicClaudePolicyArgs(allowedPatterns, { memoryWithheld: ctx.memoryWithheld === true }),
+      ...buildPublicClaudePolicyArgs(allowedPatterns, workspaceBwrapSandbox
+        ? { trust: sandboxTrust, allow: grants, memoryWithheld: ctx.memoryWithheld === true }
+        : { memoryWithheld: ctx.memoryWithheld === true }),
       ...(ctx.publicSkillArgs || []),
     ];
   } else if (allowedPatterns.length > 0) {
     innerArgv = [...innerArgv, '--allowedTools', ...allowedPatterns];
   }
+  if (workspaceBwrapSandbox) {
+    // Seatbelt denies writes under .git by path, present or not. A bwrap mount
+    // needs the path to exist, so a writable project without a .git could get
+    // one from the child, hooks included, that the person's next git command
+    // runs. Refuse that rather than create anything in their project.
+    if (grants.includes('write')) {
+      const gitEntry = await statOrNull(join(ctx.cwd, '.git'));
+      if (!gitEntry || gitEntry.isSymbolicLink()) {
+        throw new Error('workspace Claude agents with write on Linux need the project to be a git '
+          + `repository (run \`git init\` in ${ctx.cwd}), so its .git can be held read-only`);
+      }
+    }
+    const claudeBin = resolveClaudePath(claudeEnv);
+    const { statePath } = ctx.publicClaudeState;
+    let claudeInstall = null;
+    try {
+      claudeInstall = dirname(realpathSync(claudeBin));
+    } catch { /* an unresolvable binary fails at spawn with its own error */ }
+    const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
+      workspacePath: ctx.cwd,
+      workspaceReadOnly: !grants.includes('write'),
+      readOnlyWorkspaceEntries: ['.git'],
+      homePath: statePath,
+      writablePaths: [statePath],
+      readOnlyPaths: [
+        ctx.mcpConfigDir, commitHooksPath, originalHooksPath,
+        ...(ctx.mcpReadDirectories || []),
+        ...(ctx.workspaceGit?.readDirectories || []),
+        ...(ctx.workspaceGit?.readPaths || []),
+      ].filter(Boolean),
+      // The binaries the jail runs: claude (a user-local install is outside
+      // the default binds, and its link points into a versions folder), the
+      // node that runs the stdio MCP servers, and the git the history tool runs.
+      optionalReadOnlyPaths: [...new Set([
+        dirname(claudeBin), claudeInstall, dirname(process.execPath),
+        ctx.workspaceGit ? dirname(ctx.workspaceGit.executable) : null,
+        // A claude not found on PATH is left bare and fails at spawn; its
+        // dirname is '.', which is not a path to bind.
+      ].filter((p) => p && isAbsolute(p)))],
+    });
+    // TASK-440 reads the transcript from the HOME the child wrote under.
+    return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv, childHome: statePath };
+  }
   if (sandboxMode === 'bwrap') {
     const claudeBin = resolveClaudePath(claudeEnv);
     const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
@@ -974,6 +1111,8 @@ export default {
       && PUBLIC_SANDBOX_MODES.has(resolvePublicSandboxMode(ctx.environment?.sandbox));
     const publicBwrapSandbox = publicTrust
       && resolvePublicSandboxMode(ctx.environment?.sandbox) === 'bwrap';
+    const workspaceBwrapSandbox = ctx.environment?.sandbox?.trust === 'workspace'
+      && resolvePublicSandboxMode(ctx.environment?.sandbox) === 'bwrap';
     try {
       // Trust is normalized at entry (legacy `internal` reads as public). The
       // MCP policy follows trust alone, whatever confines the seat: a public
@@ -981,6 +1120,12 @@ export default {
       // (Rhea on #2247).
       if (publicNativeSandbox) {
         publicClaudeState = await preparePublicClaudeState(ctx);
+      } else if (workspaceBwrapSandbox) {
+        // Checked before the state is prepared, so a host that cannot run the
+        // jail never gets a copy of the login.
+        const bwrap = (ctx._detectBwrap || detectBwrap)();
+        if (!bwrap.available) throw new Error(`workspace Claude agents require bwrap: ${bwrap.error}`);
+        publicClaudeState = await prepareWorkspaceBwrapClaudeState(ctx);
       }
       if (publicTrust) {
         const prompt = await publicSkillPromptArgs(mountedSkills);

package/src/lib/sandbox/bwrap.js

@@ -161,7 +161,29 @@ export const wrapArgvWithBwrap = (innerArgv, env, opts = {}) => {
     flags.push('--ro-bind-try', p, p);
   }
 
-  flags.push('--bind', opts.workspacePath, opts.workspacePath);
+  // A HOME the adapter keeps outside the workspace (a workspace seat's state)
+  // is bound writable on its own, so the child's transcripts and login stay
+  // out of the person's project.
+  for (const p of opts.writablePaths || []) {
+    if (!p || !isAbsolute(p)) {
+      throw new Error('wrapArgvWithBwrap opts.writablePaths entries must be absolute paths');
+    }
+    flags.push('--bind', p, p);
+  }
+
+  flags.push(opts.workspaceReadOnly ? '--ro-bind' : '--bind', opts.workspacePath, opts.workspacePath);
+  // Entries held read-only inside a writable workspace (its .git). Bound after
+  // the workspace so they land on top of it. In a writable workspace a missing
+  // entry cannot be protected — the child could create it, and a planted
+  // .git/hooks runs on the person's next git command — so the bind is strict
+  // there and bwrap fails rather than starts.
+  for (const entry of opts.readOnlyWorkspaceEntries || []) {
+    if (!entry || isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) {
+      throw new Error('wrapArgvWithBwrap opts.readOnlyWorkspaceEntries entries must be relative names inside the workspace');
+    }
+    const p = join(opts.workspacePath, entry);
+    flags.push(opts.workspaceReadOnly ? '--ro-bind-try' : '--ro-bind', p, p);
+  }
   flags.push('--chdir', opts.workspacePath);
   flags.push('--setenv', 'HOME', opts.homePath || opts.workspacePath);