@tealbrick/kit 0.3.0-rc.5 → 0.3.0-rc.7

package/BOOTSTRAP.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.5 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.7 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # Deployment guide: Eve agent + Teal Brick kit
 
@@ -19,7 +19,7 @@ For a fresh machine, the sequence is:
 
 1. Install Node 24 and npm.
 2. Create an Eve 0.70.0 project and configure its primary model credentials.
-3. Install `@tealbrick/kit@0.3.0-rc.5` inside that project.
+3. Install `@tealbrick/kit@0.3.0-rc.7` inside that project.
 4. Run `tealbrick setup` to sign in, select capabilities and register the card.
 5. Build and start Eve, then check a real chat from desktop.
 
@@ -81,7 +81,7 @@ Run this inside the Eve project created in step 2 (or your existing compatible
 project), not in an empty directory or as a global install:
 
 ```bash
-npm install --save-exact @tealbrick/kit@0.3.0-rc.5
+npm install --save-exact @tealbrick/kit@0.3.0-rc.7
 ```
 
 This installs Portal, AVM, Voice, Vision, Deliver and the shared provider transport

package/NATIVE.md

@@ -1,10 +1,10 @@
 # Native agent setup — Stage A candidate
 
-Prerelease suite **0.3.0-rc.5** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow; the unscoped `tealbrick` facade keeps `latest` at 0.3.0-rc.1. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed. RC4 added `tealbrick native serve` and `native enroll` (see README.md). RC5 keeps an idle serve process's runtime acknowledged in Portal, and lets the runtime reach Portal-provisioned Knowledge with short-lived Portal grants when no local app binding exists.
+Prerelease suite **0.3.0-rc.7** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow; the unscoped `tealbrick` facade keeps `latest` at 0.3.0-rc.1. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed. RC4 added `tealbrick native serve` and `native enroll` (see README.md). RC5 keeps an idle serve process's runtime acknowledged in Portal, and lets the runtime reach Portal-provisioned Knowledge with short-lived Portal grants when no local app binding exists. RC6 adds the owner-only `/tealbrick/v1/capabilities` snapshot (Portal-granted apps and Marketplace consents) used by TBD Chat → Plugins, and `tealbrick native` without a subcommand prints usage. RC7 loads versioned expert contracts (`claude.contracts`) as SDK subagents with scope = contract ceiling ∩ owner grants, pauses approval operations for the owner's payload approval in TBD, and traces every delegation.
 
 ## Install and connect
 
-Install with `npm install --save-exact tealbrick@0.3.0-rc.5` (or `tealbrick@next`) once registry publication is verified. Until then, use the review tarballs with the checksum-verifying `install-candidate.mjs`.
+Install with `npm install --save-exact tealbrick@0.3.0-rc.7` (or `tealbrick@next`) once registry publication is verified. Until then, use the review tarballs with the checksum-verifying `install-candidate.mjs`.
 
 From your native agent workspace:
 

package/README.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.5 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.7 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # @tealbrick/kit
 
@@ -9,7 +9,7 @@ availability, not agent permissions. Nothing is mounted by installing the kit.
 Install inside an existing Eve 0.70.0 project:
 
 ```sh
-npm install --save-exact @tealbrick/kit@0.3.0-rc.5
+npm install --save-exact @tealbrick/kit@0.3.0-rc.7
 npx --no-install tealbrick setup
 ```
 
@@ -139,6 +139,20 @@ stops the loop with one `native.runtime.sync.stopped` line. The per-turn
   `Agent` delegates only to the configured `experts`, in the foreground with
   the session model; each expert runs with its own `tools` (workspace reads,
   `WebSearch`, `WebFetch`) and never receives Teal Brick tools.
