@kendoo.agentdesk/agentdesk 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -8,6 +8,16 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.17.2] — 2026-04-18
+
+### Changed
+- `[UI]` Docs and Guide pages now describe the per-session isolation and the kernel-enforced sandbox — what's blocked, what the scoped-env fallback is, and how to opt out. README's security section mirrors the same copy.
+
+## [0.17.1] — 2026-04-18
+
+### Added
+- `[CLI]` Sessions now run inside a kernel-enforced sandbox when one is available — `sandbox-exec` on macOS, `bwrap` (bubblewrap) on Linux. Writes outside the project directory and the session's scratch home are blocked at the kernel level; reads from known credential locations (`~/.ssh`, `~/.aws`, `~/.config/gh`, `~/.gitconfig`, `~/.netrc`, etc.) are denied so a confused agent cannot slurp up other projects' tokens. If the tool isn't installed (Linux without `bubblewrap` / unsupported platform), sessions fall back to the Tier 1 scoped-env isolation and a one-line notice explains why. Set `AGENTDESK_NO_SANDBOX=1` to opt out for debugging.
+
 ## [0.17.0] — 2026-04-18
 
 ### Added

package/README.md

@@ -224,6 +224,8 @@ Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.
 
 ### Security
 
+- **Per-session identity isolation** — every session runs with `HOME` / `GH_CONFIG_DIR` / `XDG_CONFIG_HOME` pointed at a private scratch dir containing only this project's tracker credentials and commit identity. `gh`, `git`, and `ssh` inside the session cannot see your global accounts, other projects' tokens, or keys elsewhere on disk.
+- **Kernel-enforced sandbox when available** — on macOS (`sandbox-exec`) and Linux (`bwrap` / bubblewrap), sessions run with writes restricted to the project dir + scratch home + `/tmp`, and reads denied on known credential locations (`~/.ssh`, `~/.aws`, `~/.config/gh`, `~/.gitconfig`, `~/.netrc`, etc.). If the tool isn't available, sessions fall back to scoped-env isolation with a one-line notice. Opt out for debugging with `AGENTDESK_NO_SANDBOX=1`.
 - **Outbound only** — no ports opened on your machine
 - **Project allowlist** — only runs on projects registered via `agentdesk init`
 - **No arbitrary commands** — only spawns Claude with a fixed set of allowed tools

package/cli/orchestrator.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "url";
 import { buildPrompt, buildSoloPrompt, buildPhasedPrompt } from "./prompt.mjs";
 import { createStreamParser } from "./stream-parser.mjs";
 import { createScratchHome } from "./session-sandbox.mjs";
