typeclaw 0.13.0 → 0.15.0

package/src/doctor/channel-checks.ts

@@ -0,0 +1,328 @@
+import { join } from 'node:path'
+
+import { type AdapterId, type ChannelsConfig } from '@/channels'
+import { loadConfigSync, validateConfig } from '@/config'
+import { readEnvFile } from '@/init'
+import { SecretsBackend } from '@/secrets'
+import { channelFieldDefaultEnv } from '@/secrets/defaults'
+
+import type { CheckContext, CheckResult, DoctorCheck } from './types'
+
+// Host-stage channel adapter health checks. These cannot talk to Slack /
+// Discord / Telegram / KakaoTalk / GitHub APIs — that work belongs to the
+// container-stage `start()` preflight on each adapter (see
+// `src/channels/manager.ts` and individual adapters). What doctor CAN do
+// from the host is verify that the credentials the container will look for
+// are actually present and resolvable, so the operator gets a clear,
+// before-`typeclaw start` signal instead of a silent skip in the runtime
+// logs.
+//
+// Every check is gated on `ctx.hasAgentFolder` (typeclaw.json is required to
+// read the channels config) and additionally on the adapter being declared
+// AND enabled in typeclaw.json. A missing or `enabled: false` adapter
+// reports `skipped` so the operator can see the check ran without it
+// turning into noise on minimal setups.
+
+export function buildChannelChecks(): DoctorCheck[] {
+  return [
+    slackBotCredentials(),
+    discordBotCredentials(),
+    telegramBotCredentials(),
+    kakaotalkCredentials(),
+    githubCredentials(),
+    githubWebhookDelivery(),
+  ]
+}
+
+function slackBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.slack-bot.credentials',
+    category: 'channels',
+    description: 'slack-bot adapter has SLACK_BOT_TOKEN and SLACK_APP_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'slack-bot', ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN']),
+  }
+}
+
+function discordBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.discord-bot.credentials',
+    category: 'channels',
+    description: 'discord-bot adapter has DISCORD_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'discord-bot', ['DISCORD_BOT_TOKEN']),
+  }
+}
+
+function telegramBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.telegram-bot.credentials',
+    category: 'channels',
+    description: 'telegram-bot adapter has TELEGRAM_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'telegram-bot', ['TELEGRAM_BOT_TOKEN']),
+  }
+}
+
+function kakaotalkCredentials(): DoctorCheck {
+  return {
+    name: 'channel.kakaotalk.credentials',
+    category: 'channels',
+    description: 'kakaotalk adapter has at least one account in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'kakaotalk')) {
+        return { status: 'skipped', message: 'kakaotalk not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.kakaotalk
+      const accountCount = block?.accounts ? Object.keys(block.accounts).length : 0
+      if (accountCount === 0) {
+        return {
+          status: 'warning',
+          message: 'kakaotalk has no accounts in secrets.json',
+          details: ['Adapter will start but fail authentication and stay disconnected.'],
+          fix: { description: 'Run `typeclaw channel add kakaotalk` to log in an account.' },
+        }
+      }
+      return { status: 'ok', message: `kakaotalk has ${accountCount} account(s)` }
+    },
+  }
+}
+
+function githubCredentials(): DoctorCheck {
+  return {
+    name: 'channel.github.credentials',
+    category: 'channels',
+    description: 'github adapter has auth and webhookSecret in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'github')) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.github
+      if (!block) {
+        return {
+          status: 'error',
+          message: 'github secrets missing from secrets.json',
+          details: ['Adapter requires both `auth` and `webhookSecret`.'],
+          fix: { description: 'Run `typeclaw channel set github` to configure GitHub auth.' },
+        }
+      }
+      const dotEnv = safeReadEnvFile(ctx.cwd)
+      const details: string[] = []
+      const webhookSecret = resolveSecretHostStage(block.webhookSecret, dotEnv)
+      if (webhookSecret === undefined || webhookSecret === '') {
+        details.push('webhookSecret is unset (resolves to empty string)')
+      }
+      if (block.auth.type === 'pat') {
+        const token = resolveSecretHostStage(block.auth.token, dotEnv)
+        if (token === undefined || token === '') {
+          details.push('auth.token (PAT) is unset (resolves to empty string)')
+        }
+      } else {
+        const key = resolveSecretHostStage(block.auth.privateKey, dotEnv)
+        if (key === undefined || key === '') {
+          details.push('auth.privateKey (App) is unset (resolves to empty string)')
+        }
+      }
+      if (details.length > 0) {
+        return {
+          status: 'error',
+          message: 'github credentials present but some fields resolve to empty',
+          details,
+          fix: { description: 'Run `typeclaw channel set github` to repopulate the missing fields.' },
+        }
+      }
+      return {
+        status: 'ok',
+        message: `github ${block.auth.type === 'pat' ? 'PAT' : 'App'} auth + webhookSecret resolved`,
+      }
+    },
+  }
+}
+
+function githubWebhookDelivery(): DoctorCheck {
+  return {
+    name: 'channel.github.webhook-delivery',
+    category: 'channels',
+    description: 'github webhook delivery has a public URL (webhookUrl or tunnel)',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const cfg = safeLoadConfig(ctx)
+      if (cfg === null) return configInvalidResult()
+      const github = cfg.channels.github
+      if (github === undefined || github.enabled === false) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const hasWebhookUrl = typeof github.webhookUrl === 'string' && github.webhookUrl.length > 0
+      const hasTunnel = cfg.tunnels.some((t) => t.for.kind === 'channel' && t.for.name === 'github')
+      if (hasWebhookUrl || hasTunnel) {
+        const source = hasWebhookUrl ? 'webhookUrl' : 'tunnel'
+        return { status: 'ok', message: `github webhook delivery configured via ${source}` }
+      }
+      if (github.repos.length === 0) {
+        return {
+          status: 'info',
+          message: 'github has no webhookUrl or tunnel, and no repos to register',
+          details: ['Webhooks will not be auto-registered until either webhookUrl or a tunnel binding is set.'],
+        }
+      }
+      return {
+        status: 'warning',
+        message: `github lists ${github.repos.length} repo(s) but has no public URL to deliver webhooks to`,
+        details: [
+          'Either set `channels.github.webhookUrl` in typeclaw.json,',
+          'or add a `tunnels[]` entry with `for: { kind: "channel", name: "github" }`.',
+        ],
+        fix: {
+          description: 'Configure webhookUrl or a github tunnel; see `typeclaw tunnel add` for managed tunnels.',
+        },
+      }
+    },
+  }
+}
+
+async function runTokenAdapterCheck(
+  ctx: CheckContext,
+  adapter: Extract<AdapterId, 'slack-bot' | 'discord-bot' | 'telegram-bot'>,
+  envNames: readonly string[],
+): Promise<CheckResult> {
+  const channels = readDeclaredChannels(ctx)
+  if (channels === null) return configInvalidResult()
+  if (!isAdapterActive(channels, adapter)) {
+    return { status: 'skipped', message: `${adapter} not configured` }
+  }
+  const dotEnv = safeReadEnvFile(ctx.cwd)
+  const channelSecrets = readChannelsSecrets(ctx)
+  const adapterSecrets = (channelSecrets?.[adapter] ?? {}) as Record<string, unknown>
+  const missing: string[] = []
+  for (const envName of envNames) {
+    if (hasTokenForEnv(adapter, envName, dotEnv, adapterSecrets)) continue
+    missing.push(envName)
+  }
+  if (missing.length > 0) {
+    return {
+      status: 'warning',
+      message: `${adapter} missing credentials: ${missing.join(', ')}`,
+      details: [
+        'Adapter will be skipped at start until credentials are present.',
+        'Resolution order: process.env wins over .env file value over secrets.json value.',
+      ],
+      fix: { description: 'Run `typeclaw channel set ' + adapter + '`, or add the env vars to .env.' },
+    }
+  }
+  return { status: 'ok', message: `${adapter} credentials present` }
+}
+
+// hasTokenForEnv resolves a single env-var-style credential the same way the
+// runtime does, plus one host-stage-specific source: process.env > .env file >
+// secrets.json. Empty strings count as unset, matching `src/secrets/resolve.ts`.
+function hasTokenForEnv(
+  adapter: AdapterId,
+  envName: string,
+  dotEnv: Map<string, string>,
+  adapterSecrets: Record<string, unknown>,
+): boolean {
+  const fromProcess = process.env[envName]
+  if (fromProcess !== undefined && fromProcess !== '') return true
+  const fromDotEnv = dotEnv.get(envName)
+  if (fromDotEnv !== undefined && fromDotEnv !== '') return true
+  const fieldName = fieldNameForEnv(adapter, envName)
+  if (fieldName === undefined) return false
+  const secret = adapterSecrets[fieldName]
+  if (!isSecretShape(secret)) return false
+  const resolved = resolveSecretHostStage(secret, dotEnv, envName)
+  return resolved !== undefined && resolved !== ''
+}
+
+// resolveSecretHostStage mirrors `resolveSecret` precedence but adds a .env
+// lookup before falling through to process.env. Doctor runs on the host and
+// never executes the container, so .env values are not in process.env. For
+// Secrets bound to a custom env var (e.g. `{ env: 'MY_TOKEN' }`), the runtime
+// would resolve via process.env.MY_TOKEN inside the container — on the host
+// that yields undefined even when the value is sitting in .env. So look up
+// the custom env name in the parsed .env map first.
+function resolveSecretHostStage(
+  secret: { value?: string; env?: string },
+  dotEnv: Map<string, string>,
+  defaultEnv?: string,
+): string | undefined {
+  const envName = secret.env ?? defaultEnv
+  if (envName !== undefined) {
+    const fromProcess = process.env[envName]
+    if (fromProcess !== undefined && fromProcess !== '') return fromProcess
+    const fromDotEnv = dotEnv.get(envName)
+    if (fromDotEnv !== undefined && fromDotEnv !== '') return fromDotEnv
+  }
+  return secret.value
+}
+
+function fieldNameForEnv(adapter: AdapterId, envName: string): string | undefined {
+  // Reverse-lookup using channelFieldDefaultEnv: scan the small set of known
+  // fields per adapter for the one whose default env matches. The set is
+  // tiny (1-2 entries) so the linear scan is fine.
+  const candidates: Record<string, readonly string[]> = {
+    'slack-bot': ['botToken', 'appToken'],
+    'discord-bot': ['token'],
+    'telegram-bot': ['token'],
+  }
+  const fields = candidates[adapter]
+  if (!fields) return undefined
+  for (const field of fields) {
+    if (channelFieldDefaultEnv(adapter, field) === envName) return field
+  }
+  return undefined
+}
+
+function isSecretShape(value: unknown): value is { value?: string; env?: string } {
+  if (typeof value !== 'object' || value === null) return false
+  const obj = value as Record<string, unknown>
+  const hasValue = typeof obj['value'] === 'string'
+  const hasEnv = typeof obj['env'] === 'string'
+  return hasValue || hasEnv
+}
+
+function readDeclaredChannels(ctx: CheckContext): ChannelsConfig | null {
+  const cfg = safeLoadConfig(ctx)
+  return cfg?.channels ?? null
+}
+
+function safeLoadConfig(ctx: CheckContext): ReturnType<typeof loadConfigSync> | null {
+  const result = validateConfig(ctx.cwd)
+  if (!result.ok) return null
+  try {
+    return loadConfigSync(ctx.cwd)
+  } catch {
+    return null
+  }
+}
+
+function safeReadEnvFile(cwd: string): Map<string, string> {
+  try {
+    return readEnvFile(cwd)
+  } catch {
+    return new Map()
+  }
+}
+
+function readChannelsSecrets(ctx: CheckContext): ReturnType<SecretsBackend['tryReadChannelsSync']> {
+  try {
+    return new SecretsBackend(join(ctx.cwd, 'secrets.json')).tryReadChannelsSync()
+  } catch {
+    return null
+  }
+}
+
+function isAdapterActive(channels: ChannelsConfig, adapter: AdapterId): boolean {
+  const slot = channels[adapter]
+  if (slot === undefined) return false
+  return slot.enabled !== false
+}
+
+function configInvalidResult(): CheckResult {
+  return { status: 'skipped', message: 'config invalid (covered by config.valid)' }
+}

