@tealbrick/kit 0.3.0-rc.6 → 0.3.0-rc.8

package/dist/native-claude.js

@@ -1,8 +1,13 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { isIP } from 'node:net';
+import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { realpath } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { servePaths } from './native-serve-config.js';
 export async function loadClaudeSdk(root, sdkModule) {
     let entry;
     try {
@@ -18,10 +23,28 @@ export async function loadClaudeSdk(root, sdkModule) {
 }
 /** Built-in tools Restricted mode exposes: read-only and contained to the workspace. */
 export const readOnlyTools = ['Read', 'Glob', 'Grep'];
+/**
+ * Built-in tools of the sandboxed workspace session. Every file operation goes through the OS-sandboxed
+ * Bash: the in-process file tools resolve paths outside the sandbox (symlink and check/use races), so
+ * the workspace session never gets any of them (see unsandboxedFileTools).
+ */
+/** POSIX single-quote a value for a shell command line. */
+const shq = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
+export const workspaceTools = ['Bash', 'WebSearch', 'WebFetch', 'Agent'];
+/** Claude Code's per-cwd temp folder name: every non-alphanumeric character becomes '-'. */
+export const claudeTmpSlug = (dir) => dir.replace(/[^A-Za-z0-9]/g, '-');
+/** Claude Code's sandbox temp roots for this OS user (sandboxed Bash TMPDIR), shared by every session of the user. */
+export const claudeTmpRoots = (uid) => [`/tmp/claude-${uid}`, `/private/tmp/claude-${uid}`];
+/** In-process (unsandboxed) filesystem tools: never available in the sandboxed workspace session, owner or expert. */
+export const unsandboxedFileTools = ['Read', 'Write', 'Edit', 'MultiEdit', 'Glob', 'Grep', 'LS', 'NotebookEdit', 'NotebookRead'];
+/** Homebrew prefixes the sandboxed shell keeps reading (only those present are listed). Never the whole /opt/homebrew. */
+export const homebrewReadRoots = ['bin', 'lib', 'include', 'share', 'opt', 'Cellar'].map(d => '/opt/homebrew/' + d);
 /** Removed from the model's context unless a wider access mode explicitly lists them. */
 export const restrictedDenied = ['Bash', 'BashOutput', 'KillShell', 'KillBash', 'Monitor', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'WebFetch', 'WebSearch', 'Agent', 'Task', 'TodoWrite', 'Skill', 'SlashCommand', 'ExitPlanMode', 'EnterWorktree', 'ExitWorktree'];
 const pathTools = { Read: ['file_path'], Write: ['file_path'], Edit: ['file_path'], MultiEdit: ['file_path'], NotebookEdit: ['notebook_path'], Glob: ['path'], Grep: ['path'] };
 const safeEnvNames = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LC_ALL', 'SSL_CERT_FILE', 'NODE_EXTRA_CA_CERTS'];
+/** Chat-relay identity secrets: never forwarded to the SDK process, even if listed in envPassthrough. */
+export const neverForwardedEnv = ['BUZZ_PRIVATE_KEY', 'BUZZ_AUTH_TAG', 'BUZZ_ACP_PRIVATE_KEY', 'BUZZ_API_TOKEN', 'BUZZ_ACP_API_TOKEN', 'NOSTR_PRIVATE_KEY'];
 async function contained(root, input, deny) {
     let path = resolve(root, input), tail = [];
     for (;;) {
@@ -40,14 +63,108 @@ async function contained(root, input, deny) {
         }
     }
     const inside = (base) => { const rel = relative(base, path); return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); };
-    return inside(await realpath(root)) && !deny.some(inside);
+    if (deny.some(inside))
+        return false;
+    return inside(await realpath(root));
+}
+const PRIVATE_SUFFIXES = ['.localhost', '.local', '.internal', '.ts.net'];
+function privateIPv4(ip) {
+    const [a = 0, b = 0] = ip.split('.').map(Number);
+    return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);
+}
+function ipv6Words(ip) {
+    let text = ip;
+    const v4 = /(\d+\.\d+\.\d+\.\d+)$/.exec(text)?.[1];
+    if (v4) {
+        const [a, b, c, d] = v4.split('.').map(Number);
+        text = text.slice(0, -v4.length) + ((a << 8) | b).toString(16) + ':' + ((c << 8) | d).toString(16);
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const part = (h) => h ? h.split(':').map(x => parseInt(x, 16)) : [];
+    const head = part(halves[0]), tail = halves.length === 2 ? part(halves[1]) : [];
+    const words = halves.length === 2 ? [...head, ...Array(8 - head.length - tail.length).fill(0), ...tail] : head;
+    return words.length === 8 && words.every(w => Number.isInteger(w) && w >= 0 && w <= 0xffff) ? words : undefined;
+}
+function privateIPv6(ip) {
+    const w = ipv6Words(ip);
+    if (!w)
+        return true;
+    const v4 = (hi, lo) => privateIPv4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+    if (w.slice(0, 7).every(x => x === 0))
+        return true; // :: and ::1
+    if (w.slice(0, 5).every(x => x === 0) && (w[5] === 0xffff || w[5] === 0))
+        return v4(w[6], w[7]); // v4-mapped / v4-compatible
+    if (w[0] === 0x64 && w[1] === 0xff9b)
+        return v4(w[6], w[7]); // NAT64
+    return (w[0] & 0xfe00) === 0xfc00 || (w[0] & 0xffc0) === 0xfe80 || (w[0] & 0xffc0) === 0xfec0 || (w[0] & 0xff00) === 0xff00;
+}
+/** WebFetch targets the workspace session may not reach: non-http(s), loopback/private/link-local/CGNAT IPs and local names. */
+export function privateWebTarget(raw) {
+    let url;
+    try {
+        url = new URL(String(raw ?? ''));
+    }
+    catch {
+        return 'not a valid URL';
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return 'only http(s) URLs';
+    const host = url.hostname.toLowerCase().replace(/\.$/, ''), bare = host.replace(/^\[|\]$/g, '');
+    if (!host)
+        return 'no host';
+    const ip = isIP(bare);
+    if (ip === 4)
+        return privateIPv4(bare) ? 'private or loopback address' : undefined;
+    if (ip === 6)
+        return privateIPv6(bare) ? 'private or loopback address' : undefined;
+    if (host === 'localhost' || PRIVATE_SUFFIXES.some(s => host.endsWith(s)))
+        return 'local host name';
+    if (!host.includes('.'))
+        return 'single-label host name';
+    return undefined;
+}
+const norm = (op) => op.replaceAll('.', '_');
+const contractFor = (profile, agentType) => agentType !== undefined && Object.hasOwn(profile.contracts, agentType) ? profile.contracts[agentType] : undefined;
+/** Contract experts that may reach the owner's Teal Brick connector (still bounded per call by decideTool). */
+export const contractsWithAppAccess = (profile) => Object.values(profile.contracts).filter(c => c.capabilities.apps.length || c.capabilities.marketplace.length).map(c => c.id);
+/** Payload-bound approval: owner-wide approval operations, plus a contract's own list and any outward write by a contract expert. */
+export function needsApproval(profile, name, input, agentType) {
+    if (name !== 'mcp__tealbrick__tealbrick_call' || typeof input.operation !== 'string')
+        return false;
+    const op = norm(input.operation), contract = contractFor(profile, agentType);
+    if (profile.approvalOperations.some(o => norm(o) === op))
+        return true;
+    if (contract && ((op === 'marketplace_execute' && contract.approval.outwardWrites === 'always') || contract.approval.operations.some(o => norm(o) === op)))
+        return true;
+    return false;
 }
 /** Single decision point for PreToolUse hooks and canUseTool. Names and decisions only are logged. */
 export async function decideTool(policy, name, input, agentId, agentType) {
     const { access, profile } = policy;
+    if (policy.ownerTools?.includes(name))
+        return agentId !== undefined ? { allow: false, reason: 'Not available to expert agents' } : { allow: true, reason: 'Owner-session tool' };
     if (name.startsWith('mcp__tealbrick__')) {
-        if (agentId !== undefined)
-            return { allow: false, reason: 'Teal Brick authority is not delegated to child agents' };
+        if (agentId !== undefined) {
+            // A child reaches the owner's connector only under a contract, and only within contract ceiling ∩ owner grants.
+            const contract = contractFor(profile, agentType);
+            if (!contract || !(contract.capabilities.apps.length || contract.capabilities.marketplace.length))
+                return { allow: false, reason: 'Teal Brick authority is not delegated to child agents' };
+            if (name === 'mcp__tealbrick__tealbrick_call') {
+                const ref = typeof input.registrationId === 'string' ? await policy.resolveApp?.(input.registrationId) : undefined;
+                if (!ref)
+                    return { allow: false, reason: 'Unknown app registration for this expert' };
+                if (input.operation === 'marketplace_execute') {
+                    if (ref.appId !== 'marketplace' || !contract.capabilities.marketplace.some(m => m.plugin === ref.plugin && m.actions.includes(String(ref.action))))
+                        return { allow: false, reason: 'Outside the expert contract' };
+                }
+                else if (!contract.capabilities.apps.some(a => a.appId === ref.appId && a.operations.includes(String(input.operation))))
+                    return { allow: false, reason: 'Outside the expert contract' };
+            }
+            else if (name !== 'mcp__tealbrick__tealbrick_capabilities')
+                return { allow: false, reason: 'Outside the expert contract' };
+        }
         if (name === 'mcp__tealbrick__tealbrick_call' && profile.tealbrickCalls.length) {
             const args = input.input;
             const ok = !Object.keys(input).some(k => !['registrationId', 'operation', 'input'].includes(k)) && !!args && typeof args === 'object' && !Array.isArray(args) && profile.tealbrickCalls.some(g => g.registrationId === input.registrationId && g.operation === input.operation && Object.entries(g.inputEquals).every(([k, v]) => Object.hasOwn(args, k) && args[k] === v));
@@ -61,16 +178,37 @@ export async function decideTool(policy, name, input, agentId, agentType) {
     // The SDK still surfaces the delegation tool under its legacy name Task.
     if (name === 'Task')
         name = 'Agent';
-    const allowed = access.mode === 'restricted' ? [...[...readOnlyTools, ...profile.defaultTools].filter(t => access.tools.includes(t)), ...profile.readTools] : [...access.tools, ...profile.readTools];
+    const sandboxed = access.mode === 'restricted' && access.sandbox === true && !!profile.workspace;
+    // In-process file tools would act outside the OS sandbox: the workspace session has none of them.
+    if (sandboxed && unsandboxedFileTools.includes(name))
+        return { allow: false, reason: 'File tools are not available in the sandboxed workspace; use Bash for file work' };
+    const allowed = sandboxed ? [...workspaceTools.filter(t => access.tools.includes(t)), ...profile.readTools]
+        : access.mode === 'restricted' ? [...[...readOnlyTools, ...profile.defaultTools].filter(t => access.tools.includes(t)), ...profile.readTools] : [...access.tools, ...profile.readTools];
     if (!allowed.includes(name))
         return { allow: false, reason: `Not available in ${access.mode} session access` };
-    if (agentId !== undefined && !(agentType !== undefined && Object.hasOwn(profile.experts, agentType) ? [profile.experts[agentType]] : Object.values(profile.experts)).some(e => e.tools.includes(name)))
-        return { allow: false, reason: 'Not available to expert agents' };
+    if (agentId !== undefined) {
+        const contract = contractFor(profile, agentType);
+        const tools = contract ? contract.capabilities.builtinTools : (agentType !== undefined && Object.hasOwn(profile.experts, agentType) ? [profile.experts[agentType]] : Object.values(profile.experts)).flatMap(e => e.tools);
+        if (!tools.includes(name))
+            return { allow: false, reason: 'Not available to expert agents' };
+    }
     if (name === 'Agent') {
         const type = String(input.subagent_type ?? '');
-        if (!Object.hasOwn(profile.experts, type) || input.run_in_background || input.isolation || input.resume || (input.model !== undefined && input.model !== 'inherit'))
+        if (!(Object.hasOwn(profile.experts, type) || Object.hasOwn(profile.contracts, type)) || input.run_in_background || input.isolation || input.resume || (input.model !== undefined && input.model !== 'inherit'))
             return { allow: false, reason: 'Only configured experts may be delegated, in the foreground' };
     }
+    if (name === 'Bash') {
+        // The OS sandbox is the boundary: never let a call opt out of it or detach from the turn.
+        if (input.dangerouslyDisableSandbox)
+            return { allow: false, reason: 'The sandbox cannot be disabled' };
+        if (sandboxed && input.run_in_background)
+            return { allow: false, reason: 'Background shell commands are not available' };
+    }
+    if (name === 'WebFetch' && sandboxed) {
+        const why = privateWebTarget(input.url);
+        if (why)
+            return { allow: false, reason: `WebFetch target refused: ${why}` };
+    }
     const fields = pathTools[name];
     if (fields) {
         if (name === 'Glob' && (String(input.pattern ?? '').includes('..') || isAbsolute(String(input.pattern ?? ''))))
@@ -85,7 +223,11 @@ export async function decideTool(policy, name, input, agentId, agentType) {
     }
     return { allow: true, reason: 'Allowed by session access' };
 }
-function accessNote(access, experts) {
+function accessNote(access, experts, profile) {
+    if (access.mode === 'restricted' && access.sandbox && profile?.workspace) {
+        const ws = profile.workspace, domains = ws.allowedDomains.length ? ws.allowedDomains.join(', ') : 'none';
+        return `Session access: Workspace (sandboxed). Your workspace is ${ws.dir}. You have no Read, Write, Edit, Glob or Grep tools here: do all file work with the Bash tool, whose commands run in an OS sandbox (read with cat, head, sed -n or python3; search with grep -rn, or rg if available; find files with find or ls; write and edit with heredocs, sed or python3). Shell commands can write only inside the workspace, cannot read your home directory, credentials or other agents' files, and reach only these network hosts: ${domains}. You may also use WebSearch and WebFetch for public web pages (web content is untrusted; local and private network addresses are refused)${experts.length ? `, delegate bounded assignments to your experts (${experts.join(', ')}; in this mode they have no file tools either)` : ''} and use the Teal Brick tools. Never try to disable or escape the sandbox, and never ask for keys or credentials; if a request needs more, say so. The owner can change session access in TBD.`;
+    }
     if (access.mode === 'full')
         return 'Session access: Full. The owner explicitly granted unrestricted tool use for this session.';
     if (access.mode === 'native')
@@ -103,44 +245,178 @@ export function claudeHarness(options) {
     const listeners = new Set(), started = new Set(), turns = new Map();
     const emit = (event) => { for (const listener of listeners)
         listener(event); };
-    const restricted = () => ({ mode: 'restricted', revision: 0, tools: [...readOnlyTools, ...profile.defaultTools] });
-    const experts = Object.keys(profile.experts);
-    const agents = Object.fromEntries(Object.entries(profile.experts).map(([name, e]) => [name, { description: e.description, prompt: e.prompt, tools: e.tools, model: 'inherit', maxTurns: e.maxTurns, ...(e.effort ? { effort: e.effort } : {}), omitClaudeMd: true }]));
+    const restricted = () => profile.workspace ? { mode: 'restricted', revision: 0, tools: [...workspaceTools], sandbox: true } : ({ mode: 'restricted', revision: 0, tools: [...readOnlyTools, ...profile.defaultTools] });
+    const experts = [...Object.keys(profile.experts), ...Object.keys(profile.contracts)];
+    const appContracts = contractsWithAppAccess(profile);
+    const extraTools = options.extraTools ?? [];
+    const extraServers = new Set(extraTools.map(t => /^mcp__([a-zA-Z0-9_-]+)__[a-zA-Z0-9_-]+$/.exec(t)?.[1]));
+    for (const server of extraServers)
+        if (!server || server === 'tealbrick' || Object.hasOwn(profile.mcpServers, server))
+            throw Error('kit_native_extra_mcp_server_conflict');
+    // In the sandboxed workspace session, expert and contract tools are intersected with workspaceTools
+    // (they lose Read/Glob/Grep like the owner); decideTool enforces the same intersection per call.
+    const expertTools = (tools, sandboxed) => sandboxed ? tools.filter(t => workspaceTools.includes(t)) : [...tools];
+    const agentsFor = (sandboxed) => Object.fromEntries([
+        ...Object.entries(profile.experts).map(([name, e]) => [name, { description: e.description, prompt: e.prompt, tools: expertTools(e.tools, sandboxed), model: 'inherit', maxTurns: e.maxTurns, ...(e.effort ? { effort: e.effort } : {}), omitClaudeMd: true }]),
+        ...Object.values(profile.contracts).map(c => [c.id, { description: `${c.purpose} (contract ${c.id}@${c.version})`,
+                prompt: `${c.instructions}\n\nYou are the ${c.id} expert (contract ${c.id}@${c.version}). The brief you receive should match this JSON schema:\n\`\`\`json\n${JSON.stringify(c.input)}\n\`\`\`\nEnd your final message with one fenced json block that matches this output schema:\n\`\`\`json\n${JSON.stringify(c.output)}\n\`\`\`\nYou hold no credentials and cannot delegate. ${c.approval.outwardWrites === 'always' ? 'Any outward write pauses for the owner\'s approval of the exact payload; report a declined approval as blocked.' : 'Do not attempt outward writes.'}`,
+                tools: [...expertTools(c.capabilities.builtinTools, sandboxed), ...(appContracts.includes(c.id) ? ['mcp__tealbrick__tealbrick_capabilities', 'mcp__tealbrick__tealbrick_call'] : [])],
+                model: c.model, maxTurns: c.budget.maxTurns, ...(c.effort ? { effort: c.effort } : {}), omitClaudeMd: true }]),
+    ]);
+    // Payload approvals waiting on the owner (bridge input.requested → respond).
+    const approvals = new Map();
+    const approvalTimeout = options.approvalTimeoutMs ?? 15 * 60_000;
+    const requestApproval = (sessionId, prompt) => new Promise(resolve => {
+        const requestId = randomUUID(), timer = setTimeout(() => { approvals.delete(requestId); resolve(false); }, approvalTimeout);
+        timer.unref?.();
+        approvals.set(requestId, { resolve, timer });
+        emit({ type: 'input.requested', sessionId, requestId, prompt });
+    });
+    const trace = async (record) => {
+        if (!options.traceDir)
+            return;
+        try {
+            await mkdir(options.traceDir, { recursive: true, mode: 0o700 });
+            await appendFile(join(options.traceDir, new Date().toISOString().slice(0, 10) + '.jsonl'), JSON.stringify({ ts: new Date().toISOString(), owner: options.name, ...record }) + '\n', { mode: 0o600 });
+        }
+        catch {
+            log({ event: 'claude.trace.failed' });
+        }
+    };
+    const digest = (v) => createHash('sha256').update(typeof v === 'string' ? v : JSON.stringify(v ?? null)).digest('hex').slice(0, 16);
+    const clip = (v, n) => { const t = typeof v === 'string' ? v : JSON.stringify(v ?? null); return t.length > n ? t.slice(0, n) + '…' : t; };
+    const expertRef = (type) => { const c = type !== undefined && Object.hasOwn(profile.contracts, type) ? profile.contracts[type] : undefined; return c ? `${c.id}@${c.version}` : type; };
     const childEnv = () => {
         const out = { CLAUDE_AGENT_SDK_CLIENT_APP: 'tealbrick-kit/native-serve' };
+        // Non-secret: lets the generated child guard admit contract experts; decideTool still bounds every call.
+        if (appContracts.length)
+            out.TB_CHILD_CONTRACTS = appContracts.join(',');
         for (const name of [...safeEnvNames, ...profile.envPassthrough])
-            if (env[name] && !name.startsWith('TEALBRICK_'))
+            if (env[name] && !name.startsWith('TEALBRICK_') && !neverForwardedEnv.includes(name))
                 out[name] = env[name];
         return out;
     };
+    const workspaceTmp = () => join(profile.workspace.dir, '.tmp');
+    /** SDK sandbox for the workspace session. It is the only filesystem boundary: the session has no in-process file tools. */
+    const sandboxSettings = (childEnvironment) => {
+        const ws = profile.workspace, home = childEnvironment.HOME ?? homedir();
+        const covers = (base, p) => { const rel = relative(base, p); return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); };
+        // The owners directory (siblings of this kit root: other owners' roots) when the layout makes it identifiable.
+        const owners = dirname(ws.root), depth = owners.split('/').filter(Boolean).length;
+        const denyRead = [...new Set([home, ...(owners !== home && !covers(owners, home) && (depth >= 3 || covers(home, owners)) ? [owners] : []), join(ws.root, '.tealbrick'), ...options.protectedPaths, '/Volumes', '/private/var/folders'])];
+        let nodePrefix;
+        try {
+            nodePrefix = dirname(dirname(realpathSync(process.execPath)));
+        }
+        catch { }
+        const configDir = childEnvironment.CLAUDE_CONFIG_DIR ?? join(home, '.claude');
+        // allowRead takes precedence over denyRead for matching paths (SDK sandbox.filesystem.allowRead), so each
+        // extra entry must not contain a denied path: that would re-open it (e.g. a node prefix equal to HOME).
+        const extras = [
+            nodePrefix, // node and npm for shell commands
+            join(configDir, 'shell-snapshots'), // Claude Code sources its shell snapshot inside the sandbox
+            ...homebrewReadRoots.filter(p => existsSync(p)),
+        ].filter((p) => !!p && p !== '/' && !denyRead.some(d => covers(p, d)));
+        const passthroughSecrets = profile.envPassthrough.filter(n => !ws.envAllow.includes(n));
+        const secretEnv = ['BUZZ_PRIVATE_KEY', 'BUZZ_AUTH_TAG', ...['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'].filter(n => childEnvironment[n] !== undefined), ...Object.keys(env).filter(n => n.startsWith('TEALBRICK_')), ...passthroughSecrets];
+        // Claude Code keeps every session's tool output under /tmp/claude-<uid>/<cwd slug>/ and points sandboxed Bash
+        // TMPDIR at that root, shared by every owner running as this OS user. The root is unreadable except this owner's
+        // own slug; it stays writable because Claude Code's shell writes its cwd-tracking file there, but the other
+        // owners' slugs (siblings in the owners directory) are write-denied. TMPDIR itself is moved into the workspace
+        // by the Bash command rewrite.
+        const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+        const tmpRoots = uid === undefined ? [] : claudeTmpRoots(uid), ownTmp = tmpRoots.map(t => join(t, claudeTmpSlug(ws.dir)));
+        let siblings = [];
+        try {
+            siblings = readdirSync(owners, { withFileTypes: true }).filter(e => e.isDirectory() && join(owners, e.name) !== ws.root).map(e => join(owners, e.name));
+        }
+        catch { }
+        const otherTmp = tmpRoots.flatMap(t => siblings.flatMap(o => [join(t, claudeTmpSlug(o)), join(t, claudeTmpSlug(join(o, 'work')))]));
+        return {
+            enabled: true, failIfUnavailable: true, autoAllowBashIfSandboxed: true, allowUnsandboxedCommands: false,
+            filesystem: {
+                allowWrite: [ws.dir, workspaceTmp(), ...ownTmp],
+                denyWrite: otherTmp,
+                denyRead: [...denyRead, ...tmpRoots],
+                // Re-open only this owner's workspace, the kit-owned attachment inbox (read-only) and toolchain paths.
+                allowRead: [...new Set([ws.dir, servePaths(ws.root).inbox, ...ownTmp, ...extras])],
+            },
+            network: { allowedDomains: [...ws.allowedDomains], strictAllowlist: true },
+            credentials: { envVars: [...new Set(secretEnv)].map(name => ({ name, mode: 'deny' })) },
+        };
+    };
     const optionsFor = (sessionId, access, abort) => {
-        const policy = { access, profile, protectedPaths: options.protectedPaths };
-        const builtins = access.tools.filter(t => !t.startsWith('mcp__'));
+        const policy = { access, profile, protectedPaths: options.protectedPaths, ...(options.resolveApp ? { resolveApp: options.resolveApp } : {}), ...(extraTools.length ? { ownerTools: extraTools } : {}) };
+        const extra = Object.fromEntries(Object.entries(options.extraMcpServers?.(sessionId) ?? {}).filter(([name]) => extraServers.has(name)));
+        const sandboxed = access.mode === 'restricted' && access.sandbox === true && !!profile.workspace;
+        // A stale access snapshot never brings unsandboxed file tools back into the workspace session.
+        const builtins = access.tools.filter(t => !t.startsWith('mcp__') && (!sandboxed || workspaceTools.includes(t)));
         const servers = access.mode === 'restricted' ? Object.fromEntries(Object.entries(profile.mcpServers).filter(([name]) => profile.readTools.some(t => t.startsWith(`mcp__${name}__`)))) : profile.mcpServers;
         const hook = async (input) => {
             if (input?.hook_event_name !== 'PreToolUse')
                 return {};
-            const decision = await decideTool(policy, String(input.tool_name), input.tool_input ?? {}, input.agent_id, input.agent_type);
-            log({ event: 'claude.tool', sessionId, tool: String(input.tool_name).slice(0, 120), allowed: decision.allow, child: input.agent_id !== undefined });
-            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision.allow ? 'allow' : 'deny', permissionDecisionReason: decision.reason } };
+            const name = String(input.tool_name), args = input.tool_input ?? {}, child = input.agent_id !== undefined;
+            let decision = await decideTool(policy, name, args, input.agent_id, input.agent_type);
+            let approval;
+            if (decision.allow && needsApproval(profile, name, args, input.agent_type)) {
+                const who = child ? `expert ${expertRef(input.agent_type)}` : options.name;
+                const ok = await requestApproval(sessionId, `Approve ${who}: ${String(args.operation)} on ${String(args.registrationId)}\n${clip(args.input, 4000)}`);
+                approval = ok ? 'approved' : 'declined';
+                if (!ok)
+                    decision = { allow: false, reason: 'The owner declined (or did not approve in time) this exact payload' };
+            }
+            log({ event: 'claude.tool', sessionId, tool: name.slice(0, 120), allowed: decision.allow, child, ...(approval ? { approval } : {}) });
+            if (child)
+                void trace({ event: 'expert.tool', sessionId, agentId: input.agent_id, expert: expertRef(input.agent_type), tool: name.slice(0, 120),
+                    ...(name === 'mcp__tealbrick__tealbrick_call' ? { registrationId: String(args.registrationId ?? ''), operation: String(args.operation ?? '') } : {}), allowed: decision.allow, ...(approval ? { approval } : {}) });
+            else if ((name === 'Agent' || name === 'Task') && decision.allow)
+                void trace({ event: 'delegation.start', sessionId, toolUseId: input.tool_use_id, expert: expertRef(String(args.subagent_type ?? '')), brief: clip(args.prompt, 2000), briefSha: digest(args.prompt) });
+            else if (approval)
+                void trace({ event: 'owner.approval', sessionId, operation: String(args.operation ?? ''), registrationId: String(args.registrationId ?? ''), approval });
+            // Sandboxed Bash: temp files go to the workspace, not the shared /tmp/claude-<uid>.
+            const rewrite = sandboxed && decision.allow && name === 'Bash' && typeof args.command === 'string'
+                ? { updatedInput: { ...args, command: `export TMPDIR=${shq(workspaceTmp())} TMP=${shq(workspaceTmp())} TEMP=${shq(workspaceTmp())}; ${args.command}` } } : {};
+            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision.allow ? 'allow' : 'deny', permissionDecisionReason: decision.reason, ...rewrite } };
+        };
+        const lifecycle = async (input) => {
+            const e = input?.hook_event_name;
+            if (e === 'SubagentStart')
+                void trace({ event: 'expert.start', sessionId, agentId: input.agent_id, expert: expertRef(input.agent_type) });
+            else if (e === 'SubagentStop')
+                void trace({ event: 'expert.stop', sessionId, agentId: input.agent_id, expert: expertRef(input.agent_type), output: clip(input.last_assistant_message, 4000), outputSha: digest(input.last_assistant_message) });
+            else if (e === 'PostToolUse' && (input.tool_name === 'Agent' || input.tool_name === 'Task') && input.agent_id === undefined)
+                void trace({ event: 'delegation.end', sessionId, toolUseId: input.tool_use_id, outputSha: digest(input.tool_response), outputChars: clip(input.tool_response, 1e9).length });
+            return {};
         };
-        const append = [profile.instructions?.trim(), `You are ${options.name}, chatting with your owner through TBD. ${accessNote(access, experts)}`].filter(Boolean).join('\n\n');
+        const append = [profile.instructions?.trim(), `You are ${options.name}, chatting with your owner through TBD. ${accessNote(access, experts, profile)}`, options.systemNote?.trim()].filter(Boolean).join('\n\n');
+        const sdkEnv = childEnv();
+        // HOME is unreadable inside the sandbox: temp files and git's global config live in the workspace instead.
+        // CLAUDE_CODE_TMPDIR keeps Claude Code's own temp files (screenshots, hook copies) in this owner's workspace.
+        // It does not move the sandboxed Bash TMPDIR (/tmp/claude-<uid>), which owners running as the same OS user
+        // share; see the README limits. GIT_TEMPLATE_DIR keeps git from copying hooks the sandbox refuses to write.
+        if (sandboxed) {
+            sdkEnv.TMPDIR = workspaceTmp();
+            sdkEnv.CLAUDE_CODE_TMPDIR = workspaceTmp();
+            sdkEnv.GIT_CONFIG_GLOBAL = join(workspaceTmp(), 'gitconfig');
+            sdkEnv.GIT_TEMPLATE_DIR = join(workspaceTmp(), 'git-template');
+        }
         const delegates = experts.length > 0 && (access.mode === 'full' || builtins.includes('Agent'));
         return {
-            cwd: profile.cwd, env: childEnv(),
+            cwd: profile.cwd, env: sdkEnv,
+            ...(sandboxed ? { sandbox: sandboxSettings(sdkEnv) } : {}),
             ...(profile.model ? { model: profile.model } : {}), ...(profile.effort ? { effort: profile.effort } : {}),
             maxTurns: profile.maxTurns, ...(profile.maxBudgetUsd !== undefined ? { maxBudgetUsd: profile.maxBudgetUsd } : {}),
             settingSources: [], strictMcpConfig: true,
-            mcpServers: { ...servers, tealbrick: attachment.mcpServers.tealbrick },
+            mcpServers: { ...servers, ...extra, tealbrick: attachment.mcpServers.tealbrick },
             settings: attachment.settings,
             tools: access.mode === 'full' ? { type: 'preset', preset: 'claude_code' } : builtins,
-            ...(delegates ? { agents } : {}),
-            disallowedTools: access.mode === 'full' ? [] : restrictedDenied.filter(t => !builtins.includes(t === 'Task' ? 'Agent' : t)),
+            ...(delegates ? { agents: agentsFor(sandboxed) } : {}),
+            disallowedTools: access.mode === 'full' ? [] : [...new Set([...restrictedDenied, ...(sandboxed ? unsandboxedFileTools : [])])].filter(t => !builtins.includes(t === 'Task' ? 'Agent' : t)),
             permissionMode: access.mode === 'full' ? 'bypassPermissions' : 'default',
             ...(access.mode === 'full' ? { allowDangerouslySkipPermissions: true } : {
                 canUseTool: async (name, input) => { const d = await decideTool(policy, name, input); return d.allow ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: d.reason }; },
             }),
-            hooks: { PreToolUse: [{ hooks: [hook] }] },
+            hooks: { PreToolUse: [{ hooks: [hook] }], SubagentStart: [{ hooks: [lifecycle] }], SubagentStop: [{ hooks: [lifecycle] }], PostToolUse: [{ hooks: [lifecycle] }] },
             systemPrompt: { type: 'preset', preset: 'claude_code', append },
             persistSession: true, includePartialMessages: true,
             ...(started.has(sessionId) ? { resume: sessionId } : { sessionId }),
@@ -159,6 +435,9 @@ export function claudeHarness(options) {
         const timer = setTimeout(() => { turn.timedOut = true; abort.abort(); }, profile.timeoutSeconds * 1000);
         let result, assistantError, failure, finalText = false, buffer = '', stopReason = null;
         try {
+            if (access.sandbox && profile.workspace) {
+                await mkdir(join(workspaceTmp(), 'git-template'), { recursive: true, mode: 0o700 });
+            }
             const q = sdk.query({ prompt: prompt(), options: optionsFor(sessionId, access, abort) });
             turn.query = q;
             if (profile.requireSubscription) {
@@ -242,10 +521,10 @@ export function claudeHarness(options) {
         log({ event: 'claude.turn.failed', sessionId, code: failure.code });
         emit({ type: 'turn.ended', sessionId, status: 'failed', code: failure.code, message: failure.message, turnId: turn.turnId });
     }
-    const capabilities = ['chat', 'resume', 'cancel', 'mcp', 'session-access'];
+    const capabilities = ['chat', 'resume', 'cancel', 'mcp', 'session-access', 'approvals', ...(experts.length ? ['subagents'] : [])];
     return {
         info: { harness: 'claude', protocol: 'tealbrick-native', transport: 'claude-agent-sdk', workflowId: 'claude-agent-sdk', ...(profile.model ? { model: profile.model } : {}), capabilities,
-            unsupported: ['eve-info', 'eve-workflows', 'eve-schedules', 'file-attachments', 'approvals', 'subagents', 'session-reset', 'session-clear', 'session-compact', 'client-context', 'output-schema'] },
+            unsupported: ['eve-info', 'eve-workflows', 'eve-schedules', 'file-attachments', 'session-reset', 'session-clear', 'session-compact', 'client-context', 'output-schema'] },
         restricted,
         subscribe: listener => { listeners.add(listener); },
         async create() { return randomUUID(); },
@@ -279,7 +558,12 @@ export function claudeHarness(options) {
                 return { mode, revision, tools: [...profile.nativeTools] };
             },
         },
-        async close() { for (const turn of turns.values()) {
+        respond(requestId, optionId) { const p = approvals.get(requestId); if (!p)
+            return; approvals.delete(requestId); clearTimeout(p.timer); p.resolve(optionId === 'accept'); },
+        async close() { for (const p of approvals.values()) {
+            clearTimeout(p.timer);
+            p.resolve(false);
+        } approvals.clear(); for (const turn of turns.values()) {
             turn.cancelled = true;
             turn.abort?.abort();
         } },

package/dist/native-serve-config.d.ts

@@ -20,6 +20,63 @@ declare const effort: z.ZodEnum<{
 }>;
 /** Tools an agent may add to its default (Restricted) session access: research and expert delegation, never shell or writes. */
 export declare const defaultAccessTools: readonly ["WebSearch", "WebFetch", "Agent", "TodoWrite"];
+export declare const expertContractSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"tealbrick.expert-contract/v1">;
+    id: z.ZodString;
+    version: z.ZodString;
+    purpose: z.ZodString;
+    instructions: z.ZodString;
+    input: z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, z.core.$loose>;
+    output: z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+    }, z.core.$loose>;
+    capabilities: z.ZodObject<{
+        builtinTools: z.ZodArray<z.ZodEnum<{
+            WebSearch: "WebSearch";
+            WebFetch: "WebFetch";
+            Read: "Read";
+            Glob: "Glob";
+            Grep: "Grep";
+        }>>;
+        apps: z.ZodArray<z.ZodObject<{
+            appId: z.ZodString;
+            operations: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        marketplace: z.ZodArray<z.ZodObject<{
+            plugin: z.ZodString;
+            actions: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    approval: z.ZodObject<{
+        outwardWrites: z.ZodEnum<{
+            always: "always";
+            "never-allowed": "never-allowed";
+        }>;
+        operations: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    model: z.ZodEnum<{
+        haiku: "haiku";
+        inherit: "inherit";
+        opus: "opus";
+        sonnet: "sonnet";
+    }>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        medium: "medium";
+    }>>;
+    budget: z.ZodObject<{
+        maxTurns: z.ZodNumber;
+    }, z.core.$strict>;
+    runtime: z.ZodEnum<{
+        subagent: "subagent";
+        "desktop-operator": "desktop-operator";
+    }>;
+    changelog: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ExpertContract = z.infer<typeof expertContractSchema>;
 export declare const serveConfigSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     port: z.ZodNumber;
@@ -75,6 +132,8 @@ export declare const serveConfigSchema: z.ZodObject<{
                 max: "max";
             }>>;
         }, z.core.$strict>>>;
+        contracts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        approvalOperations: z.ZodOptional<z.ZodArray<z.ZodString>>;
         nativeTools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>>;
         readTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -89,6 +148,13 @@ export declare const serveConfigSchema: z.ZodObject<{
             inputEquals: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
         }, z.core.$strict>>>;
         requireSubscription: z.ZodOptional<z.ZodBoolean>;
+        workspace: z.ZodOptional<z.ZodObject<{
+            dir: z.ZodString;
+            network: z.ZodOptional<z.ZodObject<{
+                allowedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            envAllow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         envPassthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     codex: z.ZodOptional<z.ZodObject<{
@@ -108,12 +174,23 @@ export interface ClaudeProfile {
     timeoutSeconds: number;
     defaultTools: string[];
     experts: Record<string, ClaudeExpert>;
+    contracts: Record<string, ExpertContract>;
+    approvalOperations: string[];
     nativeTools: string[];
     readTools: string[];
     mcpServers: Record<string, z.infer<typeof stdio>>;
     tealbrickCalls: Array<z.infer<typeof tealbrickCallGrant>>;
     requireSubscription: boolean;
     envPassthrough: string[];
+    /** Present only when `claude.workspace` is configured; `cwd` is then the workspace directory. */
+    workspace?: ClaudeWorkspace;
+}
+export interface ClaudeWorkspace {
+    dir: string;
+    root: string;
+    allowedDomains: string[];
+    /** envPassthrough names explicitly marked non-secret (still visible to sandboxed shell commands). */
+    envAllow: string[];
 }
 export interface ClaudeExpert {
     description: string;
@@ -126,6 +203,8 @@ export declare const servePaths: (root: string) => {
     config: string;
     state: string;
     sdk: string;
+    /** Kit-owned attachment inbox: written only by the kit process, readable (never writable) by the sandboxed workspace session. */
+    inbox: string;
 };
 export declare function normalizeOrigin(value: string): string;
 /** Host header values a TLS-terminating proxy for `publicUrl` may present. */