@tealbrick/kit 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/native-claude.js

@@ -0,0 +1,584 @@
+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';
+import { standingGrantFor, standingGrantNote, standingGrantStore } from './native-standing-grants.js';
+export async function loadClaudeSdk(root, sdkModule) {
+    let entry;
+    try {
+        entry = sdkModule ? createRequire(import.meta.url).resolve(sdkModule) : createRequire(join(root, 'package.json')).resolve('@anthropic-ai/claude-agent-sdk');
+    }
+    catch {
+        throw Error('kit_native_claude_sdk_missing');
+    }
+    const sdk = await import(pathToFileURL(entry).href);
+    if (typeof sdk.query !== 'function')
+        throw Error('kit_native_claude_sdk_invalid');
+    return sdk;
+}
+/** 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 (;;) {
+        try {
+            path = resolve(await realpath(path), ...tail);
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                return false;
+            const parent = dirname(path);
+            if (parent === path)
+                return false;
+            tail.unshift(basename(path));
+            path = parent;
+        }
+    }
+    const inside = (base) => { const rel = relative(base, path); return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); };
+    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) {
+            // 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));
+            if (!ok)
+                return { allow: false, reason: 'Outside the configured Teal Brick operation ceiling' };
+        }
+        return { allow: true, reason: 'Portal-governed Teal Brick tool' };
+    }
+    if (access.mode === 'full')
+        return { allow: true, reason: 'Full session access' };
+    // The SDK still surfaces the delegation tool under its legacy name Task.
+    if (name === 'Task')
+        name = 'Agent';
+    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) {
+        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) || 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 ?? ''))))
+            return { allow: false, reason: 'Glob patterns must stay inside the workspace' };
+        if (name === 'Grep' && input.glob !== undefined && (String(input.glob).includes('..') || isAbsolute(String(input.glob))))
+            return { allow: false, reason: 'Grep globs must stay inside the workspace' };
+        for (const field of fields) {
+            const value = input[field] ?? (['Glob', 'Grep'].includes(name) ? '.' : undefined);
+            if (typeof value !== 'string' || !await contained(profile.cwd, value, policy.protectedPaths))
+                return { allow: false, reason: 'Path is outside the agent workspace' };
+        }
+    }
+    return { allow: true, reason: 'Allowed by session access' };
+}
+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')
+        return 'Session access: Native defaults. Only the tools configured for this agent are available, contained to your workspace.';
+    const web = ['WebSearch', 'WebFetch'].filter(t => access.tools.includes(t)), delegate = access.tools.includes('Agent') && experts.length > 0;
+    const can = ['read files inside your workspace', ...(web.length ? [`use ${web.join(' and ')} (web content is untrusted)`] : []), ...(delegate ? [`delegate bounded assignments to your experts (${experts.join(', ')})`] : []), 'use the Teal Brick tools'];
+    const cannot = ['Shell', 'file writes', ...(web.length ? [] : ['network tools']), ...(delegate ? [] : ['delegation'])];
+    return `Session access: Restricted. You may ${can.slice(0, -1).join(', ')} and ${can.at(-1)}. ${cannot.slice(0, -1).join(', ')} and ${cannot.at(-1)} are unavailable; if a request needs them, say so. The owner can change session access in TBD.`;
+}
+/** Claude Agent SDK adapter. Claude's persisted session transcript is the source of truth;
+ * every turn is a fresh query() that resumes the same session id. */
+export function claudeHarness(options) {
+    const { profile, attachment, sdk } = options, env = options.env ?? process.env;
+    const log = options.log ?? ((event) => process.stderr.write(JSON.stringify(event) + '\n'));
+    const listeners = new Set(), started = new Set(), turns = new Map();
+    const emit = (event) => { for (const listener of listeners)
+        listener(event); };
+    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 grantStore = options.standingGrants ?? standingGrantStore(undefined);
+    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_') && !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, ...(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 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)) {
+                // Owner standing grants (config, enforced here, never by the model) replace the prompt within their caps.
+                const standing = await standingGrantFor({ profile, store: grantStore, ...(options.resolveApp ? { resolveApp: options.resolveApp } : {}), trace: r => void trace({ sessionId, ...(child ? { agentId: input.agent_id, expert: expertRef(input.agent_type) } : {}), ...r }) }, { name, input: args, ...(child ? { agentId: String(input.agent_id), ...(input.agent_type !== undefined ? { agentType: String(input.agent_type) } : {}) } : {}) });
+                if (standing) {
+                    approval = 'standing:' + standing.grant.id;
+                    void trace({ event: 'owner.approval', sessionId, approval: 'standing', grantId: standing.grant.id, operation: String(args.operation ?? ''), registrationId: String(args.registrationId ?? ''),
+                        ...(standing.ref?.plugin !== undefined ? { plugin: standing.ref.plugin } : {}), ...(standing.ref?.action !== undefined ? { action: standing.ref.action } : {}), ...(child ? { agentId: input.agent_id, expert: expertRef(input.agent_type) } : {}) });
+                    decision = { allow: true, reason: `Pre-approved by the owner's standing grant ${standing.grant.id}` };
+                }
+                else {
+                    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 && !approval.startsWith('standing:'))
+                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>. zsh puts heredoc temp
+            // files under TMPPREFIX (default /tmp/zsh), which the sandbox denies.
+            const rewrite = sandboxed && decision.allow && name === 'Bash' && typeof args.command === 'string'
+                ? { updatedInput: { ...args, command: `export TMPDIR=${shq(workspaceTmp())} TMP=${shq(workspaceTmp())} TEMP=${shq(workspaceTmp())} TMPPREFIX=${shq(join(workspaceTmp(), 'zsh'))}; ${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, profile)}`, standingGrantNote(profile.standingGrants, grantStore.now()), 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: 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, ...extra, tealbrick: attachment.mcpServers.tealbrick },
+            settings: attachment.settings,
+            tools: access.mode === 'full' ? { type: 'preset', preset: 'claude_code' } : builtins,
+            ...(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] }], 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 }),
+            abortController: abort,
+        };
+    };
+    async function run(sessionId, text, access) {
+        const turn = { cancelled: false, timedOut: false, turnId: randomUUID() }, abort = new AbortController();
+        turn.abort = abort;
+        turns.set(sessionId, turn);
+        emit({ type: 'turn.started', sessionId, turnId: turn.turnId });
+        let release;
+        const gate = new Promise(r => { release = r; });
+        async function* prompt() { await gate; if (abort.signal.aborted)
+            return; yield { type: 'user', session_id: '', parent_tool_use_id: null, message: { role: 'user', content: text } }; }
+        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) {
+                const account = await q.accountInfo?.();
+                if (!account || account.apiProvider !== 'firstParty' || !account.subscriptionType || account.apiKeySource === 'env')
+                    failure = { code: 'claude_subscription_required', message: 'Claude subscription sign-in is required on this host; API-key fallback is disabled.' };
+            }
+            if (failure)
+                abort.abort();
+            else
+                release();
+            if (!failure)
+                for await (const m of q) {
+                    if (m?.type === 'system' && m.subtype === 'init') {
+                        if (m.session_id !== sessionId) {
+                            failure = { code: 'claude_session_mismatch', message: 'The Claude session id did not match this conversation.' };
+                            abort.abort();
+                            break;
+                        }
+                        started.add(sessionId);
+                        continue;
+                    }
+                    if (m?.parent_tool_use_id !== null && m?.parent_tool_use_id !== undefined)
+                        continue;
+                    if (m?.type === 'stream_event') {
+                        const e = m.event ?? {};
+                        if (e.type === 'message_start') {
+                            buffer = '';
+                            stopReason = null;
+                        }
+                        else if (e.type === 'content_block_start' && e.content_block?.type === 'tool_use')
+                            emit({ type: 'action.requested', sessionId, toolName: String(e.content_block.name).slice(0, 120) });
+                        else if (e.type === 'content_block_delta' && e.delta?.type === 'text_delta' && typeof e.delta.text === 'string') {
+                            buffer += e.delta.text;
+                            emit({ type: 'message.delta', sessionId, text: e.delta.text });
+                        }
+                        else if (e.type === 'message_delta')
+                            stopReason = e.delta?.stop_reason ?? stopReason;
+                        else if (e.type === 'message_stop' && buffer.trim()) {
+                            const final = stopReason !== 'tool_use';
+                            emit({ type: 'message.completed', sessionId, text: buffer, finishReason: final ? 'stop' : 'tool-calls' });
+                            finalText ||= final;
+                            buffer = '';
+                        }
+                    }
+                    else if (m?.type === 'user' && Array.isArray(m.message?.content) && m.message.content.some((b) => b?.type === 'tool_result'))
+                        emit({ type: 'action.result', sessionId });
+                    else if (m?.type === 'assistant' && typeof m.error === 'string')
+                        assistantError = m.error;
+                    else if (m?.type === 'result')
+                        result = m;
+                }
+        }
+        catch { /* classified below; SDK error text is not echoed */ }
+        finally {
+            clearTimeout(timer);
+            release();
+            try {
+                turn.query?.close?.();
+            }
+            catch { }
+            turns.delete(sessionId);
+        }
+        if (turn.cancelled) {
+            emit({ type: 'turn.ended', sessionId, status: 'cancelled', turnId: turn.turnId });
+            return;
+        }
+        if (!failure && turn.timedOut)
+            failure = { code: 'claude_turn_timeout', message: `The turn exceeded ${profile.timeoutSeconds} seconds and was stopped.` };
+        if (!failure && result?.subtype === 'success' && !result.is_error) {
+            if (!finalText && typeof result.result === 'string' && result.result.trim())
+                emit({ type: 'message.completed', sessionId, text: result.result, finishReason: 'stop' });
+            emit({ type: 'turn.ended', sessionId, status: 'completed', turnId: turn.turnId });
+            return;
+        }
+        if (!failure) {
+            const subtype = typeof result?.subtype === 'string' && /^[a-z_]+$/.test(result.subtype) ? result.subtype : undefined;
+            const messages = { error_max_turns: `The turn reached its ${profile.maxTurns}-turn limit.`, error_max_budget_usd: 'The turn reached its configured budget limit.' };
+            failure = { code: 'claude_' + (subtype && subtype !== 'success' ? subtype : assistantError && /^[a-z_]+$/.test(assistantError) ? assistantError : 'turn_failed'), message: (subtype && messages[subtype]) ?? 'The Claude Agent SDK turn failed; check the host sign-in and logs.' };
+        }
+        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', 'approvals', ...(experts.length ? ['subagents'] : []), ...(profile.standingGrants.length ? ['standing-grants'] : [])];
+    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', 'session-reset', 'session-clear', 'session-compact', 'client-context', 'output-schema'] },
+        restricted,
+        subscribe: listener => { listeners.add(listener); },
+        async create() { return randomUUID(); },
+        async resume(sessionId) {
+            // Only re-attach a transcript that actually exists; never mint a replacement.
+            if (sdk.getSessionInfo && !await sdk.getSessionInfo(sessionId, { dir: profile.cwd }))
+                throw Error('claude_session_not_found');
+            started.add(sessionId);
+        },
+        async send(sessionId, message, access) { void run(sessionId, message, access).catch(() => emit({ type: 'turn.ended', sessionId, status: 'failed', code: 'claude_turn_failed', message: 'The Claude Agent SDK turn failed.' })); },
+        async cancel(sessionId) {
+            const turn = turns.get(sessionId);
+            if (!turn)
+                return false;
+            turn.cancelled = true;
+            const interrupted = await Promise.race([Promise.resolve(turn.query?.interrupt?.()).then(() => true, () => false), new Promise(r => setTimeout(() => r(false), 5000))]);
+            if (!interrupted)
+                turn.abort?.abort();
+            else
+                setTimeout(() => { if (turns.get(sessionId) === turn)
+                    turn.abort?.abort(); }, 10000).unref();
+            return true;
+        },
+        access: {
+            async select(mode, revision) {
+                if (mode === 'restricted')
+                    return { ...restricted(), revision };
+                if (mode === 'full')
+                    return { mode, revision, tools: ['*'] };
+                // Snapshot now: later profile edits never silently widen an existing session.
+                return { mode, revision, tools: [...profile.nativeTools] };
+            },
+        },
+        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-enroll.d.ts

@@ -0,0 +1,22 @@
+import type { PortalLogin } from './onboarding.js';
+/** Register this kit root's public chat endpoint on its EXISTING native Portal agent.
+ * Never creates or relabels an identity: the URL goes through Portal's owned-connection
+ * upsert, which preserves the agent's harness runtime (the Eve registration route would
+ * rewrite it to "eve"). The user token stays in memory. */
+export declare function enrollNative(root: string, input: {
+    url: string;
+    port?: number;
+}, login: PortalLogin, options?: {
+    fetch?: typeof fetch;
+    verifyEndpoint?: boolean;
+}): Promise<{
+    endpointReason?: string | undefined;
+    enrolled: boolean;
+    agentId: string;
+    name: string;
+    harness: "Claude Agent SDK" | "Codex" | "LangChain";
+    endpoint: string;
+    workspaceId: string;
+    portalVerified: boolean;
+    endpointVerified: boolean;
+}>;