kronk-cli 0.1.0 → 0.1.2

package/README.md

@@ -23,8 +23,67 @@ entirely on your machine. No network, no API key, no per-token cost.
   2104→812 tok · 61.3 tok/s · ttft 240ms · 1980 cached
 ```
 
+[![ci](https://github.com/BardiaN/kronk-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/BardiaN/kronk-cli/actions/workflows/ci.yml)
+[![security](https://github.com/BardiaN/kronk-cli/actions/workflows/security.yml/badge.svg)](https://github.com/BardiaN/kronk-cli/actions/workflows/security.yml)
+[![codeql](https://github.com/BardiaN/kronk-cli/actions/workflows/codeql.yml/badge.svg)](https://github.com/BardiaN/kronk-cli/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/BardiaN/kronk-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/BardiaN/kronk-cli)
+[![npm](https://img.shields.io/npm/v/kronk-cli?logo=npm)](https://www.npmjs.com/package/kronk-cli)
+
 **Zero dependencies.** It is `fetch` and `readline` against Kronk's OpenAI-compatible API.
 
+**It talks to your Kronk server and nothing else** — enforced in CI by running the whole thing
+inside a network namespace with only loopback. See [Verifying this build](#verifying-this-build).
+
+---
+
+## Verifying this build
+
+This tool reads your files and runs your commands. You should not have to take anyone's word for
+what it does with them — so every claim here is machine-checkable.
+
+### Check the artifact came from this source
+
+Every release tarball carries a signed attestation binding it to the repository, commit and
+workflow run that produced it:
+
+```bash
+gh attestation verify kronk-cli-*.tgz --repo BardiaN/kronk-cli
+```
+
+npm packages carry the same provenance, shown as a **Provenance** panel on the
+[package page](https://www.npmjs.com/package/kronk-cli), and verifiable locally:
+
+```bash
+npm audit signatures
+```
+
+Both fail if the artifact was built anywhere other than this repository's CI.
+
+### Read the scan results yourself
+
+| | |
+|---|---|
+| [Security tab](https://github.com/BardiaN/kronk-cli/security/code-scanning) | every CodeQL and Scorecard finding, open and closed |
+| [Scorecard report](https://scorecard.dev/viewer/?uri=github.com/BardiaN/kronk-cli) | per-check supply-chain scores, updated weekly |
+| [Actions](https://github.com/BardiaN/kronk-cli/actions/workflows/security.yml) | full logs of every scan, including the egress proof |
+
+These are published by GitHub and the OpenSSF, not by this project. Nobody here can edit them.
+
+### Check it does not phone home
+
+The strongest claim, and the easiest to test yourself:
+
+```bash
+# Linux — run it with no network except loopback
+sudo unshare --net bash -c 'ip link set lo up; kronk-cli --models'
+```
+
+CI runs exactly this on every pull request against a stub server, and a second step proves the
+namespace was really isolated so a pass cannot be a false negative.
+
+Or just read `src/` — it is under 1,500 lines with no dependencies, and every network call goes
+through one function in `src/client.js`.
+
 ---
 
 ## Requirements
@@ -94,8 +153,102 @@ ln -s "$PWD/src/index.js" ~/.local/bin/kronk-cli
 
 ### Scope
 
-The agent roots itself at **the directory you launch it from**. That becomes its sandbox — file
-tools cannot read or write outside it, and `bash` cannot `cd` out of it. `cd` into a project first.
+The agent roots itself at **the directory you launch it from**. `cd` into a project first.
+
+Two separate things keep it there, and they are worth telling apart:
+
+| | Enforced by | Covers |
+|---|---|---|
+| **Path containment** | `kronk-cli` | `read_file`, `write_file`, `list_dir`, `search` — resolved through symlinks, so a link inside the project cannot point out of it |
+| **Shell confinement** | the kernel — `sandbox-exec` on macOS, [`bwrap`](https://github.com/containers/bubblewrap) on Linux | `bash`: writes outside the project are denied, and key material (`~/.ssh`, `~/.gnupg`, `~/.password-store`, the macOS keychain, `~/.netrc`, `~/.npmrc`) is unreadable |
+
+The startup banner says which is in force:
+
+```
+  sandbox  paths + seatbelt
+```
+
+If no backend is available, it says so rather than implying one:
+
+```
+  sandbox  paths only — bwrap not installed, shell commands are unconfined
+```
+
+**What shell confinement does not do.** Reads stay open outside the deny-list, because denying them
+wholesale breaks every compiler and runtime the agent needs. The network is not blocked — the agent
+has to be able to run `npm install`. So it stops a command from *writing* outside your project or
+reading your keys; it does not make a hostile command harmless.
+
+The write half is categorical: both backends start from "nothing is writable" and hand back the
+project, the temp directories and the build caches. The read half is a deny-list, and a deny-list is
+only as good as its entries — which is exactly why it is kept narrow rather than broad. See
+[Authenticated CLIs](#authenticated-clis) for the trade that produced it.
+
+Two more limits worth stating:
+
+- **Symlinks out of the project are refused, even benign ones.** An `npm link`ed package under
+  `node_modules` resolves outside the root, so `read_file` and `write_file` will decline it. Use the
+  real path, which is inside a project the agent was launched in.
+- **Only filesystem operations are constrained.** The macOS profile allows everything else by
+  design, so a command that persuades an *already-running* unsandboxed process to act on its behalf
+  is not covered by it. Confinement limits what a command reaches directly; it is not a substitute
+  for reading the command before approving it.
+
+`KRONK_SANDBOX=strict` refuses to run `bash` at all when no backend is available, which is the
+setting to use if you need the guarantee rather than the best effort. `KRONK_SANDBOX=off` disables
+confinement.
+
+On Linux, install bubblewrap to get it: `apt install bubblewrap` / `dnf install bubblewrap`.
+
+### Authenticated CLIs
+
+**Tools you are already logged in to keep working.** `kubectl`, `argocd`, `aws`, `docker` and the
+like read their session tokens from `~/.kube`, `~/.config/argocd`, `~/.aws` and so on, and those
+stay readable:
+
+```console
+› run lint on all apps, then show me the current kube context
+  1 ⚙ bash: npx nx run-many -t lint
+  ✓ 174 lines
+  2 ⚙ bash: kubectl config current-context
+  ✓ prod
+```
+
+An earlier version of this denied those directories too. It broke `kubectl` and `gh` outright while
+still missing `argocd`, whose token lives in `~/.config/argocd` and which nobody had thought to add
+— a deny-list that blocks the tools you use and misses the ones you forgot costs real work and buys
+little, since an attacker just takes whichever store was not on the list. So the default covers
+material that is pivot-grade and never legitimately read by a build.
+
+**The one exception is the macOS keychain**, which is denied by default. `gh` stores its token
+there, so it will report `Failed to log in` under the sandbox. If you want it:
+
+```bash
+KRONK_SANDBOX_ALLOW=~/Library/Keychains kronk-cli
+```
+
+**Logging in from inside the agent will not work**, by design — `argocd login`, `gh auth login` and
+`kubectl config set-context` all write outside the project. Log in yourself, in your own shell,
+before starting a session. If a tool genuinely must write to its config directory, allow just that:
+
+```bash
+KRONK_SANDBOX_ALLOW=~/.config/argocd kronk-cli
+```
+
+`KRONK_SANDBOX_ALLOW` makes a path fully available — writable, and readable even if it is denied by
+default. `KRONK_SANDBOX_DENY` goes the other way and hides more, if you would rather the agent could
+not read your cluster credentials at all:
+
+```bash
+KRONK_SANDBOX_DENY=~/.kube,~/.aws kronk-cli     # kubectl and aws will now fail
+```
+
+Both take a comma- or colon-separated list, and `~` expands.
+
+> ⚠️ `bwrap` needs unprivileged user namespaces, which several hardened distros and most CI
+> runners disable — GitHub's included. Where they are off, `bwrap` is installed but cannot start,
+> and the banner will say the shell is unconfined. That is why the backend is probed rather than
+> assumed, and why the check is worth reading rather than trusting the presence of the binary.
 
 ---
 
@@ -233,6 +386,9 @@ The per-turn usage line still prints after each response; this one is the runnin
 | `KRONK_THINKING` | `true` | `false` hides reasoning but still generates it |
 | `KRONK_NO_THINK` | — | `1` disables reasoning server-side |
 | `KRONK_TOOL_TIMEOUT` | `900` | Seconds before a shell command is killed |
+| `KRONK_SANDBOX` | `auto` | `auto` confines `bash` when the OS can, `strict` refuses to run it when it cannot, `off` disables it |
+| `KRONK_SANDBOX_ALLOW` | — | Paths to make fully available inside the sandbox, comma or colon separated |
+| `KRONK_SANDBOX_DENY` | — | Extra paths to hide from `bash`, comma or colon separated |
 | `KRONK_DISTILL` | `true` | `false` disables tool-output distillation |
 | `KRONK_DISTILL_AT` | `8000` | Characters of output that trigger distillation |
 | `KRONK_AUTO_COMPACT` | `true` | `false` disables automatic compaction |
@@ -430,7 +586,8 @@ Disable with `--no-compact` or `KRONK_AUTO_COMPACT=false` if you would rather se
 | `bash` | ✋ | Run a command; shows it first |
 
 `--yes` and `--auto` skip the prompts. Paths resolve against the session directory and cannot
-escape the launch root. `bash` keeps its working directory **between calls**, so a bare `cd`
+escape the launch root — including through a symlink. `bash` additionally runs under an OS
+sandbox where one is available; see [Scope](#scope) for exactly what that covers. `bash` keeps its working directory **between calls**, so a bare `cd`
 sticks the way it would in a real shell.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kronk-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A Claude-Code-style terminal agent for local models served by Kronk.",
   "license": "Apache-2.0",
   "type": "module",

package/src/config.js

@@ -35,6 +35,27 @@ export const config = {
   rcPath: RC,
 };
 
+/**
+ * File contents and command output leave this process in request bodies, which
+ * is the whole job. Over loopback that is fine. Pointed at a remote host over
+ * plain HTTP it is not, so say so once rather than letting it pass silently.
+ */
+export function warnIfInsecure(warn = console.error) {
+  let url;
+  try { url = new URL(config.baseUrl); } catch { return false; }
+
+  const local = ['localhost', '127.0.0.1', '::1', '0.0.0.0'].includes(url.hostname)
+    || url.hostname.endsWith('.local')
+    || url.hostname === 'host.docker.internal';
+
+  if (url.protocol === 'https:' || local) return false;
+
+  warn(`  warning: ${config.baseUrl} is remote and unencrypted.`);
+  warn('  File contents and command output will cross the network in clear text.');
+  warn('  Use https, or an SSH tunnel to keep the endpoint on localhost.');
+  return true;
+}
+
 export const headers = () => ({
   'Content-Type': 'application/json',
   Authorization: `Bearer ${config.token}`,

package/src/index.js

@@ -2,13 +2,14 @@
 import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { readFile } from 'node:fs/promises';
-import { config, DEFAULT_MODEL } from './config.js';
+import { config, DEFAULT_MODEL, warnIfInsecure } from './config.js';
 import { listModels, listModelDetails, listLoaded, modelLimits, tokenize } from './client.js';
 import { runTurn, SYSTEM, SYSTEM_AUTO } from './agent.js';
 import { c, banner, fmtContext, statusLine } from './ui.js';
 import { projectContext } from './context.js';
 import { compact, report } from './compact.js';
 import { loadServers, McpHub, reportFailures } from './mcp.js';
+import { resolveSandbox, sandbox } from './tools.js';
 
 // ---- argv -------------------------------------------------------------
 const argv = process.argv.slice(2);
@@ -307,6 +308,14 @@ async function oneShot(prompt) {
   ];
   const ac = new AbortController();
   process.on('SIGINT', () => ac.abort());
+
+  // One shot prints no banner, so the mode that auto-approves every command was
+  // also the one that said nothing about what was confining them. On stderr, so
+  // piping the answer somewhere still gets just the answer.
+  if (resolveSandbox() === 'none' && AUTO_YES) {
+    console.error(c.yellow(`  warning: shell commands run unconfined — ${sandbox.reason}`));
+  }
+
   const approve = async (name) => {
     if (AUTO_YES) return true;
     console.log(c.yellow(`  ✗ ${name} needs approval; re-run with --yes to allow it`));
@@ -322,6 +331,9 @@ async function oneShot(prompt) {
 }
 
 async function main() {
+  // Before anything reaches the network, on every path through the program.
+  warnIfInsecure();
+
   if (SHOW_MODELS) { await showModels(); return; }
   if (SHOW_MCP) { await showMcp(); process.exit(0); }
 
@@ -344,9 +356,17 @@ async function main() {
     if (ctx.isGit) bits.push('git');
     if (ctx.agentFile) bits.push(c.green(ctx.agentFile));
     if (config.contextWindow) bits.push(c.grey(`${(config.contextWindow / 1000).toFixed(0)}k ctx`));
-    console.log(c.grey(`  context`) + `  ${bits.join(c.grey(' · '))}\n`);
+    console.log(c.grey(`  context`) + `  ${bits.join(c.grey(' · '))}`);
   }
 
+  // Say which of the two confinements is actually in force. Printing nothing
+  // would let the README's word "sandbox" stand in for a guarantee the kernel
+  // is not making on this machine.
+  const backend = resolveSandbox();
+  console.log(`${c.grey('  sandbox')}  ${backend === 'none'
+    ? c.yellow(`paths only — ${sandbox.reason}, shell commands are unconfined`)
+    : c.grey(`paths + ${backend}`)}\n`);
+
   const messages = [{ role: 'system', content }];
 
   // Ctrl-C aborts the in-flight request instead of killing the process.

package/src/sandbox.js

@@ -0,0 +1,168 @@
+import { existsSync, statSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
+
+/**
+ * OS-level confinement for `bash`.
+ *
+ * The file tools resolve paths and refuse to leave the launch root, but `bash`
+ * had no such guard: `cat ~/.ssh/id_rsa` ran fine, and the README called the
+ * launch root a sandbox anyway. A path check in JavaScript cannot constrain a
+ * process it has already handed the whole machine to, so the confinement has to
+ * come from the kernel.
+ *
+ * This module is pure — it builds an argv and nothing else. Spawning stays in
+ * the tool layer, which is the only place allowed to start processes.
+ */
+
+/** Directories a build legitimately writes to outside the project. */
+const CACHE_DIRS = ['.npm', '.cache', '.yarn', '.pnpm-store', 'Library/Caches'];
+
+/**
+ * Absolute cache paths. Exported because with the filesystem read-only these
+ * have to exist *before* the sandbox starts — bwrap cannot create a mountpoint
+ * under a read-only parent, so a machine with no ~/.npm yet could not run
+ * `npm install` at all. The tool layer creates them; this module stays pure.
+ */
+export const cacheDirs = (home) => CACHE_DIRS.map((d) => join(home, d));
+
+/**
+ * Key material the agent has no reason to read, and that no build step needs.
+ *
+ * This list was once wider — it covered `~/.kube`, `~/.aws`, `~/.config/gh` and
+ * friends. That broke `kubectl`, `gh` and anything else the user had already
+ * logged in to, while still missing tools nobody thought of (`argocd` keeps its
+ * token in `~/.config/argocd`, and sailed straight through). A deny-list that
+ * blocks the tools you use and misses the ones you forgot is worse than an
+ * honest boundary: it costs real work and buys little, because an attacker
+ * exfiltrates whichever credential store was not on it.
+ *
+ * So the default is narrow and covers material that is pivot-grade and never
+ * legitimately read by a build. Session tokens for CLIs you are already logged
+ * in to stay readable — add them with KRONK_SANDBOX_DENY if your threat model
+ * wants them gone, at the cost of those commands failing.
+ *
+ * The write confinement is the half that holds categorically. This half is
+ * best-effort, and the README says so.
+ */
+const SECRET_DIRS = ['.ssh', '.gnupg', '.password-store', 'Library/Keychains'];
+
+const SECRET_FILES = ['.npmrc', '.netrc', '.pypirc', '.git-credentials'];
+
+/** `A:B` or `A,B`, absolute or `~`-relative. Empty entries are dropped. */
+export function extraPaths(value, home) {
+  return (value ?? '')
+    .split(/[:,]/)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => (p.startsWith('~/') ? join(home, p.slice(2)) : p));
+}
+
+/** Seatbelt string literals are double-quoted; only `\` and `"` need escaping. */
+const sb = (p) => `"${p.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * Allow everything, then take away writes outside the project and reads of
+ * credential stores. Starting from `(deny default)` would mean enumerating every
+ * dylib, locale file and device node a toolchain touches, and getting that wrong
+ * fails closed in ways that look like a broken CLI rather than a blocked write.
+ */
+export function seatbeltProfile({ root, home, tmp, allow = [], deny = [] }) {
+  const writable = [root, '/dev', '/private/tmp', '/private/var/tmp', '/private/var/folders', '/tmp']
+    .concat(tmp ? [tmp] : [])
+    .concat(cacheDirs(home))
+    .concat(allow);
+
+  // ALLOW means "this path is fully available", so it also lifts a default
+  // denial. Without that there is no way to run a keychain-backed CLI like `gh`
+  // short of turning the sandbox off entirely, which is a worse trade.
+  const unreadable = SECRET_DIRS.map((d) => join(home, d)).concat(deny)
+    .filter((d) => !allow.some((a) => d === a || d.startsWith(`${a}/`)));
+
+  return [
+    '(version 1)',
+    '(allow default)',
+    '(deny file-write*)',
+    `(allow file-write* ${writable.map((p) => `(subpath ${sb(p)})`).join(' ')})`,
+    `(deny file-read* ${unreadable.map((d) => `(subpath ${sb(d)})`).join(' ')} `
+      + `${SECRET_FILES.map((f) => `(literal ${sb(join(home, f))})`).join(' ')})`,
+  ].join('\n');
+}
+
+/**
+ * bubblewrap equivalent: the filesystem read-only, then hand back what has to
+ * be writable.
+ *
+ * This started as `--dev-bind / /` (everything read-write) with `$HOME` made
+ * read-only afterwards, which protected `$HOME` and nothing else — `/etc`,
+ * `/opt`, `/usr/local` and `/var/tmp` all stayed writable. That is the escape
+ * this module exists to prevent, merely relocated. Deny-by-default is the only
+ * shape that matches what the README promises, and it is what seatbelt does on
+ * the other side.
+ */
+export function bwrapArgs({ root, home, cwd, tmp, allow = [], deny = [] }) {
+  // /dev and /proc must be fresh mounts: a read-only bind of the host's would
+  // leave a shell unable to write to its own stdout or read /proc/self.
+  const args = ['--die-with-parent', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc'];
+
+  // The project is bound unconditionally: it is the working directory, it has to
+  // exist, and guarding it on existsSync meant a root that could not be stat-ed
+  // silently produced a read-only project instead of an error.
+  args.push('--bind', root, root);
+
+  const optional = ['/tmp', '/var/tmp']
+    .concat(tmp ? [tmp] : [])
+    .concat(cacheDirs(home))
+    .concat(allow);
+
+  for (const p of optional) {
+    if (existsSync(p)) args.push('--bind', p, p);
+  }
+
+  // A tmpfs makes a credential directory exist but be empty; /dev/null over a
+  // file makes it readable and empty. Both beat a missing path, which tools
+  // report as a confusing ENOENT rather than an obvious denial.
+  const hidden = SECRET_DIRS.map((x) => join(home, x)).concat(deny)
+    .filter((d) => !allow.some((a) => d === a || d.startsWith(`${a}/`)));
+  for (const d of hidden) {
+    if (existsSync(d) && statSync(d).isDirectory()) args.push('--tmpfs', d);
+  }
+  for (const f of SECRET_FILES.map((x) => join(home, x))) {
+    if (existsSync(f)) args.push('--ro-bind', '/dev/null', f);
+  }
+
+  return args.concat('--chdir', cwd, 'bash');
+}
+
+/** First match in PATH, without shelling out to `which`. */
+export function onPath(bin, { env = process.env } = {}) {
+  return (env.PATH ?? '').split(delimiter).some((d) => d && existsSync(join(d, bin)));
+}
+
+/**
+ * Which backend this machine can offer, before we know whether it works.
+ * `KRONK_SANDBOX=off` skips confinement; `strict` refuses to run unconfined.
+ */
+export function detectBackend({ platform = process.platform, env = process.env } = {}) {
+  if ((env.KRONK_SANDBOX ?? 'auto') === 'off') return 'none';
+  if (platform === 'darwin' && onPath('sandbox-exec', { env })) return 'seatbelt';
+  if (platform === 'linux' && onPath('bwrap', { env })) return 'bwrap';
+  return 'none';
+}
+
+/**
+ * Build the argv that runs `script` under `backend`.
+ * Returns `['bash', ['-c', script]]` shaped output for spawn().
+ */
+export function sandboxArgv(script, { backend, root, home, cwd, tmp, env = process.env }) {
+  const allow = extraPaths(env.KRONK_SANDBOX_ALLOW, home);
+  const deny = extraPaths(env.KRONK_SANDBOX_DENY, home);
+
+  if (backend === 'seatbelt') {
+    return ['sandbox-exec',
+      ['-p', seatbeltProfile({ root, home, tmp, allow, deny }), 'bash', '-c', script]];
+  }
+  if (backend === 'bwrap') {
+    return ['bwrap', [...bwrapArgs({ root, home, cwd, tmp, allow, deny }), '-c', script]];
+  }
+  return ['bash', ['-c', script]];
+}

package/src/tools.js

@@ -1,8 +1,10 @@
 import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
-import { execFile, spawn } from 'node:child_process';
+import { execFile, spawn, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
-import { resolve, relative } from 'node:path';
-import { realpathSync } from 'node:fs';
+import { resolve, relative, dirname, basename, isAbsolute } from 'node:path';
+import { realpathSync, mkdirSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { detectBackend, sandboxArgv, cacheDirs } from './sandbox.js';
 import { c } from './ui.js';
 
 const exec = promisify(execFile);
@@ -31,6 +33,30 @@ function real(p) {
   try { return realpathSync(p); } catch { return p; }
 }
 
+/**
+ * Resolve symlinks all the way down, including for a path that does not exist
+ * yet.
+ *
+ * Comparing the textual path against the root let a symlink inside the project
+ * point anywhere: `ln -s /etc/passwd notes` and then `read_file notes` passed
+ * the containment check and read the target. Writes were worse — a symlinked
+ * directory meant `write_file` landed outside the root entirely. So we resolve
+ * the deepest ancestor that exists and re-attach the rest, which is the path the
+ * filesystem will actually use.
+ */
+function realDeep(abs) {
+  const tail = [];
+  let cur = abs;
+  for (;;) {
+    try { return tail.length ? resolve(realpathSync(cur), ...tail) : realpathSync(cur); }
+    catch { /* does not exist yet — walk up */ }
+    const parent = dirname(cur);
+    if (parent === cur) return abs;
+    tail.unshift(basename(cur));
+    cur = parent;
+  }
+}
+
 /**
  * Trim from the MIDDLE, never the end.
  *
@@ -47,9 +73,11 @@ export const clip = (s) => {
 
 /** Resolve against the session cwd, and keep the agent inside the launch root. */
 export function safe(p) {
-  const abs = resolve(real(session.cwd), p);
+  const abs = realDeep(resolve(real(session.cwd), p));
   const rel = relative(real(session.root), abs);
-  if (rel.startsWith('..')) throw new Error(`refusing to touch path outside ${session.root}: ${p}`);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`refusing to touch path outside ${session.root}: ${p}`);
+  }
   return abs;
 }
 
@@ -123,6 +151,55 @@ function applyCwd(out, mark) {
 
 const MARK = '__KRONK_CWD__';
 
+/**
+ * What is actually confining `bash`, resolved once and reported in the banner.
+ * `pending` until the first command runs, because the preflight costs a process.
+ */
+export const sandbox = { backend: 'pending', reason: null };
+
+/**
+ * Ask the kernel, do not assume.
+ *
+ * `sandbox-exec` exists on every Mac and `bwrap` may be installed but unusable
+ * — unprivileged user namespaces are off on some distros, and a container often
+ * has neither. A backend that fails to launch would turn every command into a
+ * confusing startup error, so it is tried against `true` once and dropped if it
+ * does not work.
+ */
+export function resolveSandbox({ platform = process.platform, env = process.env } = {}) {
+  if (sandbox.backend !== 'pending') return sandbox.backend;
+
+  const mode = env.KRONK_SANDBOX ?? 'auto';
+  const wanted = detectBackend({ platform, env });
+
+  if (wanted === 'none') {
+    sandbox.backend = 'none';
+    sandbox.reason = mode === 'off'
+      ? 'disabled by KRONK_SANDBOX=off'
+      : platform === 'linux' ? 'bwrap not installed' : 'no sandbox backend on this platform';
+    return sandbox.backend;
+  }
+
+  // With the filesystem read-only inside the sandbox these cannot be created
+  // from within it, and a missing ~/.npm would break `npm install` outright.
+  for (const d of cacheDirs(homedir())) {
+    try { mkdirSync(d, { recursive: true }); } catch { /* not fatal — it just stays unwritable */ }
+  }
+
+  const [bin, argv] = sandboxArgv('exit 0', {
+    backend: wanted, root: session.root, home: homedir(), cwd: session.cwd, tmp: real(tmpdir()),
+  });
+  const probe = spawnSync(bin, argv, { stdio: 'ignore', timeout: 10_000 });
+
+  if (probe.error || probe.status !== 0) {
+    sandbox.backend = 'none';
+    sandbox.reason = `${wanted} failed to start`;
+  } else {
+    sandbox.backend = wanted;
+  }
+  return sandbox.backend;
+}
+
 /**
  * Run a shell command, streaming progress to `onProgress` as it goes.
  *
@@ -141,7 +218,16 @@ export function runBash(cmd, { onProgress, timeoutMs = TOOL_TIMEOUT } = {}) {
     // Appending `printf` naively made every command look successful, so
     // failures never reached the agent at all.
     const script = `${cmd}\n__kronk_st=$?\nprintf '\\n${MARK}%s' "$(pwd)"\nexit $__kronk_st`;
-    const child = spawn('bash', ['-c', script], {
+
+    const backend = resolveSandbox();
+    if (backend === 'none' && (process.env.KRONK_SANDBOX ?? 'auto') === 'strict') {
+      return resolve(`error: refusing to run unconfined — KRONK_SANDBOX=strict and ${sandbox.reason}.`);
+    }
+
+    const [bin, argv] = sandboxArgv(script, {
+      backend, root: session.root, home: homedir(), cwd: session.cwd, tmp: real(tmpdir()),
+    });
+    const child = spawn(bin, argv, {
       cwd: session.cwd,
       env: { ...process.env, TERM: 'dumb', CI: process.env.CI ?? '1' },
       detached: true,
@@ -246,7 +332,9 @@ export async function runTool(name, args, opts = {}) {
       }
 
       case 'search': {
-        const where = args.path ?? '.';
+        // Went straight to ripgrep unchecked, so `search` with an absolute path
+        // read anything on the machine while read_file was busy refusing to.
+        const where = safe(args.path ?? '.');
         try {
           const { stdout } = await exec('rg', ['-n', '--no-heading', '-m', '200', args.pattern, where]);
           return clip(stdout) || '(no matches)';