package/src/doctor/checks.ts

@@ -21,6 +21,7 @@ import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { detectMissingDeps } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 
+import { buildChannelChecks } from './channel-checks'
 import type { DoctorCheck } from './types'
 
 export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
@@ -40,6 +41,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     hostdRegistration(),
     containerState(dockerExec),
     containerHostPort(),
+    ...buildChannelChecks(),
   ]
 }
 

package/src/init/dockerfile.ts

@@ -1,4 +1,9 @@
 import type { DockerfileConfig, DockerfileFeatureToggle } from '@/config/config'
+import {
+  CLAUDE_CREDENTIALS_FILE_NAME,
+  CLAUDE_CREDENTIALS_RELATIVE_PATH,
+  CLAUDE_DEFAULT_CONFIG_DIR_NAME,
+} from '@/secrets/export-claude-credentials-file'
 
 import { GHCR_BASE_IMAGE_REPO } from './cli-version'
 
@@ -33,7 +38,27 @@ export type BuildDockerfileOptions = {
 // self-heals: it spawns Xvfb (and exports DISPLAY) if the binary is on
 // PATH, and execs the agent directly otherwise. See APT_FEATURES.xvfb
 // below and `buildEntrypointShim`.
-const BASELINE_APT_PACKAGES = ['git', 'ca-certificates', 'curl', 'gnupg', 'iptables', 'util-linux'] as const
+// `bubblewrap` ships the `bwrap(1)` setuid-less namespace sandboxer. It is
+// included in baseline (not behind a toggle) because per-tool sandboxing of
+// agent bash calls is a runtime concern resolved by the agent, not by the
+// agent author. See `src/sandbox/` for the bwrap command builder, and
+// `docs/internals/sandbox.mdx` for why bwrap is the right
+// shape for per-call isolation inside an already-containerized agent. The
+// outer container's `--security-opt seccomp=unconfined` (added in the same
+// commit as this line; see `src/container/start.ts:planStart`) is what lets
+// bwrap create user/pid/mount namespaces from inside Docker. Without that
+// flag the seccomp default profile blocks `unshare(CLONE_NEWUSER)` and bwrap
+// fails at startup. The two changes are load-bearing together — do not drop
+// one without the other.
+const BASELINE_APT_PACKAGES = [
+  'git',
+  'ca-certificates',
+  'curl',
+  'gnupg',
+  'iptables',
+  'util-linux',
+  'bubblewrap',
+] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
 // a non-browser client on residential IPs in 2026. DDG fingerprints incoming
@@ -283,13 +308,19 @@ set -eu
 #                           no inbound exposure anyway.
 # link_persistent_home_files symlinks credential files that tools write
 # to $HOME into a bind-mounted location so they survive container
-# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
-# rewrites the file in place to rotate OAuth tokens, and the official
-# CI/CD guidance is to persist auth.json so refresh-token state
-# compounds across runs. The container's $HOME (/root by default) lives
-# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
-# cycle, so without this symlink the operator would have to re-paste
-# auth.json after every restart.
+# restarts. The container's $HOME (/root by default) lives on Docker's
+# writable overlay and is wiped on every \`stop\`+\`start\` cycle, so
+# without this symlink the operator would have to re-paste credentials
+# after every restart.
+#
+# Two files are linked today, both following the same contract:
+#   - ~/.codex/auth.json — Codex CLI rotates OAuth tokens in place by
+#     rewriting auth.json with refreshed credentials.
+#   - $CLAUDE_CONFIG_DIR/.credentials.json, or ~/.claude/.credentials.json
+#     by default — Claude Code rotates OAuth tokens in place by rewriting
+#     .credentials.json on every successful refresh (anthropics/claude-code
+#     #53063). Linux/Windows path; macOS uses the Keychain entry "Claude
+#     Code-credentials" with the same JSON shape.
 #
 # The persist root lives under /agent/.typeclaw/home/ (bind-mounted
 # from the agent folder via the -v <cwd>:/agent flag in start.ts).
@@ -329,6 +360,12 @@ link_persistent_home_files() {
   persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
   mkdir -p "$persist_root/.codex" "$HOME/.codex"
   ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+  claude_config_dir="\${CLAUDE_CONFIG_DIR:-}"
+  if [ -z "$claude_config_dir" ]; then
+    claude_config_dir="$HOME/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}"
+  fi
+  mkdir -p "$persist_root/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}" "$claude_config_dir"
+  ln -sfn "$persist_root/${CLAUDE_CREDENTIALS_RELATIVE_PATH}" "$claude_config_dir/${CLAUDE_CREDENTIALS_FILE_NAME}"
 }
 
 start_xvfb() {

package/src/run/index.ts

@@ -43,7 +43,11 @@ import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
-import { exportCodexAuthFileForAgent, hydrateChannelEnvFromSecrets } from '@/secrets'
+import {
+  exportClaudeCredentialsFileForAgent,
+  exportCodexAuthFileForAgent,
+  hydrateChannelEnvFromSecrets,
+} from '@/secrets'
 import { createServer, type Server } from '@/server'
 import {
   createCommandRunner,
@@ -194,6 +198,19 @@ export async function startAgent({
     log: (message) => console.warn(message),
   })
 
+  // Same shape as the codex exporter above, gated on `docker.file.claudeCode`
+  // and `secrets.json#providers.anthropic`. Writes ~/.claude/.credentials.json
+  // so the Claude Code CLI in the container can run without the user pasting
+  // a CLAUDE_CODE_OAUTH_TOKEN. See src/secrets/export-claude-credentials-
+  // file.ts for the newer-wins compare that prevents clobbering Claude
+  // Code's in-place token refreshes, and the read-merge-write that preserves
+  // any mcpOAuth state in the file.
+  exportClaudeCredentialsFileForAgent({
+    agentDir: cwd,
+    claudeCodeEnabled: cwdConfig.docker.file.claudeCode,
+    log: (message) => console.warn(message),
+  })
+
   const claimController = createClaimController({
     cwd,
     permissions: pluginsLoaded.permissions,

package/src/sandbox/availability.ts

@@ -0,0 +1,35 @@
+import { SandboxUnavailableError } from './errors'
+
+// Cached because the binary cannot appear or disappear during a single
+// process lifetime, and a probe per bash call is wasted work. Keyed by the
+// resolved bwrap path so a test (or a consumer pinning a non-default path)
+// re-probes instead of reading another path's cached result.
+const availabilityCache = new Map<string, boolean>()
+
+export async function ensureBwrapAvailable(options?: { bwrapPath?: string }): Promise<void> {
+  const bwrap = options?.bwrapPath ?? 'bwrap'
+  const cached = availabilityCache.get(bwrap)
+  if (cached === true) return
+  if (cached === false) throw new SandboxUnavailableError()
+
+  const available = await probe(bwrap)
+  availabilityCache.set(bwrap, available)
+  if (!available) throw new SandboxUnavailableError()
+}
+
+async function probe(bwrap: string): Promise<boolean> {
+  // Bun.spawn throws synchronously with ENOENT when the binary is not on
+  // PATH, rather than resolving with a non-zero exit code — so the
+  // "not installed" case lands in the catch, not in proc.exitCode.
+  try {
+    const proc = Bun.spawn([bwrap, '--version'], { stdout: 'ignore', stderr: 'ignore' })
+    await proc.exited
+    return proc.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+export function _resetBwrapAvailabilityCacheForTests(): void {
+  availabilityCache.clear()
+}

package/src/sandbox/build.ts

@@ -0,0 +1,128 @@
+import { SandboxPolicyError } from './errors'
+import {
+  DEFAULT_SANDBOX_ENV,
+  type SandboxCommandFilter,
+  type SandboxEnvPolicy,
+  type SandboxMount,
+  type SandboxPolicy,
+} from './policy'
+import { formatCommand } from './quote'
+
+export type SandboxedCommand = {
+  argv: string[]
+  commandString: string
+}
+
+// Pure: no I/O, no bwrap availability probe (that is `ensureBwrapAvailable`'s
+// job). Given a bash command and a policy, returns the bwrap-wrapped argv plus
+// a shell-quoted rendering of it. Knows nothing about subagents, origins, or
+// the agent runtime — a consumer resolves a policy from whatever context it
+// has and calls this. Throws SandboxPolicyError only when the consumer opted
+// into the command-filter knobs and the command violates them.
+export function buildSandboxedCommand(command: string, policy: SandboxPolicy = {}): SandboxedCommand {
+  if (policy.commandFilter !== undefined) {
+    applyCommandFilter(command, policy.commandFilter)
+  }
+  const argv = buildArgv(command, policy)
+  return { argv, commandString: formatCommand(argv) }
+}
+
+function buildArgv(command: string, policy: SandboxPolicy): string[] {
+  const bwrap = policy.bwrapPath ?? 'bwrap'
+  const argv: string[] = [bwrap, '--unshare-all']
+
+  if (policy.network === 'inherit') {
+    // --unshare-all already unshared the net namespace; --share-net rejoins
+    // the outer container's network. Other namespaces (user/pid/mount/ipc/
+    // uts/cgroup) stay unshared. Default ('none' / undefined) leaves the net
+    // namespace isolated — prompt-injected bash cannot exfiltrate over the
+    // network without the consumer explicitly opting in.
+    argv.push('--share-net')
+  }
+
+  const proc = policy.process ?? {}
+  if (proc.newSession !== false) {
+    // Drops the controlling terminal so the contained process cannot push
+    // input back into the agent's tty via TIOCSTI. Mandated by
+    // docs/internals/sandbox.mdx. Harmless for a one-shot `bash -c`.
+    argv.push('--new-session')
+  }
+  if (proc.dieWithParent !== false) {
+    argv.push('--die-with-parent')
+  }
+
+  argv.push('--clearenv')
+  for (const [key, value] of Object.entries(resolveEnv(policy.env))) {
+    argv.push('--setenv', key, value)
+  }
+
+  argv.push('--ro-bind', '/usr', '/usr', '--ro-bind', '/etc', '/etc', '--dev', '/dev', '--tmpfs', '/tmp')
+
+  if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
+    // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
+    // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc
+    // (leaks the outer container's /proc/N/environ — including
+    // FIREWORKS_API_KEY — into the sandbox). See sandbox.mdx.
+    argv.push('--tmpfs', '/proc')
+  }
+
+  for (const mount of policy.mounts ?? []) {
+    appendMount(argv, mount)
+  }
+
+  if (policy.cwd !== undefined) {
+    argv.push('--chdir', policy.cwd)
+  }
+
+  argv.push('bash', '-c', command)
+  return argv
+}
+
+function appendMount(argv: string[], mount: SandboxMount): void {
+  switch (mount.type) {
+    case 'ro-bind':
+      argv.push('--ro-bind', mount.source, mount.dest)
+      return
+    case 'bind':
+      argv.push('--bind', mount.source, mount.dest)
+      return
+    case 'tmpfs':
+      argv.push('--tmpfs', mount.dest)
+      return
+    case 'dev':
+      argv.push('--dev', mount.dest)
+      return
+  }
+}
+
+function resolveEnv(env: SandboxEnvPolicy | undefined): Record<string, string> {
+  const resolved: Record<string, string> = { ...DEFAULT_SANDBOX_ENV, ...env?.set }
+  for (const key of env?.passthrough ?? []) {
+    const value = process.env[key]
+    if (value !== undefined) resolved[key] = value
+  }
+  return resolved
+}
+
+// Token-boundary match: the normalized command must equal a prefix exactly or
+// start with `prefix + ' '`. Substring matching would let `git-evil ...` slip
+// past a `git` prefix; this does not.
+const ALLOWLIST_WHITESPACE = /\s+/g
+const FORBIDDEN_METACHARS = /[;&|`$()<>\\\n]/
+
+function applyCommandFilter(command: string, filter: SandboxCommandFilter): void {
+  if (filter.rejectShellMetacharacters === true && FORBIDDEN_METACHARS.test(command)) {
+    throw new SandboxPolicyError(
+      'command contains a forbidden shell metacharacter. This policy only permits simple commands without ; & | ` $ ( ) < > \\ or newlines.',
+    )
+  }
+  if (filter.allowPrefixes !== undefined) {
+    const normalized = command.trim().replace(ALLOWLIST_WHITESPACE, ' ')
+    const matched = filter.allowPrefixes.some((p) => normalized === p || normalized.startsWith(`${p} `))
+    if (!matched) {
+      throw new SandboxPolicyError(
+        `command does not match any allowed prefix. Allowed: ${filter.allowPrefixes.join(', ')}`,
+      )
+    }
+  }
+}

package/src/sandbox/errors.ts

@@ -0,0 +1,20 @@
+export class SandboxUnavailableError extends Error {
+  override readonly name = 'SandboxUnavailableError'
+  constructor() {
+    super(
+      'sandbox unavailable: bwrap binary not found on PATH. Refusing to run a command that requires sandboxing without the kernel boundary in place.',
+    )
+  }
+}
+
+// Raised by the optional command-filter knobs (allowPrefixes,
+// rejectShellMetacharacters). These are consumer-opt-in restrictions layered
+// ABOVE the always-on kernel containment, so a rejection here is a policy
+// decision the consumer asked for — not a failure of the sandbox itself. The
+// message is phrased for the model to read and self-correct from.
+export class SandboxPolicyError extends Error {
+  override readonly name = 'SandboxPolicyError'
+  constructor(reason: string) {
+    super(`sandbox policy rejected command: ${reason}`)
+  }
+}

package/src/sandbox/index.ts

@@ -0,0 +1,14 @@
+export { buildSandboxedCommand, type SandboxedCommand } from './build'
+export { ensureBwrapAvailable } from './availability'
+export { formatCommand, shellQuote } from './quote'
+export { SandboxPolicyError, SandboxUnavailableError } from './errors'
+export {
+  DEFAULT_SANDBOX_ENV,
+  type SandboxCommandFilter,
+  type SandboxEnvPolicy,
+  type SandboxMount,
+  type SandboxNetwork,
+  type SandboxPolicy,
+  type SandboxProcessPolicy,
+  type SandboxProcStrategy,
+} from './policy'