+- **Expert contracts** (`claude.contracts`: absolute paths to
+  `tealbrick.expert-contract/v1` JSON files, e.g. from the Agent-creation
+  cookbook) run as SDK subagents. Effective scope = contract ceiling ∩ the
+  owner's Portal grants ∩ the owner's `tealbrickCalls` ceiling; experts never
+  hold credentials or delegate. Payload approvals: `approvalOperations`
+  (default `marketplace_execute`) and a contract's outward writes pause the
+  exact call as an `input.requested` approval in TBD; decline or timeout denies.
+  Each delegation is traced to `.tealbrick/native-serve/traces/*.jsonl`
+  (owner, expert@version, brief, capabilities used, output digest).
+- `GET /tealbrick/v1/capabilities` (same owner auth) reports what Portal
+  currently grants this agent: Knowledge apps from the background runtime sync
+  and, when `tealbrick native marketplace-enable` is set, Marketplace consents
+  (plugin and action names only; no credentials, leases or account
+  references). TBD uses it for Chat → Plugins.
 - Elevation only through Desktop's session-access control (owner, explicit
   confirmation, optimistic revision, no turn in flight). **Native defaults**
   snapshots `nativeTools` (still workspace-contained); **Full** uses the

package/dist/native-app-capabilities.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeSync } from './native-runtime-sync.js';
+export interface AppCapabilitiesOptions {
+    fetch?: typeof fetch;
+    now?: () => number;
+    marketplaceTtlMs?: number;
+}
+/**
+ * Owner-facing snapshot of what Portal currently grants this agent: Knowledge apps from the background
+ * runtime sync, and Marketplace consents when Marketplace is activated in this kit root. Identifiers,
+ * actions and plugin/action names only; never credentials, leases or provider account references.
+ */
+export declare function appCapabilitiesProvider(root: string, runtime: () => RuntimeSync | undefined, options?: AppCapabilitiesOptions): () => Promise<{
+    schema: number;
+    sync: {
+        error?: string | undefined;
+        lastSyncAt?: number | undefined;
+        expiresAt?: number | undefined;
+        revision?: string | undefined;
+        status: string;
+    };
+    apps: {
+        registrationId: string;
+        appId: "knowledge";
+        actions: import("@tealbrick/portal/runtime").CrudAction[];
+        available: boolean;
+        operations: import("@tealbrick/portal/runtime").KnowledgeOperation[];
+    }[];
+    marketplace: Record<string, unknown>;
+}>;

package/dist/native-app-capabilities.js

@@ -0,0 +1,36 @@
+import { MarketplaceRuntimeConnector } from '@tealbrick/portal/marketplace-runtime';
+import { readKit } from './index.js';
+import { runtimeSecret } from './secrets.js';
+const code = (v) => typeof v === 'string' && /^[a-z][a-z0-9_]{0,80}$/.test(v) ? v : undefined;
+/**
+ * Owner-facing snapshot of what Portal currently grants this agent: Knowledge apps from the background
+ * runtime sync, and Marketplace consents when Marketplace is activated in this kit root. Identifiers,
+ * actions and plugin/action names only; never credentials, leases or provider account references.
+ */
+export function appCapabilitiesProvider(root, runtime, options = {}) {
+    const now = options.now ?? Date.now, ttl = options.marketplaceTtlMs ?? 30_000;
+    let cached;
+    async function marketplace() {
+        const kit = await readKit(root);
+        if (!kit.native?.active || !kit.native.marketplace || !kit.runtime)
+            return { enabled: false, status: 'inactive', grants: [] };
+        const { credentialRef, ...identity } = kit.runtime, key = JSON.stringify(kit.runtime);
+        if (cached && cached.key === key && now() - cached.at < ttl)
+            return cached.value;
+        let value;
+        try {
+            const consents = await new MarketplaceRuntimeConnector({ ...identity, credential: () => runtimeSecret(credentialRef, root), ...(options.fetch ? { fetch: options.fetch } : {}) }).discover();
+            value = { enabled: true, status: 'ok', grants: consents.map(c => ({ registrationId: `marketplace:${c.consentId}`, consentId: c.consentId, consentRevision: c.consentRevision, deploymentId: c.deploymentId, state: c.state, plugin: c.selection.pluginId, action: c.selection.actionKey, resourceKind: c.selection.resourceKind, operations: ['marketplace_execute'] })) };
+        }
+        catch (e) {
+            value = { enabled: true, status: 'unavailable', error: code(e?.message) ?? 'runtime_marketplace_unavailable', grants: [] };
+        }
+        cached = { at: now(), key, value };
+        return value;
+    }
+    return async () => {
+        const snap = runtime()?.snapshot();
+        const apps = (snap?.capabilities?.apps ?? []).map(a => ({ registrationId: a.registrationId, appId: a.appId, actions: [...a.actions], available: a.available, operations: [...a.operations] }));
+        return { schema: 1, sync: { status: snap?.status ?? 'disabled', ...(snap?.revision ? { revision: snap.revision } : {}), ...(snap?.expiresAt ? { expiresAt: snap.expiresAt } : {}), ...(snap?.lastSyncAt ? { lastSyncAt: snap.lastSyncAt } : {}), ...(snap?.error ? { error: snap.error } : {}) }, apps, marketplace: await marketplace() };
+    };
+}