+import { wrapIsolatedSpawn, probeIsolation } from "./session-isolation.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")).version;
@@ -123,9 +124,21 @@ export async function runOrchestrator({
   emit({ type: "phase:change", phase: initialPhase, model: representativeModel });
 
   const modelArgs = modelArgsForPhase("EXECUTION", config?.phaseModels);
+  const wrapped = wrapIsolatedSpawn({
+    cmd: "claude",
+    args: ["-p", fullPrompt, ...modelArgs, "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep", "--verbose", "--output-format", "stream-json"],
+    cwd,
+    scratchHome: sandbox.home,
+    sessionId,
+  });
+  if (wrapped.isolation.kind !== "none") {
+    console.error(`[agentdesk] session isolation: ${wrapped.isolation.kind}`);
+  } else if (wrapped.isolation.reason) {
+    console.error(`[agentdesk] hard isolation unavailable (${wrapped.isolation.reason}) — scoped-env only`);
+  }
   const child = spawn(
-    "claude",
-    ["-p", fullPrompt, ...modelArgs, "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep", "--verbose", "--output-format", "stream-json"],
+    wrapped.cmd,
+    wrapped.args,
     { stdio: ["pipe", "pipe", "inherit"], shell: false, env, cwd }
   );
   child.stdin.end();
@@ -221,10 +234,17 @@ export async function runOrchestrator({
 
 // --- Phased orchestrator: runs 3 sequential Claude processes ---
 
-async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [] }) {
+async function runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs = [], scratchHome, sessionId }) {
+  const wrapped = wrapIsolatedSpawn({
+    cmd: "claude",
+    args: ["-p", prompt, ...modelArgs, "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep", "--verbose", "--output-format", "stream-json"],
+    cwd,
+    scratchHome,
+    sessionId,
+  });
   const child = spawn(
-    "claude",
-    ["-p", prompt, ...modelArgs, "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep", "--verbose", "--output-format", "stream-json"],
+    wrapped.cmd,
+    wrapped.args,
     { stdio: ["pipe", "pipe", "inherit"], shell: false, env, cwd }
   );
   child.stdin.end();
@@ -278,6 +298,13 @@ export async function runPhasedOrchestrator({
   const startTime = Date.now();
   const teamNames = teamSections.names;
 
+  const probe = probeIsolation();
+  if (probe.kind !== "none") {
+    console.error(`[agentdesk] session isolation: ${probe.kind}`);
+  } else {
+    console.error(`[agentdesk] hard isolation unavailable (${probe.reason}) — scoped-env only`);
+  }
+
   function timestamp() {
     const d = new Date();
     return [d.getHours(), d.getMinutes(), d.getSeconds()].map(n => String(n).padStart(2, "0")).join(":");
@@ -330,7 +357,7 @@ export async function runPhasedOrchestrator({
     });
 
     const modelArgs = modelArgsForPhase(phase, config?.phaseModels);
-    const result = await runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs });
+    const result = await runSinglePhase({ prompt, cwd, env, teamNames, emit, modelArgs, scratchHome: sandbox.home, sessionId });
 
     if (onChild) onChild(result.child);
 

package/cli/session-isolation.mjs

@@ -0,0 +1,160 @@
+// Tier 2 kernel-enforced isolation.
+//
+// On top of the scoped HOME from session-sandbox.mjs, wrap the Claude child
+// process in a kernel sandbox when one is available:
+//   - macOS: `sandbox-exec` (TrustedBSD sandbox, same primitive App Sandbox uses)
+//   - Linux: `bwrap` (bubblewrap — mount namespaces, same primitive Docker uses)
+//
+// Failure mode: if the tool isn't present or the profile can't be written,
+// we emit a one-line notice and spawn the child as normal. The scoped HOME
+// from Phase E still applies — isolation just degrades from "kernel boundary"
+// to "scoped env."
+//
+// Escape hatch: AGENTDESK_NO_SANDBOX=1 skips this layer entirely.
+
+import { execSync } from "child_process";
+import { existsSync, writeFileSync } from "fs";
+import { join } from "path";
+import { platform, homedir } from "os";
+
+// Detect which kernel-isolation tool is usable. Cached after first probe.
+let cachedProbe = null;
+export function probeIsolation() {
+  if (cachedProbe) return cachedProbe;
+  if (process.env.AGENTDESK_NO_SANDBOX === "1") {
+    cachedProbe = { kind: "none", reason: "AGENTDESK_NO_SANDBOX=1 set" };
+    return cachedProbe;
+  }
+  if (platform() === "darwin") {
+    try {
+      execSync("command -v sandbox-exec", { stdio: "pipe" });
+      cachedProbe = { kind: "sandbox-exec" };
+      return cachedProbe;
+    } catch {
+      cachedProbe = { kind: "none", reason: "sandbox-exec not found" };
+      return cachedProbe;
+    }
+  }
+  if (platform() === "linux") {
+    try {
+      execSync("command -v bwrap", { stdio: "pipe" });
+      cachedProbe = { kind: "bwrap" };
+      return cachedProbe;
+    } catch {
+      cachedProbe = { kind: "none", reason: "bubblewrap not installed — apt install bubblewrap / brew install bubblewrap" };
+      return cachedProbe;
+    }
+  }
+  cachedProbe = { kind: "none", reason: `no isolation tool for platform ${platform()}` };
+  return cachedProbe;
+}
+
+// Build the spawn arguments for an isolated claude invocation. Takes the
+// original command/args/options and returns the wrapped form, plus a flag
+// indicating which isolation mode is active.
+export function wrapIsolatedSpawn({ cmd, args, cwd, scratchHome, sessionId }) {
+  const probe = probeIsolation();
+  if (probe.kind === "none") {
+    return { cmd, args, isolation: { kind: "none", reason: probe.reason } };
+  }
+
+  if (probe.kind === "sandbox-exec") {
+    const profilePath = join(scratchHome, "sandbox.sb");
+    writeFileSync(profilePath, macosProfile({ cwd, scratchHome }), { mode: 0o600 });
+    return {
+      cmd: "sandbox-exec",
+      args: ["-f", profilePath, cmd, ...args],
+      isolation: { kind: "sandbox-exec" },
+    };
+  }
+
+  if (probe.kind === "bwrap") {
+    return {
+      cmd: "bwrap",
+      args: [...bwrapArgs({ cwd, scratchHome }), cmd, ...args],
+      isolation: { kind: "bwrap" },
+    };
+  }
+
+  return { cmd, args, isolation: { kind: "none", reason: "unknown probe kind" } };
+}
+
+// --- macOS sandbox-exec profile ---------------------------------------------
+
+function macosProfile({ cwd, scratchHome }) {
+  const home = homedir();
+  // Known-sensitive user paths where credentials typically live. Reads denied
+  // even though general reads are allowed, so a confused agent can't slurp
+  // up other projects' tokens or the user's SSH keys.
+  const denyReadPaths = [
+    join(home, ".ssh"),
+    join(home, ".aws"),
+    join(home, ".gcloud"),
+    join(home, ".config", "gh"),         // real gh config (scratch is under $TMPDIR)
+    join(home, ".docker"),
+    join(home, ".kube"),
+    join(home, ".agentdesk"),
+    join(home, ".config", "agentdesk"),
+  ];
+  const denyReadLiterals = [
+    join(home, ".netrc"),
+    join(home, ".gitconfig"),            // real gitconfig (scratch has its own)
+    join(home, ".npmrc"),
+    join(home, ".pypirc"),
+  ];
+
+  // Writes allowed only here. Everywhere else: read-only by default.
+  const writeSubpaths = [
+    cwd,
+    scratchHome,
+    "/tmp",
+    "/private/tmp",
+    "/private/var/folders",              // macOS TMPDIR lives here
+  ];
+
+  const sb = [
+    `(version 1)`,
+    `(allow default)`,
+    ``,
+    `; Deny reads to known credential locations`,
+    ...denyReadPaths.map(p => `(deny file-read* (subpath ${sbString(p)}))`),
+    ...denyReadLiterals.map(p => `(deny file-read* (literal ${sbString(p)}))`),
+    ``,
+    `; Writes: deny everywhere, then allow the project dir + scratch + tmp`,
+    `(deny file-write*)`,
+    ...writeSubpaths.map(p => `(allow file-write* (subpath ${sbString(p)}))`),
+    ``,
+    `; Allow writes to devices so stdio, /dev/null, tty, ptys all work`,
+    `(allow file-write* (subpath "/dev"))`,
+    ``,
+  ].join("\n");
+
+  return sb;
+}
+
+function sbString(s) {
+  return `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+// --- Linux bwrap args --------------------------------------------------------
+
+function bwrapArgs({ cwd, scratchHome }) {
+  // Everything read-only by default via ro-bind of /. Writable exceptions:
+  // the project dir, the scratch HOME, and a private /tmp. /home/<user> is
+  // replaced with a tmpfs so the agent can't browse the real home dir.
+  const home = homedir();
+  return [
+    "--ro-bind", "/", "/",
+    "--dev-bind", "/dev", "/dev",
+    "--proc", "/proc",
+    "--tmpfs", "/tmp",
+    "--tmpfs", home,                     // blank user home
+    "--bind", cwd, cwd,                  // project dir writable
+    "--bind", scratchHome, scratchHome,  // scratch writable (HOME env var points here)
+    "--die-with-parent",
+    "--unshare-ipc",
+    "--unshare-uts",
+    "--unshare-pid",
+    // Network is NOT unshared — agents need network for tracker APIs and git.
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {