klyro 1.0.0 → 1.0.2

package/dist/tools/fs/edit-file.js

@@ -3,12 +3,51 @@
  * Strict: ambiguous matches fail unless replaceAll=true. Missing match fails.
  */
 import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 import { wasRead } from './read-history.js';
+// Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
+// __tests__ segments — but NOT latest.ts / attest.ts / contest-data.
+const TEST_BASENAME_RE = /(^|[._-])(test|spec)\.[^.]+$|\.test\.[^.]+$|\.spec\.[^.]+$|__(tests|snapshots)__/i;
+function checkRepairGuard(targetPath, _content, deny) {
+    if (!deny)
+        return null;
+    const base = targetPath.split(/[\\/]/).pop() ?? targetPath;
+    // Basename alone decides. File CONTENT is never consulted for non-test
+    // paths (the old assert-skip regex over-blocked ordinary sources
+    // containing e.g. `it(` or `test(`), and stays unconsulted for test-like
+    // paths too since the basename already denies.
+    if (!TEST_BASENAME_RE.test(base))
+        return null;
+    return { ok: false, error: { code: 'POLICY_DENIED', message: 'repair-guard: test edits denied (denyTestEdits)' } };
+}
+async function checkAllowedPaths(cwd, resolved, allowed) {
+    if (!allowed)
+        return null;
+    // Canonicalize both sides (realpath) so lexical-vs-canonical spellings
+    // of the same directory (e.g. Windows 8.3 short names) compare equal.
+    const canon = async (p) => {
+        try {
+            return await fs.realpath(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const canonTarget = await canon(resolved);
+    for (const base of allowed) {
+        const absBase = path.isAbsolute(base) ? path.resolve(base) : path.resolve(cwd, base);
+        const canonBase = await canon(absBase);
+        const rel = path.relative(canonBase, canonTarget);
+        if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)))
+            return null;
+    }
+    return { ok: false, error: { code: 'POLICY_DENIED', message: `agent path not allowed: ${resolved}` } };
+}
 const InputSchema = z.object({
     path: z.string().min(1),
     find: z.string().min(1).describe('Exact substring to match. Not a regex.'),
@@ -36,7 +75,13 @@ export const editFileTool = defineTool({
     renderResult: (output) => `${output.path} ${output.replacements} replacement(s)`,
     execute: async (input, ctx) => {
         return safe(async () => {
+            const guard = checkRepairGuard(input.path, `${input.find}\n${input.replace}`, ctx.repairGuard?.denyTestEdits);
+            if (guard)
+                return guard;
             const { resolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const allowed = await checkAllowedPaths(ctx.cwd, resolved, ctx.agentAllowedPaths);
+            if (allowed)
+                return allowed;
             // 4.1: staleness check via mtime+hash
             const stat = await fs.stat(resolved);
             const raw = await fs.readFile(resolved, 'utf-8');
@@ -112,6 +157,26 @@ export const editFileTool = defineTool({
             // Preserve BOM
             if (hasBOM)
                 next = '\uFEFF' + next;
+            // TOCTOU shrink (mirrors write_file): re-resolve symlinks immediately
+            // before the write and refuse if the target moved. Compares
+            // canonicalized forms (not raw strings) to avoid false positives from
+            // lexical-vs-canonical spellings (e.g. `sub/../a.txt`, short names).
+            const { resolved: reResolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const canon = async (p) => {
+                try {
+                    return await fs.realpath(p);
+                }
+                catch { /* missing file → try parent */ }
+                try {
+                    return path.join(await fs.realpath(path.dirname(p)), path.basename(p));
+                }
+                catch {
+                    return p;
+                }
+            };
+            if ((await canon(reResolved)) !== (await canon(resolved))) {
+                throw Object.assign(new Error(`Path target changed between check and write: ${input.path} (POLICY_DENIED)`), { code: 'POLICY_DENIED' });
+            }
             const tmp = `${resolved}.klyro-edit-${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}.tmp`;
             await fs.writeFile(tmp, next, 'utf-8');
             // Ensure fsync before rename (like write_file)
@@ -122,6 +187,9 @@ export const editFileTool = defineTool({
             finally {
                 await fh.close().catch(() => undefined);
             }
+            // Symlink-swap guard: refuse if the final dest became a symlink
+            // since the up-front resolve (lstat never follows the final link).
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/fs/multi-edit.d.ts

@@ -9,6 +9,10 @@ export declare const multiEditTool: import("../types.js").Tool<{
         replaceAll?: boolean | undefined;
     }[];
 }, {
+    path: string;
+    edits: number;
+    diff: string;
+} | {
     readonly path: string;
     readonly edits: number;
     readonly diff: `multi_edit ${number} edits`;

package/dist/tools/fs/multi-edit.js

@@ -5,10 +5,49 @@ import * as fs from 'node:fs/promises';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
 import { wasRead } from './read-history.js';
 import { checkStaleness, recordEditStaleness } from './edit-file.js';
+import * as path from 'node:path';
+// Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
+// __tests__ segments — but NOT latest.ts / attest.ts / contest-data.
+const TEST_BASENAME_RE = /(^|[._-])(test|spec)\.[^.]+$|\.test\.[^.]+$|\.spec\.[^.]+$|__(tests|snapshots)__/i;
+function checkRepairGuard(targetPath, _content, deny) {
+    if (!deny)
+        return null;
+    const base = targetPath.split(/[\\/]/).pop() ?? targetPath;
+    // Basename alone decides. File CONTENT is never consulted for non-test
+    // paths (the old assert-skip regex over-blocked ordinary sources
+    // containing e.g. `it(` or `test(`), and stays unconsulted for test-like
+    // paths too since the basename already denies.
+    if (!TEST_BASENAME_RE.test(base))
+        return null;
+    return { ok: false, error: { code: 'POLICY_DENIED', message: 'repair-guard: test edits denied (denyTestEdits)' } };
+}
+async function checkAllowedPaths(cwd, resolved, allowed) {
+    if (!allowed)
+        return null;
+    // Canonicalize both sides (realpath) so lexical-vs-canonical spellings
+    // of the same directory (e.g. Windows 8.3 short names) compare equal.
+    const canon = async (p) => {
+        try {
+            return await fs.realpath(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const canonTarget = await canon(resolved);
+    for (const base of allowed) {
+        const absBase = path.isAbsolute(base) ? path.resolve(base) : path.resolve(cwd, base);
+        const canonBase = await canon(absBase);
+        const rel = path.relative(canonBase, canonTarget);
+        if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)))
+            return null;
+    }
+    return { ok: false, error: { code: 'POLICY_DENIED', message: `agent path not allowed: ${resolved}` } };
+}
 const EditSchema = z.object({
     find: z.string().min(1),
     replace: z.string(),
@@ -26,7 +65,14 @@ export const multiEditTool = defineTool({
     isConcurrencySafe: false,
     execute: async (input, ctx) => {
         return safe(async () => {
+            const combined = input.edits.map((e) => `${e.find}\n${e.replace}`).join('\n');
+            const guard = checkRepairGuard(input.path, combined, ctx.repairGuard?.denyTestEdits);
+            if (guard)
+                return guard;
             const { resolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const allowed = await checkAllowedPaths(ctx.cwd, resolved, ctx.agentAllowedPaths);
+            if (allowed)
+                return allowed;
             const stat = await fs.stat(resolved);
             let content = await fs.readFile(resolved, 'utf-8');
             if (checkStaleness(resolved, stat.mtimeMs, crypto.createHash('sha256').update(content, 'utf-8').digest('hex'))) {
@@ -44,8 +90,31 @@ export const multiEditTool = defineTool({
                     throw Object.assign(new Error(`edit ${i}: ambiguous (${count} matches)`), { code: 'MATCH_AMBIGUOUS' });
                 content = e.replaceAll ? content.split(e.find).join(e.replace) : content.replace(e.find, e.replace);
             }
+            // TOCTOU shrink (mirrors write_file): re-resolve symlinks immediately
+            // before the write and refuse if the target moved. Compares
+            // canonicalized forms (not raw strings) to avoid false positives from
+            // lexical-vs-canonical spellings (e.g. `sub/../a.txt`, short names).
+            const { resolved: reResolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const canon = async (p) => {
+                try {
+                    return await fs.realpath(p);
+                }
+                catch { /* missing file → try parent */ }
+                try {
+                    return path.join(await fs.realpath(path.dirname(p)), path.basename(p));
+                }
+                catch {
+                    return p;
+                }
+            };
+            if ((await canon(reResolved)) !== (await canon(resolved))) {
+                throw Object.assign(new Error(`Path target changed between check and write: ${input.path} (POLICY_DENIED)`), { code: 'POLICY_DENIED' });
+            }
             const tmp = `${resolved}.klyro-multi-${Date.now()}.tmp`;
             await fs.writeFile(tmp, content, 'utf-8');
+            // Symlink-swap guard: refuse if the final dest became a symlink
+            // since the up-front resolve (lstat never follows the final link).
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/fs/write-file.js

@@ -5,12 +5,51 @@
  * directories if needed.
  */
 import * as fs from 'node:fs/promises';
+import * as fsSyncNode from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { z } from 'zod';
 import { defineTool } from '../types.js';
-import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { resolveAndFollowSymlinks, assertNotSymlink, openNoFollowForWrite } from '../../policy/path-guard.js';
 import { safe } from '../normalize.js';
+// Extension-anchored: matches test.ts, foo.test.ts, foo-test.ts, foo.spec.js,
+// __tests__ segments — but NOT latest.ts / attest.ts / contest-data.
+const TEST_BASENAME_RE = /(^|[._-])(test|spec)\.[^.]+$|\.test\.[^.]+$|\.spec\.[^.]+$|__(tests|snapshots)__/i;
+function checkRepairGuard(targetPath, _content, deny) {
+    if (!deny)
+        return null;
+    const base = targetPath.split(/[\\/]/).pop() ?? targetPath;
+    // Basename alone decides. File CONTENT is never consulted for non-test
+    // paths (the old assert-skip regex over-blocked ordinary sources
+    // containing e.g. `it(` or `test(`), and stays unconsulted for test-like
+    // paths too since the basename already denies.
+    if (!TEST_BASENAME_RE.test(base))
+        return null;
+    return { ok: false, error: { code: 'POLICY_DENIED', message: 'repair-guard: test edits denied (denyTestEdits)' } };
+}
+async function checkAllowedPaths(cwd, resolved, allowed) {
+    if (!allowed)
+        return null;
+    // Canonicalize both sides (realpath) so lexical-vs-canonical spellings
+    // of the same directory (e.g. Windows 8.3 short names) compare equal.
+    const canon = async (p) => {
+        try {
+            return await fs.realpath(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const canonTarget = await canon(resolved);
+    for (const base of allowed) {
+        const absBase = path.isAbsolute(base) ? path.resolve(base) : path.resolve(cwd, base);
+        const canonBase = await canon(absBase);
+        const rel = path.relative(canonBase, canonTarget);
+        if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)))
+            return null;
+    }
+    return { ok: false, error: { code: 'POLICY_DENIED', message: `agent path not allowed: ${resolved}` } };
+}
 const InputSchema = z.object({
     path: z.string().min(1).describe('Path relative to cwd or absolute (must be inside cwd)'),
     content: z.string().describe('File content. Use empty string to truncate.'),
@@ -26,7 +65,13 @@ export const writeFileTool = defineTool({
     renderResult: (output) => `${output.path} written ${output.bytesWritten} bytes`,
     execute: async (input, ctx) => {
         return safe(async () => {
+            const guard = checkRepairGuard(input.path, input.content, ctx.repairGuard?.denyTestEdits);
+            if (guard)
+                return guard;
             const { resolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const allowed = await checkAllowedPaths(ctx.cwd, resolved, ctx.agentAllowedPaths);
+            if (allowed)
+                return allowed;
             const parent = path.dirname(resolved);
             await fs.mkdir(parent, { recursive: true });
             // 3.2: if file exists and was not read this session, warn but allow with diff
@@ -44,15 +89,47 @@ export const writeFileTool = defineTool({
             const suffix = crypto.randomBytes(8).toString('hex');
             const tmp = path.join(parent, `.klyro-write-${process.pid}-${suffix}.tmp`);
             const data = Buffer.from(input.content, 'utf-8');
-            // Truncate to 8k tokens ~32k chars for result
-            const fh = await fs.open(tmp, 'w');
+            // TOCTOU shrink (not elimination): re-resolve symlinks immediately
+            // before the write and refuse if the target moved. A racing swap
+            // between this check and rename can still occur.
+            // NOTE: the pre-check resolution may be lexical (parent missing) while
+            // the re-resolution is canonical (parent now exists), so compare
+            // canonicalized forms — not raw strings — to avoid false positives
+            // (e.g. Windows 8.3 short-name expansion after mkdir).
+            const { resolved: reResolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const canon = async (p) => {
+                try {
+                    return await fs.realpath(p);
+                }
+                catch { /* missing file → try parent */ }
+                try {
+                    return path.join(await fs.realpath(path.dirname(p)), path.basename(p));
+                }
+                catch {
+                    return p;
+                }
+            };
+            if ((await canon(reResolved)) !== (await canon(resolved))) {
+                throw Object.assign(new Error(`Path target changed between check and write: ${input.path} (POLICY_DENIED)`), { code: 'POLICY_DENIED' });
+            }
+            // Truncate to 8k tokens ~32k chars for result.
+            // The tmp file is opened O_NOFOLLOW (POSIX; plain 'w' on Windows —
+            // see openNoFollowForWrite) so a planted link at the fresh tmp name
+            // can't redirect the content write; atomic tmp+rename semantics stay.
+            const fd = openNoFollowForWrite(parent, path.basename(tmp));
             try {
-                await fh.writeFile(data);
-                await fh.sync();
+                fsSyncNode.writeFileSync(fd, data);
+                fsSyncNode.fsyncSync(fd);
             }
             finally {
-                await fh.close().catch(() => undefined);
+                try {
+                    fsSyncNode.closeSync(fd);
+                }
+                catch { /* already closed */ }
             }
+            // Symlink-swap guard: lstat the final dest immediately before rename
+            // and refuse if it became a symlink since the up-front resolve.
+            await assertNotSymlink(resolved);
             try {
                 await fs.rename(tmp, resolved);
             }

package/dist/tools/plan/todo-write.js

@@ -14,7 +14,7 @@ export const todoWriteTool = defineTool({
     name: 'todo_write',
     description: 'Update the live plan checklist. Persisted and re-injected when stale.',
     inputSchema: InputSchema,
-    permission: 'read',
+    permission: 'edit',
     isConcurrencySafe: true,
     execute: async (input, ctx) => {
         return safe(async () => {

package/dist/tools/registry.js

@@ -28,6 +28,9 @@ import { memoryWriteTool } from './memory-write.js';
 import { spawnAgentTool } from './agent/spawn-agent.js';
 import { taskListTool } from './agent/task-list.js';
 import { taskGetTool } from './agent/task-get.js';
+import { taskWaitTool } from './agent/task-wait.js';
+import { taskStopTool } from './agent/task-stop.js';
+import { taskApplyTool } from './agent/task-apply.js';
 import { zodToJsonSchema } from './schema.js';
 export class ToolRegistry {
     tools = new Map();
@@ -113,5 +116,8 @@ export const builtinRegistry = () => {
     r.register(spawnAgentTool);
     r.register(taskListTool);
     r.register(taskGetTool);
+    r.register(taskWaitTool);
+    r.register(taskStopTool);
+    r.register(taskApplyTool);
     return r;
 };

package/dist/tools/shell/background.js

@@ -2,7 +2,7 @@
  * 4.3 — Background shell: shell(run_in_background), bash_output, kill_shell, /jobs
  */
 import { spawn } from 'node:child_process';
-import { findBlockedReason } from './shell-exec.js';
+import { findBlockedReason, filteredEnv } from './shell-exec.js';
 const jobs = new Map();
 let counter = 0;
 const MAX_JOBS = 5;
@@ -32,7 +32,9 @@ export function startBackground(command, cwd) {
     if (blocked)
         throw new Error(`Command blocked: ${blocked}`);
     const id = `job-${++counter}-${Date.now().toString(36)}`;
-    const proc = spawn(command, { cwd, shell: true, windowsHide: true });
+    // Filtered env, same call shape as shell_exec — background children must
+    // not inherit secrets from the parent process.
+    const proc = spawn(command, { cwd, shell: true, windowsHide: true, env: filteredEnv() });
     const job = { id, command, cwd, proc, output: '', start: Date.now() };
     jobs.set(id, job);
     proc.stdout?.on('data', (b) => { job.output += b.toString(); if (job.output.length > 1_000_000)
@@ -56,7 +58,8 @@ export function startBackgroundArgv(argv, cwd) {
     if (argv.length === 0)
         throw new Error('startBackgroundArgv requires argv');
     const id = `job-${++counter}-${Date.now().toString(36)}`;
-    const proc = spawn(argv[0], argv.slice(1), { cwd, shell: false, windowsHide: true });
+    // Filtered env, same call shape as shell_exec (see startBackground).
+    const proc = spawn(argv[0], argv.slice(1), { cwd, shell: false, windowsHide: true, env: filteredEnv() });
     const job = { id, command: argv.join(' '), cwd, proc, output: '', start: Date.now() };
     jobs.set(id, job);
     proc.stdout?.on('data', (b) => { job.output += b.toString(); if (job.output.length > 1_000_000)

package/dist/tools/shell/sandbox.d.ts

@@ -0,0 +1,51 @@
+/**
+ * G1-1 — OS-level sandbox shim for shell/subprocess tools.
+ *
+ * Bounds even a *compromised* tool call by the kernel, not by policy. Path
+ * guards + the destructive-pattern denylist stop a cooperative model; this
+ * is the layer that stops an exploited one.
+ *
+ * Backend strategy (defense-in-depth, cheapest-first):
+ *   - `bwrap` (bubblewrap) — rootless, cross-distro, the same primitive Claude
+ *     Code's sandbox docs reference. Primary backend when present.
+ *   - landlock — kernel LSM, no helper binary needed, but requires a native
+ *     syscall helper Node can't invoke directly. Tracked for the next step.
+ *
+ * Detection is done once at startup and cached. When no backend is present we
+ * *degrade cleanly* to `undefined` — an empty sandbox command and a clearly
+ * reported status, never a pretend "sandboxed" that isn't.
+ */
+export type SandboxBackend = 'bwrap' | 'none';
+export interface SandboxStatus {
+    backend: SandboxBackend;
+    /** True when a real kernel/namespace boundary will be applied. */
+    active: boolean;
+    /** Human-readable why — for /sandbox and the trust gate. */
+    reason: string;
+}
+/**
+ * One-time detection. Cached for the process lifetime so we don't fork a
+ * probe on every tool call. bwrap only — landlock is a follow-on.
+ */
+export declare function detectSandbox(): SandboxStatus;
+/**
+ * Build a bwrap argv-wrapper for a command, bounding:
+ *   - filesystem: read-only root, bind cwd read-write (only the permitted dir)
+ *   - network: disabled (--unshare-net) for tool calls by default
+ *   - process: new PID/user namespace (--unshare-pid --unshare-user)
+ *   - devices/sockets: stripped of host access
+ *
+ * Returns `undefined` when no backend is active — the caller then runs the
+ * command normally. Sandbox is opt-out of the *command namespace*, never a
+ * silent no-op that claims to be sandboxed.
+ */
+export declare function sandboxCommand(cmd: string, args: string[], opts: {
+    cwd: string;
+    readWriteDirs?: string[];
+    allowNetwork?: boolean;
+}): {
+    cmd: string;
+    args: string[];
+} | undefined;
+/** Reset detection (tests). */
+export declare function resetSandbox(): void;

package/dist/tools/shell/sandbox.js

@@ -0,0 +1,143 @@
+/**
+ * G1-1 — OS-level sandbox shim for shell/subprocess tools.
+ *
+ * Bounds even a *compromised* tool call by the kernel, not by policy. Path
+ * guards + the destructive-pattern denylist stop a cooperative model; this
+ * is the layer that stops an exploited one.
+ *
+ * Backend strategy (defense-in-depth, cheapest-first):
+ *   - `bwrap` (bubblewrap) — rootless, cross-distro, the same primitive Claude
+ *     Code's sandbox docs reference. Primary backend when present.
+ *   - landlock — kernel LSM, no helper binary needed, but requires a native
+ *     syscall helper Node can't invoke directly. Tracked for the next step.
+ *
+ * Detection is done once at startup and cached. When no backend is present we
+ * *degrade cleanly* to `undefined` — an empty sandbox command and a clearly
+ * reported status, never a pretend "sandboxed" that isn't.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+let cachedStatus = null;
+/** Walk $PATH for an executable without shells. Returns null when absent. */
+function findOnPath(bin) {
+    const paths = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+    for (const dir of paths) {
+        const p = path.join(dir, bin);
+        try {
+            if (fs.statSync(p).isFile() && p.endsWith(bin))
+                return p;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return null;
+}
+/** True when `bwrap --version` runs and reports a sane bubblewrap build. */
+function bwrapUsable(binPath) {
+    try {
+        const r = spawnSync(binPath, ['--version'], { encoding: 'utf-8', timeout: 2000, windowsHide: true });
+        return r.status === 0 && r.stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One-time detection. Cached for the process lifetime so we don't fork a
+ * probe on every tool call. bwrap only — landlock is a follow-on.
+ */
+export function detectSandbox() {
+    if (cachedStatus)
+        return cachedStatus;
+    // bubblewrap is POSIX-only; Windows guards are policy+path only (documented
+    // honestly — Windows receives a native sandbox in G1-3 via a microVM).
+    if (process.platform === 'win32') {
+        cachedStatus = {
+            backend: 'none',
+            active: false,
+            reason: 'native sandbox not yet available on win32 (G1-3 microVM planned); policy+path guards active',
+        };
+        return cachedStatus;
+    }
+    const bwrap = findOnPath('bwrap');
+    if (bwrap && bwrapUsable(bwrap)) {
+        cachedStatus = { backend: 'bwrap', active: true, reason: `bubblewrap at ${bwrap}` };
+        return cachedStatus;
+    }
+    cachedStatus = {
+        backend: 'none',
+        active: false,
+        reason: 'bwrap not found on $PATH — install bubblewrap (e.g. `apt install bubblewrap`) or run unsandboxed; policy+path guards remain active',
+    };
+    return cachedStatus;
+}
+/**
+ * Build a bwrap argv-wrapper for a command, bounding:
+ *   - filesystem: read-only root, bind cwd read-write (only the permitted dir)
+ *   - network: disabled (--unshare-net) for tool calls by default
+ *   - process: new PID/user namespace (--unshare-pid --unshare-user)
+ *   - devices/sockets: stripped of host access
+ *
+ * Returns `undefined` when no backend is active — the caller then runs the
+ * command normally. Sandbox is opt-out of the *command namespace*, never a
+ * silent no-op that claims to be sandboxed.
+ */
+export function sandboxCommand(cmd, args, opts) {
+    const status = detectSandbox();
+    if (!status.active)
+        return undefined;
+    const roDirs = ['/usr', '/bin', '/etc', '/lib', '/lib64', '/opt'];
+    const bwrapArgs = [
+        '--unshare-all',
+        '--ro-bind',
+        '/usr',
+        '/usr',
+        '--ro-bind',
+        '/bin',
+        '/bin',
+        '--ro-bind',
+        '/etc',
+        '/etc',
+        '--ro-bind',
+        '/lib',
+        '/lib',
+        '--ro-bind',
+        '/lib64',
+        '/lib64',
+        '--ro-bind',
+        '/opt',
+        '/opt',
+        '--dev',
+        '/dev',
+        '--proc',
+        '/proc',
+        '--tmpfs',
+        '/tmp',
+    ];
+    // Read-write: the permitted cwd (and any explicitly allowed dirs) only.
+    const rw = [opts.cwd, ...(opts.readWriteDirs ?? [])];
+    for (const d of roDirs)
+        void d; // (kept for parity with the read-only surface)
+    for (const d of rw) {
+        bwrapArgs.push('--bind', d, d);
+    }
+    // A clean, empty HOME so the child can't read the operator's dotfiles.
+    bwrapArgs.push('--tmpfs', '/root');
+    bwrapArgs.push('--clearenv');
+    bwrapArgs.push('--setenv', 'PATH', '/usr/bin:/bin:/usr/local/bin');
+    bwrapArgs.push('--setenv', 'HOME', '/root');
+    bwrapArgs.push('--chdir', opts.cwd);
+    if (!opts.allowNetwork) {
+        // Default: sandboxed tool calls are offline. Exfiltration via curl/wget is
+        // already denylisted at the policy layer; this is the belt-and-suspenders.
+        bwrapArgs.push('--unshare-net');
+    }
+    bwrapArgs.push('--', cmd, ...args);
+    return { cmd: 'bwrap', args: bwrapArgs };
+}
+/** Reset detection (tests). */
+export function resetSandbox() {
+    cachedStatus = null;
+}

package/dist/tools/shell/shell-exec.d.ts

@@ -17,6 +17,35 @@ declare const InputSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Reset the sticky cwd (e.g. after /cd changes the session directory). */
 export declare function resetPersistentCwd(): void;
+export declare function filteredEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;
+/**
+ * Protected-branch push helpers (mirror policy engine shellDenyRule).
+ * `git push` targeting main/master/production is denied outright; a bare
+ * `git push` (no ref args) is denied when the checkout sits on a protected
+ * branch. Escape hatch: KLYRO_ALLOW_MAIN_PUSH=1.
+ */
+export declare const PROTECTED_BRANCHES: string[];
+export declare const PROTECTED_PUSH_RE: RegExp;
+/**
+ * True when KLYRO_ALLOW_MAIN_PUSH=1 opts out of the protected-push deny. */
+export declare function isMainPushEscape(): boolean;
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export declare function isBareGitPush(cmd: string): boolean;
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal flow to continue.
+ */
+export declare function currentGitBranch(cwd: string): string | null;
+/**
+ * Bare-push check with cwd: deny `git push` with no ref args when the
+ * checkout is on a protected branch. Returns the block reason or null.
+ */
+export declare function findBareProtectedPushReason(command: string, cwd: string): string | null;
 /**
  * Shared dangerous-command check (also used by background shells).
  * Returns the block reason, or null when the command is not hard-blocked.