package/dist/native-child-guard.js

@@ -9,8 +9,13 @@ try {
             throw Error('oversized_hook');
     }
     const input = JSON.parse(text);
-    if (input.hook_event_name === 'PreToolUse' && typeof input.tool_name === 'string' && input.tool_name.startsWith('mcp__tealbrick__') && input.agent_id === undefined)
-        output = {};
+    if (input.hook_event_name === 'PreToolUse' && typeof input.tool_name === 'string' && input.tool_name.startsWith('mcp__tealbrick__')) {
+        // Parent: no override. A child only if native serve admitted its contract type (non-secret env, SDK-authored agent_type);
+        // the in-process hook still checks contract ceiling ∩ owner grants on every call.
+        const admitted = (process.env.TB_CHILD_CONTRACTS ?? '').split(',').filter(Boolean);
+        if (input.agent_id === undefined || (typeof input.agent_type === 'string' && admitted.includes(input.agent_type)))
+            output = {};
+    }
 }
 catch { }
 process.stdout.write(JSON.stringify(output) + '\n');

package/dist/native-claude.d.ts

@@ -25,11 +25,22 @@ export type ClaudeAccess = {
 export declare const readOnlyTools: string[];
 /** Removed from the model's context unless a wider access mode explicitly lists them. */
 export declare const restrictedDenied: string[];
+/** What a Portal registration id refers to; resolved from the runtime's own capability snapshot. */
+export type AppRef = {
+    appId: string;
+    plugin?: string;
+    action?: string;
+};
 export interface ToolPolicy {
     access: ClaudeAccess;
     profile: ClaudeProfile;
     protectedPaths: string[];
+    resolveApp?: (registrationId: string) => Promise<AppRef | undefined>;
 }
+/** Contract experts that may reach the owner's Teal Brick connector (still bounded per call by decideTool). */
+export declare const contractsWithAppAccess: (profile: ClaudeProfile) => string[];
+/** Payload-bound approval: owner-wide approval operations, plus a contract's own list and any outward write by a contract expert. */
+export declare function needsApproval(profile: ClaudeProfile, name: string, input: Record<string, unknown>, agentType?: string): boolean;
 /** Single decision point for PreToolUse hooks and canUseTool. Names and decisions only are logged. */
 export declare function decideTool(policy: ToolPolicy, name: string, input: Record<string, unknown>, agentId?: string, agentType?: string): Promise<{
     allow: boolean;
@@ -43,6 +54,12 @@ export interface ClaudeHarnessOptions {
     protectedPaths: string[];
     log?: (event: Record<string, unknown>) => void;
     env?: NodeJS.ProcessEnv;
+    /** Resolves registration ids to apps for contract scope checks. */
+    resolveApp?: (registrationId: string) => Promise<AppRef | undefined>;
+    /** Owner-only directory for per-run delegation trace records (JSONL). */
+    traceDir?: string;
+    /** How long a payload approval may wait before it is denied. */
+    approvalTimeoutMs?: number;
 }
 /** 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. */

package/dist/native-claude.js

@@ -1,4 +1,5 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, mkdir } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { realpath } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, basename } from 'node:path';
@@ -42,12 +43,44 @@ 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);
 }
+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 (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));
@@ -64,11 +97,15 @@ export async function decideTool(policy, name, input, agentId, agentType) {
     const allowed = 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' };
     }
     const fields = pathTools[name];
@@ -104,26 +141,85 @@ export function claudeHarness(options) {
     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 experts = [...Object.keys(profile.experts), ...Object.keys(profile.contracts)];
+    const appContracts = contractsWithAppAccess(profile);
+    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 }]),
+        ...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: [...c.capabilities.builtinTools, ...(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_'))
                 out[name] = env[name];
         return out;
     };
     const optionsFor = (sessionId, access, abort) => {
-        const policy = { access, profile, protectedPaths: options.protectedPaths };
+        const policy = { access, profile, protectedPaths: options.protectedPaths, ...(options.resolveApp ? { resolveApp: options.resolveApp } : {}) };
         const builtins = access.tools.filter(t => !t.startsWith('mcp__'));
         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 });
+            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 });
             return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision.allow ? 'allow' : 'deny', permissionDecisionReason: decision.reason } };
         };
+        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 delegates = experts.length > 0 && (access.mode === 'full' || builtins.includes('Agent'));
         return {
@@ -140,7 +236,7 @@ export function claudeHarness(options) {
             ...(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 }),
@@ -242,10 +338,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 +375,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<{
@@ -108,6 +167,8 @@ 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>>;

package/dist/native-serve-config.js

@@ -16,6 +16,28 @@ export const defaultAccessTools = ['WebSearch', 'WebFetch', 'Agent', 'TodoWrite'
 /** Tools an expert subagent may hold; workspace reads stay contained and network content stays untrusted. */
 const expertTool = z.enum(['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
 const expertName = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+/** Versioned expert contract (tealbrick.expert-contract/v1). The contract is a ceiling; Portal grants still apply. */
+const opName = z.string().regex(/^[a-z][a-z0-9_.]{1,120}$/);
+export const expertContractSchema = z.object({
+    schema: z.literal('tealbrick.expert-contract/v1'),
+    id: z.string().regex(/^[a-z][a-z0-9-]{1,62}$/),
+    version: z.string().regex(/^\d+\.\d+\.\d+$/),
+    purpose: z.string().min(10).max(300),
+    instructions: z.string().min(40).max(8000),
+    input: z.object({ type: z.literal('object') }).passthrough(),
+    output: z.object({ type: z.literal('object') }).passthrough(),
+    capabilities: z.object({
+        builtinTools: z.array(expertTool).max(8),
+        apps: z.array(z.object({ appId: z.string().regex(/^[a-z][a-z0-9-]{1,40}$/), operations: z.array(z.string().regex(/^[a-z][a-z0-9_]{1,80}$/)).min(1) }).strict()).max(12),
+        marketplace: z.array(z.object({ plugin: z.string().regex(/^[a-z0-9][a-z0-9-]{1,80}$/), actions: z.array(z.string().regex(/^[a-z0-9][a-z0-9._-]{1,120}$/)).min(1) }).strict()).max(12),
+    }).strict(),
+    approval: z.object({ outwardWrites: z.enum(['always', 'never-allowed']), operations: z.array(opName) }).strict(),
+    model: z.enum(['inherit', 'opus', 'sonnet', 'haiku']),
+    effort: z.enum(['low', 'medium', 'high']).optional(),
+    budget: z.object({ maxTurns: z.number().int().min(1).max(50) }).strict(),
+    runtime: z.enum(['subagent', 'desktop-operator']),
+    changelog: z.array(z.string().max(300)).optional(),
+}).strict();
 const expert = z.object({ promptFile: absolute, description: z.string().min(1).max(300).optional(), tools: z.array(expertTool).max(8).optional(), maxTurns: z.number().int().min(1).max(50).optional(), effort: effort.optional() }).strict();
 const claude = z.object({
     /** Package directory or entry file of @anthropic-ai/claude-agent-sdk. Default: resolved from the kit root. */
@@ -34,6 +56,10 @@ const claude = z.object({
     defaultTools: z.array(z.enum(defaultAccessTools)).max(4).optional(),
     /** Expert subagents the Agent tool may delegate to, foreground only, inheriting the session model. */
     experts: z.record(expertName, expert).optional(),
+    /** Versioned expert contracts (JSON files) run as SDK subagents. Effective scope = contract ceiling ∩ owner grants. */
+    contracts: z.array(absolute).max(32).optional(),
+    /** Operations that always pause for the owner's approval of the exact payload, whoever calls them. */
+    approvalOperations: z.array(opName).max(64).optional(),
     /** Tool allowlist for the opt-in "Native defaults" session access mode. */
     nativeTools: z.array(tool).max(64).optional(),
     /** Operator-vetted read-only MCP tools, also available in Restricted mode. */
@@ -173,6 +199,19 @@ export async function resolveClaudeProfile(root, config) {
     if (instructions && instructions.length > 200000)
         throw Error('kit_native_serve_instructions_too_large');
     const readTools = c.readTools ?? agent?.readTools ?? [];
+    const contracts = {};
+    for (const path of c.contracts ?? []) {
+        await regularFile(path, { ownerOnly: false });
+        const text = await readFile(path, 'utf8');
+        if (text.length > 65536)
+            throw Error('kit_native_serve_contract_too_large');
+        const contract = parsed(expertContractSchema, text, 'kit_native_serve_contract_invalid');
+        if (contract.runtime !== 'subagent')
+            throw Error('kit_native_serve_contract_runtime_unsupported:' + contract.id);
+        if (Object.hasOwn(contracts, contract.id))
+            throw Error('kit_native_serve_contract_duplicate:' + contract.id);
+        contracts[contract.id] = contract;
+    }
     const experts = {};
     for (const [name, e] of Object.entries(c.experts ?? {})) {
         await regularFile(e.promptFile, { ownerOnly: false });
@@ -181,9 +220,12 @@ export async function resolveClaudeProfile(root, config) {
             throw Error('kit_native_serve_expert_prompt_invalid:' + name);
         experts[name] = { description: e.description ?? name.replaceAll('-', ' ') + ' for a bounded assignment', prompt, tools: [...new Set(e.tools ?? [])], maxTurns: e.maxTurns ?? 8, ...(e.effort ? { effort: e.effort } : {}) };
     }
+    for (const id of Object.keys(contracts))
+        if (Object.hasOwn(experts, id))
+            throw Error('kit_native_serve_contract_duplicate:' + id);
     return { cwd, sdkModule: c.sdkModule, instructions, model: c.model ?? recipe?.model, effort: c.effort ?? recipe?.effort,
         maxTurns: c.maxTurns ?? recipe?.maxTurns ?? 24, maxBudgetUsd: c.maxBudgetUsd ?? recipe?.maxBudgetUsd, timeoutSeconds: c.timeoutSeconds ?? recipe?.timeoutSeconds ?? 900,
-        defaultTools: [...new Set(c.defaultTools ?? [])], experts,
+        defaultTools: [...new Set(c.defaultTools ?? [])], experts, contracts, approvalOperations: [...new Set(c.approvalOperations ?? ['marketplace_execute'])],
         nativeTools: c.nativeTools ?? ['Read', 'Glob', 'Grep', 'TodoWrite'], readTools: readTools.filter(t => !t.startsWith('mcp__tealbrick__')),
         mcpServers: c.mcpServers ?? agent?.mcpServers ?? {}, tealbrickCalls: c.tealbrickCalls ?? agent?.tealbrickCalls ?? [],
         requireSubscription: c.requireSubscription ?? false, envPassthrough: c.envPassthrough ?? [] };

package/dist/native-serve.d.ts

@@ -1,6 +1,7 @@
 import { type AuthResult } from '@tealbrick/portal';
 import { type ClaudeSdk } from './native-claude.js';
 import { type RuntimeSyncOptions } from './native-runtime-sync.js';
+import { type AppCapabilitiesOptions } from './native-app-capabilities.js';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export declare function langchainHarness(): never;
 export interface ServeDependencies {
@@ -10,6 +11,9 @@ export interface ServeDependencies {
     env?: NodeJS.ProcessEnv;
     /** Background Portal config/ack sync for this runtime; false disables it (tests only). */
     runtimeSync?: RuntimeSyncOptions | false;
+    /** Test seams for the owner-only /tealbrick/v1/capabilities snapshot. */
+    appCapabilities?: AppCapabilitiesOptions;
+    approvalTimeoutMs?: number;
 }
 /** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
 export declare function createNativeServe(root: string, deps?: ServeDependencies): Promise<{

package/dist/native-serve.js

@@ -12,6 +12,7 @@ import { readKit } from './index.js';
 import { nativeSdkConfig } from './native-setup.js';
 import { claudeHarness, loadClaudeSdk } from './native-claude.js';
 import { startRuntimeSync } from './native-runtime-sync.js';
+import { appCapabilitiesProvider } from './native-app-capabilities.js';
 import { publicHosts, readClaudeAttachment, readServeConfig, resolveClaudeProfile, servePaths } from './native-serve-config.js';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export function langchainHarness() { throw Error('kit_native_serve_langchain_unsupported'); }
@@ -34,9 +35,20 @@ export async function createNativeServe(root, deps = {}) {
     await mkdir(paths.state, { recursive: true, mode: 0o700 });
     let adapter;
     let codex;
+    let runtime;
+    const appCapabilities = appCapabilitiesProvider(root, () => runtime, deps.appCapabilities);
     if (kit.native.harness === 'claude') {
         const profile = await resolveClaudeProfile(root, config);
-        adapter = claudeHarness({ name: config.agent.name, profile, attachment: await readClaudeAttachment(root), sdk: deps.claudeSdk ?? await loadClaudeSdk(root, profile.sdkModule), protectedPaths: [join(root, '.tealbrick')], log, env: deps.env });
+        // Contract scope checks resolve registration ids from this runtime's own Portal-granted snapshot.
+        const resolveApp = async (registrationId) => {
+            const snap = await appCapabilities();
+            const app = snap.apps.find(a => a.registrationId === registrationId);
+            if (app)
+                return { appId: app.appId };
+            const grant = snap.marketplace.grants.find(g => g.registrationId === registrationId);
+            return grant ? { appId: 'marketplace', plugin: grant.plugin, action: grant.action } : undefined;
+        };
+        adapter = claudeHarness({ name: config.agent.name, profile, attachment: await readClaudeAttachment(root), sdk: deps.claudeSdk ?? await loadClaudeSdk(root, profile.sdkModule), protectedPaths: [join(root, '.tealbrick')], log, env: deps.env, resolveApp, traceDir: join(paths.state, 'traces'), ...(deps.approvalTimeoutMs ? { approvalTimeoutMs: deps.approvalTimeoutMs } : {}) });
     }
     else if (kit.native.harness === 'codex') {
         if (!config.codex)
@@ -49,10 +61,10 @@ export async function createNativeServe(root, deps = {}) {
     else
         adapter = langchainHarness();
     const authenticate = deps.authenticate ?? createPortalVerifier({ issuer: kit.runtime.issuer, org: kit.runtime.org, agent: config.agent.name }).authenticate;
-    const bridge = await createNativeBridge({ name: config.agent.name, ownerId: config.agent.ownerId, root: paths.state, port: config.port, allowedHosts: publicHosts(config), authenticate, adapter, maxActiveTurns: config.maxActiveTurns ?? 2, log });
+    const bridge = await createNativeBridge({ name: config.agent.name, ownerId: config.agent.ownerId, root: paths.state, port: config.port, allowedHosts: publicHosts(config), authenticate, adapter, maxActiveTurns: config.maxActiveTurns ?? 2, log, appCapabilities });
     // Portal marks a runtime expired unless it re-acknowledges its signed config within the 300s lease;
     // an idle serve process has no per-turn MCP child doing that, so it keeps the lease itself.
-    const runtime = deps.runtimeSync === false ? undefined : startRuntimeSync(root, { log, ...deps.runtimeSync });
+    runtime = deps.runtimeSync === false ? undefined : startRuntimeSync(root, { log, ...deps.runtimeSync });
     return { ...bridge, port: config.port, harness: kit.native.harness, runtime, close: async () => { await runtime?.stop(); await bridge.close(); await codex?.close(); } };
 }
 export async function serveNative(root) {

package/dist/native.d.ts

@@ -37,5 +37,6 @@ export declare function nativeConnector(): {
     }>;
     call: (registrationId: string, operation: KnowledgeOperation, input?: Record<string, unknown>, signal?: AbortSignal) => Promise<any>;
 };
+export declare const nativeUsage = "Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable";
 export declare function nativeCommand(args: string[], root: string): Promise<void>;
 export { guidedNativeSetup, nativeSdkConfig };

package/dist/native.js

@@ -64,6 +64,7 @@ function serveFlags(args, values, switches) {
     }
     return flags;
 }
+export const nativeUsage = 'Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable';
 export async function nativeCommand(args, root) {
     if (args[0] === 'serve' || args[0] === 'enroll') {
         const flags = args[0] === 'serve' ? serveFlags(args.slice(1), ['root'], ['install-launchd', 'uninstall', 'no-load']) : serveFlags(args.slice(1), ['root', 'url', 'port'], ['skip-endpoint-check']);
@@ -111,6 +112,11 @@ export async function nativeCommand(args, root) {
         return;
     }
     const command = args[0], flags = {};
+    // A bare `tealbrick native` or help request prints usage; it is not a failed setup.
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        console.log(nativeUsage);
+        return;
+    }
     for (let i = 1; i < args.length; i += 2) {
         if (!/^--(root|harness|workspace|workspace-name|create-workspace|node|agent|agent-name|create-agent|delegation|issuer)$/.test(args[i]) || !args[i + 1] || flags[args[i].slice(2)])
             throw Error('kit_native_invalid_arguments');
@@ -171,6 +177,7 @@ export async function nativeCommand(args, root) {
         console.log(JSON.stringify({ active: command === 'enable' }));
         return;
     }
-    throw Error('Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable');
+    console.error(nativeUsage);
+    process.exitCode = 2;
 }
 export { guidedNativeSetup, nativeSdkConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.5",
+  "version": "0.3.0-rc.7",
   "type": "module",
   "license": "MIT",
   "description": "Complete Teal Brick package kit with explicit Eve capability activation",
@@ -43,11 +43,11 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@tealbrick/portal": "0.3.0-rc.5",
-    "@tealbrick/avm": "0.3.0-rc.5",
-    "@tealbrick/voice": "0.3.0-rc.5",
-    "@tealbrick/vision": "0.3.0-rc.5",
-    "@tealbrick/deliver": "0.3.0-rc.5",
+    "@tealbrick/portal": "0.3.0-rc.7",
+    "@tealbrick/avm": "0.3.0-rc.7",
+    "@tealbrick/voice": "0.3.0-rc.7",
+    "@tealbrick/vision": "0.3.0-rc.7",
+    "@tealbrick/deliver": "0.3.0-rc.7",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },