zigmini 1.0.0-beta.3 → 1.1.0-beta.2

package/host/omo-bridge/agent-execution.ts

@@ -0,0 +1,158 @@
+/**
+ * 294 item 6: confined code execution for registered agents (plan C6).
+ *
+ * eval runs only in the engine's existing QuickJS cell (kernels/sandbox/sandbox-cell.ts) with the sandbox forced on.
+ * Every tool the cell calls goes through the agent authority first. bash/powershell/command monitors run under
+ * sandbox-exec with agent-execution.sb, in a work root that holds only copies of files the authority allowed.
+ * The executor never writes to the host outside that root and never calls a settings or permission API.
+ */
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize } from "node:path";
+import type { AuthorizationOutcome } from "../../src/agent/tool-permission-types.ts";
+import { SANDBOX_CELL_MODULE } from "../../src/engine/sandbox-cell.ts";
+
+export const SANDBOX_PROFILE = join(import.meta.dir, "agent-execution.sb");
+export const EVAL_MEMORY_MB = 64;
+export const EVAL_TIMEOUT_SECONDS = 300;
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+const BASH = "/bin/bash";
+
+export interface AuthorityCall { readonly toolName: string; readonly args: unknown; readonly operation: string }
+export type Authorize = (call: AuthorityCall) => AuthorizationOutcome | Promise<AuthorizationOutcome>;
+export interface ToolResult { readonly content: readonly unknown[]; readonly details?: unknown }
+export type ExecuteTool = (toolName: string, params: unknown, options?: { signal?: AbortSignal }) => Promise<ToolResult>;
+export interface ResolvedSandbox { readonly enabled: boolean; readonly memoryMb: number; readonly timeoutSeconds: number }
+export type Shell = "bash" | "powershell";
+
+/** The cell's limits: always isolated, never above the engine's 64 MiB / 300 s defaults. A model cannot turn it off. */
+export function forcedSandbox(requested: Partial<ResolvedSandbox> = {}): ResolvedSandbox {
+	const memory = requested.memoryMb ?? EVAL_MEMORY_MB;
+	const timeout = requested.timeoutSeconds ?? EVAL_TIMEOUT_SECONDS;
+	return {
+		enabled: true,
+		memoryMb: memory > 0 ? Math.min(memory, EVAL_MEMORY_MB) : EVAL_MEMORY_MB,
+		timeoutSeconds: timeout > 0 ? Math.min(timeout, EVAL_TIMEOUT_SECONDS) : EVAL_TIMEOUT_SECONDS,
+	};
+}
+
+function denied(outcome: AuthorizationOutcome): Error | null {
+	return outcome.decision === "allow" ? null : new Error(`agent_tool_denied:${outcome.reason}`);
+}
+
+/** Wraps the engine's executeTool so every proxied call passes the agent authority right before it runs. */
+export function authorizedExecuteTool(authorize: Authorize, executeTool: ExecuteTool): ExecuteTool {
+	return async (toolName, params, options) => {
+		const error = denied(await authorize({ toolName, args: params, operation: toolName }));
+		if (error) throw error;
+		return executeTool(toolName, params, options);
+	};
+}
+
+/** A copy target must be a plain relative path inside the work root. */
+export function checkCopyTarget(target: string): string {
+	const clean = normalize(target);
+	if (target.length === 0 || target.includes("\0") || isAbsolute(target) || clean === "." || target.split("/").includes(".."))
+		throw new Error("agent_exec_copy_target");
+	return clean;
+}
+
+export interface CopyRequest { readonly source: string; readonly target: string }
+
+/** Creates a fresh work root under `parent` and copies only the files the authority allows for read. */
+export async function prepareWorkRoot(input: { parent: string; files: readonly CopyRequest[]; authorize: Authorize }): Promise<string> {
+	const targets = input.files.map((file) => checkCopyTarget(file.target));
+	for (const file of input.files) {
+		const error = denied(await input.authorize({ toolName: "read", args: { path: file.source }, operation: "read" }));
+		if (error) throw error;
+	}
+	const root = realpathSync(mkdtempSync(join(input.parent, "zgw-agent-exec-")));
+	input.files.forEach((file, index) => {
+		const destination = join(root, targets[index]!);
+		mkdirSync(dirname(destination), { recursive: true });
+		copyFileSync(file.source, destination);
+	});
+	return root;
+}
+
+/** The only variables a confined subprocess sees. No gateway token or runtime home is inherited. */
+export function sandboxEnv(root: string): Record<string, string> {
+	return { HOME: root, TMPDIR: root, PATH: "/usr/bin:/bin", LANG: "en_US.UTF-8" };
+}
+
+function checkRoot(root: string): string {
+	if (!isAbsolute(root) || root.split("/").includes("..") || normalize(root) !== root) throw new Error("agent_exec_root");
+	return root;
+}
+
+export function sandboxArgs(input: { root: string; shell: Shell; script: string; powershellPath?: string }): string[] {
+	const root = checkRoot(input.root);
+	let interpreter = BASH;
+	let invoke = ["-c"];
+	if (input.shell === "powershell") {
+		if (!input.powershellPath) throw new Error("agent_exec_powershell_missing");
+		interpreter = input.powershellPath;
+		invoke = ["-NoProfile", "-NonInteractive", "-Command"];
+	}
+	return [SANDBOX_EXEC, "-f", SANDBOX_PROFILE, "-D", `WORK_ROOT=${root}`, "-D", `INTERPRETER=${interpreter}`,
+		"-D", `INTERPRETER_DIR=${dirname(interpreter)}`, interpreter, ...invoke, input.script];
+}
+
+/** The execution handle shape the engine's process sessions provide; Bun.spawn by default. */
+export interface ExecHandle { readonly stdout: ReadableStream<Uint8Array>; readonly stderr: ReadableStream<Uint8Array>; readonly exited: Promise<number>; kill(): void }
+export type Spawn = (argv: readonly string[], options: { cwd: string; env: Record<string, string> }) => ExecHandle;
+const bunSpawn: Spawn = (argv, options) => {
+	const child = Bun.spawn([...argv], { cwd: options.cwd, env: options.env, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+	return { stdout: child.stdout, stderr: child.stderr, exited: child.exited, kill: () => child.kill("SIGKILL") };
+};
+
+export interface RestrictedResult { readonly exitCode: number; readonly stdout: string; readonly stderr: string; readonly timedOut: boolean }
+
+export async function runRestricted(input: {
+	root: string; shell: Shell; script: string; powershellPath?: string; timeoutMs?: number; signal?: AbortSignal; spawn?: Spawn;
+}): Promise<RestrictedResult> {
+	const argv = sandboxArgs(input);
+	const handle = (input.spawn ?? bunSpawn)(argv, { cwd: input.root, env: sandboxEnv(input.root) });
+	let timedOut = false;
+	const timer = setTimeout(() => { timedOut = true; handle.kill(); }, input.timeoutMs ?? EVAL_TIMEOUT_SECONDS * 1_000);
+	const onAbort = () => handle.kill();
+	input.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		const [stdout, stderr, exitCode] = await Promise.all([new Response(handle.stdout).text(), new Response(handle.stderr).text(), handle.exited]);
+		return { exitCode, stdout, stderr, timedOut };
+	} finally {
+		clearTimeout(timer);
+		input.signal?.removeEventListener("abort", onAbort);
+	}
+}
+
+export interface EvalResult { readonly ok: boolean; readonly output: string; readonly valueRepr?: string; readonly error?: { name: string; message: string } }
+
+/** Runs a cell in the engine's existing QuickJS sandbox. No host kernel fallback. */
+export async function runAgentEval(input: {
+	code: string; engineRoot: string; toolNames: () => readonly string[]; executeTool: ExecuteTool; authorize: Authorize;
+	requested?: Partial<ResolvedSandbox>; signal?: AbortSignal;
+}): Promise<EvalResult> {
+	const cellModule = join(input.engineRoot, SANDBOX_CELL_MODULE);
+	if (!existsSync(cellModule)) throw new Error("agent_eval_engine_missing");
+	const { sandboxCellExecutor } = await import(cellModule);
+	const executor = sandboxCellExecutor(input.code, {
+		sandbox: forcedSandbox(input.requested),
+		executeTool: authorizedExecuteTool(input.authorize, input.executeTool),
+		toolNames: input.toolNames,
+	});
+	const output: string[] = [];
+	const outcome = await executor({
+		signal: input.signal ?? new AbortController().signal,
+		emit: (message: { type: string; data?: string }) => { if (message.type === "text" && message.data) output.push(message.data); },
+	});
+	return { ok: outcome.ok, output: output.join(""), valueRepr: outcome.valueRepr, error: outcome.error };
+}
+
+/** Moves one exact temp folder to the macOS Trash. Relative paths and '..' are refused. */
+export async function moveToTrash(path: string): Promise<void> {
+	checkRoot(path);
+	if (!existsSync(path)) return;
+	const child = Bun.spawn(["/usr/bin/trash", path], { stdout: "ignore", stderr: "pipe" });
+	const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+	if (code !== 0) throw new Error(`agent_exec_trash_failed:${code}:${stderr.trim()}`);
+}

package/host/omo-bridge/agent-tool-adapters.ts

@@ -0,0 +1,388 @@
+/**
+ * 294 item 8: resource scope checks for the remaining tool classes (plan C1/C6/C8/C10, interfaces I04-I12).
+ *
+ * The catalog (src/agent/tool-catalog.ts) decides whether a tool and operation are granted at all. This module adds the
+ * resource half at the real adapter boundary: each restriction adapter turns the call arguments into exact resources
+ * (`path:`, `origin:`, `provider:`, `mcp:`, `session:`, `child:`, `exec:`, `schedule:`, `memory:`, `args:`) and an active
+ * grant must cover every one of them. `run` executes the real tool only after the check and hands it a guard that
+ * re-checks redirects, resolved paths and nested tool calls with the same grants.
+ *
+ * Order (C10): access state -> lifecycle/authority epoch -> exact permission source and resources -> external action
+ * ticket -> fence at execution. No source overrides an earlier deny. Protected targets (gateway origins, loopback,
+ * the permission ledger and runtime/settings roots) are refused before any grant is looked at.
+ *
+ * Indirect execution (exec tool proxy, MCP proxy, child, scheduled run) uses `ceiling`: the effective grants are the
+ * intersection of the agent's own grants and the ceiling, never more than either side.
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { authorizeTool, describeTool } from "../../src/agent/tool-catalog.ts";
+import type { AgentAccessView, DenyReason, RegisteredToolMeta, ToolDescriptor, ToolGrant } from "../../src/agent/tool-permission-types.ts";
+import { isProtectedUrl, originOf } from "../../src/agent/aside-targets.ts";
+
+/** A grant with the resources the operator confirmed. `path:` entries cover their subtree; every other entry is exact. */
+export interface ScopedGrant extends ToolGrant {
+	readonly resources: readonly string[];
+}
+
+/**
+ * The adapter grants from the real ledger rows (AgentToolPermissionStore.policyGrants). A legacy row without stored
+ * resources (null) gets none: it still covers resource-free classes as before, but every scoped class denies it.
+ */
+export function ledgerGrants(rows: readonly (ToolGrant & { readonly resources?: readonly string[] | null })[]): ScopedGrant[] {
+	return rows.map((row) => ({
+		id: row.id, agentId: row.agentId, incarnation: row.incarnation, authorityEpoch: row.authorityEpoch, toolKey: row.toolKey,
+		operations: row.operations, state: row.state, revision: row.revision, resources: row.resources ?? [],
+	}));
+}
+
+/** A 293 selected attachment copy (I04/X1/X9). Its own authority, not a persistent tool grant. */
+export interface SelectedAttachment {
+	readonly attachmentId: string;
+	readonly recipientAgentId: string;
+	readonly authorityEpoch: number;
+}
+
+export interface AdapterContext {
+	readonly view: AgentAccessView;
+	readonly role: "agent" | "work";
+	readonly grants: readonly ScopedGrant[];
+	/** Indirect execution: effective grants are the intersection with these. null for a direct call. */
+	readonly ceiling: readonly ScopedGrant[] | null;
+	/** The agent's work root; relative paths resolve against it. */
+	readonly root: string;
+	/** The agent's own memory folder. Memory tools write only below it. */
+	readonly memoryRoot: string;
+	readonly sessionId: string;
+	readonly owned: { readonly children: readonly string[]; readonly sessions: readonly string[]; readonly execs: readonly string[] };
+	readonly attachments: readonly SelectedAttachment[];
+	/** Resolves the inner tool and arguments of an MCP proxy call. null when it cannot be resolved. */
+	readonly resolveProxy: (args: Record<string, unknown>) => { tool: RegisteredToolMeta; args: Record<string, unknown> } | null;
+	/** Consumes the one-shot external action ticket for this exact argument digest (C8). */
+	readonly consumeTicket: (agentId: string, argsDigest: string) => boolean;
+}
+
+export interface AdapterDeps {
+	readonly gatewayOrigins: readonly string[];
+	/** Ledger, runtime home, secrets and engine settings. Never readable or writable through any adapter. */
+	readonly protectedRoots: readonly string[];
+	readonly realpath?: (path: string) => string;
+}
+
+export interface ToolCall {
+	readonly tool: RegisteredToolMeta;
+	readonly operation: string;
+	readonly args: Record<string, unknown>;
+}
+
+export type AdapterDeny = DenyReason | "scope_not_granted" | "protected_path" | "protected_origin" | "invalid_target" | "not_owned"
+	| "full_access_child" | "action_ticket_required" | "user_answer_proxy" | "adapter_elsewhere" | "nesting_too_deep";
+
+export type AdapterOutcome =
+	| { readonly decision: "allow"; readonly grantId: string | null; readonly resources: readonly string[]; readonly descriptor: ToolDescriptor }
+	| { readonly decision: "deny"; readonly reason: AdapterDeny }
+	| { readonly decision: "hold"; readonly reason: "tool_changed" };
+
+export class AdapterDenied extends Error {
+	constructor(readonly reason: AdapterDeny) {
+		super(`agent_tool_denied:${reason}`);
+	}
+}
+
+const MAX_DEPTH = 4;
+const SPAWN = new Set(["task", "task_create", "workflow", "workpool", "team_create"]);
+const SCHEDULE = new Set(["schedule_wakeup", "schedule_prompt"]);
+
+function canonical(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object")
+		return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical((value as Record<string, unknown>)[key])]));
+	return value;
+}
+
+export const argsDigest = (args: unknown) => createHash("sha256").update(JSON.stringify(canonical(args ?? null))).digest("hex");
+
+/** Real path of a file that may not exist yet: the nearest existing parent is resolved and the rest appended. */
+export function realTarget(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		const parent = dirname(path);
+		if (parent === path) return path;
+		return resolve(realTarget(parent), basename(path));
+	}
+}
+
+const within = (path: string, root: string) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+
+/** True when `have` covers `want`: a `path:` entry covers its subtree, every other kind must match exactly. */
+export function covers(have: string, want: string): boolean {
+	if (have.startsWith("path:") && want.startsWith("path:")) return within(want.slice(5), have.slice(5));
+	return have === want;
+}
+
+const sameKey = (a: ToolGrant, b: ToolGrant) =>
+	a.toolKey.sourceKind === b.toolKey.sourceKind && a.toolKey.ownerId === b.toolKey.ownerId
+	&& a.toolKey.originalName === b.toolKey.originalName && a.toolKey.registrationDigest === b.toolKey.registrationDigest;
+
+/** Only what both sides allow: same tool registration, shared operations, and the narrower of each resource pair. */
+export function intersectGrants(own: readonly ScopedGrant[], ceiling: readonly ScopedGrant[]): ScopedGrant[] {
+	const out: ScopedGrant[] = [];
+	for (const grant of own) {
+		for (const limit of ceiling) {
+			if (!sameKey(grant, limit)) continue;
+			const operations = grant.operations.filter((operation) => limit.operations.includes(operation));
+			const resources = [...new Set([
+				...grant.resources.filter((r) => limit.resources.some((l) => covers(l, r))),
+				...limit.resources.filter((l) => grant.resources.some((r) => covers(r, l))),
+			])];
+			if (operations.length > 0 && resources.length > 0) out.push({ ...grant, operations, resources });
+		}
+	}
+	return out;
+}
+
+/** Child grants (C1 sub-task row): the parent's current effective grants limited to the requested tool names. */
+export function childGrants(parent: readonly ScopedGrant[], requestedTools: readonly string[]): ScopedGrant[] {
+	return parent.filter((grant) => requestedTools.includes(grant.toolKey.originalName));
+}
+
+const str = (value: unknown) => (typeof value === "string" && value.length > 0 && !value.includes("\0") ? value : null);
+const list = (value: unknown) => (Array.isArray(value) ? value : value === undefined ? [] : [value]);
+
+/** Every target path of an apply_patch body. */
+export function patchPaths(input: string): string[] {
+	const out: string[] = [];
+	for (const line of input.split("\n")) {
+		const match = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/.exec(line) ?? /^\*\*\* Move to: (.+)$/.exec(line);
+		if (match?.[1]) out.push(match[1].trim());
+	}
+	return out;
+}
+
+/** Local file paths a show_html_page document embeds. */
+export function htmlPaths(html: string): string[] {
+	return [...html.matchAll(/\bsrc\s*=\s*["'](\/[^"']+)["']/g)].map((match) => match[1] as string);
+}
+
+type Resolved = { readonly resources: string[] } | { readonly deny: AdapterDeny };
+
+export class AgentToolAdapters {
+	private readonly realpath: (path: string) => string;
+
+	constructor(private readonly deps: AdapterDeps) {
+		this.realpath = deps.realpath ?? realTarget;
+	}
+
+	/** One canonical `path:` resource, or a deny for protected or malformed targets. Checked lexically and after symlinks. */
+	path(ctx: AdapterContext, raw: unknown): Resolved {
+		const value = str(raw);
+		if (value === null) return { deny: "invalid_target" };
+		const lexical = isAbsolute(value) ? resolve(value) : resolve(ctx.root, value);
+		const real = this.realpath(lexical);
+		const roots = this.deps.protectedRoots.flatMap((root) => [root, this.realpath(root)]);
+		if (roots.some((root) => within(lexical, root) || within(real, root))) return { deny: "protected_path" };
+		return { resources: [`path:${real}`] };
+	}
+
+	private paths(ctx: AdapterContext, raws: readonly unknown[]): Resolved {
+		if (raws.length === 0) return { deny: "invalid_target" };
+		const resources: string[] = [];
+		for (const raw of raws) {
+			const one = this.path(ctx, raw);
+			if ("deny" in one) return one;
+			resources.push(...one.resources);
+		}
+		return { resources };
+	}
+
+	url(raw: unknown): Resolved {
+		const value = str(raw);
+		if (value === null || originOf(value) === null) return { deny: "invalid_target" };
+		if (isProtectedUrl(value, this.deps.gatewayOrigins)) return { deny: "protected_origin" };
+		return { resources: [`origin:${originOf(value)}`] };
+	}
+
+	/** Resources one call touches, by the descriptor's restriction adapter. */
+	resources(ctx: AdapterContext, d: ToolDescriptor, call: ToolCall): Resolved {
+		const a = call.args;
+		const name = d.key.originalName;
+		switch (d.restrictionAdapter) {
+			case "path_scope": {
+				if (name === "apply_patch") return this.paths(ctx, patchPaths(String(a.input ?? a.patch ?? "")));
+				const raws = [...list(a.path), ...list(a.paths), ...list(a.file_path), ...list(a.filePath)];
+				return this.paths(ctx, raws.length > 0 ? raws : [ctx.root]);
+			}
+			case "web_origin": {
+				if (a.url !== undefined) return this.url(a.url);
+				if (str(a.query ?? a.libraryName ?? a.libraryId) === null) return { deny: "invalid_target" };
+				return { resources: [`provider:${d.key.ownerId}/${name}`] };
+			}
+			case "media_io": {
+				const resources: string[] = [];
+				for (const raw of [...list(a.path), ...list(a.paths), ...list(a.image), ...list(a.images), ...list(a.file_path)]) {
+					const one = typeof raw === "string" && /^https?:/i.test(raw) ? this.url(raw) : this.path(ctx, raw);
+					if ("deny" in one) return one;
+					resources.push(...one.resources);
+				}
+				if (a.output !== undefined) {
+					const out = this.path(ctx, a.output);
+					if ("deny" in out) return out;
+					resources.push(...out.resources);
+				}
+				resources.push(`provider:${d.key.ownerId}/${name}`);
+				return { resources };
+			}
+			case "display_surface": {
+				const embedded = htmlPaths(String(a.html ?? ""));
+				const files = embedded.length > 0 ? this.paths(ctx, embedded) : { resources: [] as string[] };
+				return "deny" in files ? files : { resources: [...files.resources, "display:self"] };
+			}
+			case "mcp_resource": {
+				const server = str(a.server);
+				return server === null ? { deny: "invalid_target" } : { resources: [`mcp:${server}`] };
+			}
+			case "self_identity": {
+				if (call.operation === "read_self") return { resources: [`memory:${ctx.view.agentId}`] };
+				const target = this.path(ctx, a.file_path ?? a.path ?? ctx.memoryRoot);
+				if ("deny" in target) return target;
+				const memory = this.realpath(resolve(ctx.memoryRoot));
+				if (!within((target.resources[0] as string).slice(5), memory)) return { deny: "not_owned" };
+				return { resources: [`memory:${ctx.view.agentId}`] };
+			}
+			case "owned_session": {
+				if (name === "thread_answer") return { deny: "user_answer_proxy" };
+				if (name === "thread_create" || name === "thread_list" || name === "thread_bindings") return { resources: [`session:${name}`] };
+				const id = str(a.thread_id ?? a.threadId ?? a.session_id ?? a.target);
+				if (id === null) return { deny: "invalid_target" };
+				return ctx.owned.sessions.includes(id) ? { resources: [`session:${id}`] } : { deny: "not_owned" };
+			}
+			case "owned_child": {
+				if (SPAWN.has(name)) {
+					if (a.preset === "full-access" || a.fullAccess === true || a.permission === "full-access") return { deny: "full_access_child" };
+					return { resources: ["child:new"] };
+				}
+				const id = str(a.task_id ?? a.taskId ?? a.name ?? a.team);
+				if (id === null) return { deny: "invalid_target" };
+				return ctx.owned.children.includes(id) ? { resources: [`child:${id}`] } : { deny: "not_owned" };
+			}
+			case "self_state": {
+				if (!SCHEDULE.has(name)) return { resources: [`self:${ctx.sessionId}`] };
+				const target = a.target ?? a.session ?? ctx.sessionId;
+				return target === ctx.sessionId ? { resources: [`schedule:${ctx.sessionId}`] } : { deny: "not_owned" };
+			}
+			case "restricted_exec": {
+				if (name === "monitor" && a.path !== undefined) return this.path(ctx, a.path);
+				return { resources: [`exec:${ctx.root}`] };
+			}
+			case "owned_exec_handle": {
+				const id = str(a.bash_id ?? a.id);
+				if (id === null) return { deny: "invalid_target" };
+				return ctx.owned.execs.includes(id) ? { resources: [`exec-handle:${id}`] } : { deny: "not_owned" };
+			}
+			case "exact_args":
+				return { resources: [`args:${argsDigest(a)}`] };
+			case "metadata_only":
+			case "own_history":
+			case "role_only":
+				return { resources: [] };
+			case "browser_target":
+				return { deny: "adapter_elsewhere" };
+			default:
+				return { deny: "not_grantable" };
+		}
+	}
+
+	/** The full check for one call. Never executes anything. */
+	authorize(ctx: AdapterContext, call: ToolCall, depth = 0): AdapterOutcome {
+		if (depth > MAX_DEPTH) return { decision: "deny", reason: "nesting_too_deep" };
+		const { view } = ctx;
+		if (view.accessState !== "open") return { decision: "deny", reason: "agent_access_blocked" };
+		const descriptor = describeTool(call.tool);
+		if (descriptor.restrictionAdapter === "mcp_proxy") {
+			const inner = ctx.resolveProxy(call.args);
+			if (inner === null) return { decision: "deny", reason: "proxy_target_unresolved" };
+			return this.authorize(ctx, { tool: inner.tool, operation: call.operation, args: inner.args }, depth + 1);
+		}
+		if (descriptor.restrictionAdapter === "attachment_selection") return this.attachment(ctx, call, descriptor);
+		const resolved = this.resources(ctx, descriptor, call);
+		if ("deny" in resolved) return { decision: "deny", reason: resolved.deny };
+		const effective = ctx.ceiling === null ? ctx.grants : intersectGrants(ctx.grants, ctx.ceiling);
+		const candidates = effective.filter((g) => g.toolKey.sourceKind === descriptor.key.sourceKind && g.toolKey.ownerId === descriptor.key.ownerId
+			&& g.toolKey.originalName === descriptor.key.originalName);
+		let last: AdapterOutcome = { decision: "deny", reason: "no_grant" };
+		if (candidates.length === 0) {
+			const base = authorizeTool({ descriptor, grant: null, access: view, operation: call.operation, role: ctx.role });
+			if (base.decision !== "allow") return base;
+			return this.ticket(ctx, call, { decision: "allow", grantId: null, resources: resolved.resources, descriptor });
+		}
+		for (const grant of candidates) {
+			const base = authorizeTool({ descriptor, grant, access: view, operation: call.operation, role: ctx.role });
+			if (base.decision !== "allow") {
+				last = base;
+				continue;
+			}
+			if (!this.covered(grant, resolved.resources)) {
+				last = { decision: "deny", reason: "scope_not_granted" };
+				continue;
+			}
+			return this.ticket(ctx, call, { decision: "allow", grantId: grant.id, resources: resolved.resources, descriptor });
+		}
+		return last;
+	}
+
+	/** Grant `path:` entries are compared by their real path too, like the requested targets. */
+	private covered(grant: ScopedGrant, wants: readonly string[]): boolean {
+		const haves = grant.resources.map((have) => (have.startsWith("path:") ? `path:${this.realpath(have.slice(5))}` : have));
+		return wants.every((want) => haves.some((have) => covers(have, want)));
+	}
+
+	private attachment(ctx: AdapterContext, call: ToolCall, descriptor: ToolDescriptor): AdapterOutcome {
+		const id = str(call.args.attachmentId ?? call.args.attachment_id);
+		if (id === null) return { decision: "deny", reason: "invalid_target" };
+		const ok = ctx.attachments.some((s) => s.attachmentId === id && s.recipientAgentId === ctx.view.agentId && s.authorityEpoch === ctx.view.authorityEpoch);
+		return ok ? { decision: "allow", grantId: null, resources: [`attachment:${id}`], descriptor } : { decision: "deny", reason: "no_grant" };
+	}
+
+	/** External effects need the one-shot ticket for the exact arguments, on top of the tool grant (C8). */
+	private ticket(ctx: AdapterContext, call: ToolCall, allow: AdapterOutcome & { decision: "allow" }): AdapterOutcome {
+		if (allow.descriptor.effect !== "external_write") return allow;
+		return ctx.consumeTicket(ctx.view.agentId, argsDigest(call.args)) ? allow : { decision: "deny", reason: "action_ticket_required" };
+	}
+
+	/**
+	 * Authorize, then run the real tool once. The guard re-checks every later target with the same context: redirect
+	 * hops, resolved paths, nested tool calls (intersected with the effective grants), and child grant sets. A call allowed
+	 * without a grant (bootstrap, selected attachment) has no scope, so the guard refuses every later path or URL.
+	 */
+	async run<T>(ctx: AdapterContext, call: ToolCall, execute: (args: Record<string, unknown>, guard: AdapterGuard) => Promise<T>, depth = 0): Promise<T> {
+		const outcome = this.authorize(ctx, call, depth);
+		if (outcome.decision === "hold") throw new AdapterDenied("grant_not_active");
+		if (outcome.decision === "deny") throw new AdapterDenied(outcome.reason);
+		const effective = ctx.ceiling === null ? ctx.grants : intersectGrants(ctx.grants, ctx.ceiling);
+		const scope = outcome.grantId === null ? null : effective.find((g) => g.id === outcome.grantId) ?? null;
+		const guard: AdapterGuard = {
+			url: (url) => {
+				const one = this.url(url);
+				if ("deny" in one) throw new AdapterDenied(one.deny);
+				if (scope === null || !this.covered(scope, one.resources)) throw new AdapterDenied("scope_not_granted");
+			},
+			path: (path) => {
+				const one = this.path(ctx, path);
+				if ("deny" in one) throw new AdapterDenied(one.deny);
+				if (scope === null || !this.covered(scope, one.resources)) throw new AdapterDenied("scope_not_granted");
+			},
+			nested: (inner, innerExecute) => this.run({ ...ctx, ceiling: effective }, inner, innerExecute, depth + 1),
+			child: (requestedTools) => childGrants(effective, requestedTools),
+		};
+		return execute(call.args, guard);
+	}
+}
+
+export interface AdapterGuard {
+	readonly url: (url: string) => void;
+	readonly path: (path: string) => void;
+	readonly nested: <U>(call: ToolCall, execute: (args: Record<string, unknown>, guard: AdapterGuard) => Promise<U>) => Promise<U>;
+	readonly child: (requestedTools: readonly string[]) => ScopedGrant[];
+}

package/host/omo-bridge/agent-tool-permissions.ts

@@ -0,0 +1,96 @@
+/**
+ * 294 item 5: the session (bridge) side of a granted agent tool operation. The gateway side (enginePolicy, delivery,
+ * recipient check) is src/agent/tool-delivery.ts.
+ *
+ * - agentToolGatewayClient: the signed /internal/agent-tools/* client, using the shared managed-call proof.
+ * - installAgentToolBinding: keeps the rotated bind secret for the session.
+ * - execSessionSpawn: item 6 runRestricted over the engine's exec-session handle.
+ */
+import { createSecretKey, randomBytes, type KeyObject } from "node:crypto";
+import { parseManagedCallIdentity, type ManagedCallIdentity } from "../../src/agent/managed-call.ts";
+import { runRestricted, type ExecHandle, type RestrictedResult, type Shell, type Spawn } from "./agent-execution.ts";
+import { buildManagedCallProof, type ManagedCallContext } from "./managed-call.ts";
+
+export const AGENT_TOOL_ROUTES = {
+	request: "/internal/agent-tools/request",
+	action: "/internal/agent-tools/action",
+	reserve: "/internal/agent-tools/reserve",
+	start: "/internal/agent-tools/start",
+	result: "/internal/agent-tools/result",
+	policy: "/internal/agent-tools/policy",
+	policyAck: "/internal/agent-tools/policy-ack",
+} as const;
+export type AgentToolRoute = keyof typeof AGENT_TOOL_ROUTES;
+export const agentToolCall = (toolCallId: string) => `agent-tool:${toolCallId}`;
+
+/** Signed client for the internal routes. Identity comes from the trusted binding, never from the body. */
+export function agentToolGatewayClient(input: {
+	context: (toolCallId: string) => ManagedCallContext;
+	base: string;
+	token: () => string;
+	fetch?: typeof fetch;
+}) {
+	const send = async (route: AgentToolRoute, toolCallId: string, body: unknown): Promise<unknown> => {
+		const path = AGENT_TOOL_ROUTES[route];
+		const method = route === "policy" ? "GET" : "POST";
+		const bytes = new TextEncoder().encode(method === "GET" ? "" : JSON.stringify(body));
+		const proof = buildManagedCallProof(input.context(toolCallId), { method, route: path, operation: `agent_tool.${route}`, body: bytes, nonce: randomBytes(32).toString("hex") });
+		const response = await (input.fetch ?? fetch)(new URL(path, input.base), {
+			method, redirect: "error", ...(method === "GET" ? {} : { body: bytes }),
+			headers: { authorization: `Bearer ${input.token()}`, "content-type": "application/json", "x-zigmini-managed-call": Buffer.from(JSON.stringify(proof)).toString("base64") },
+		});
+		const result: unknown = await response.json();
+		if (!response.ok) throw new Error(typeof (result as { error?: unknown })?.error === "string" ? (result as { error: string }).error : `agent_tool_http_${response.status}`);
+		return result;
+	};
+	return { send };
+}
+export type { ManagedCallIdentity };
+
+/** The engine's process-session handle (bash/monitor). Item 6 runs the confined command through it. */
+export interface EngineExecSessions {
+	spawn(argv: readonly string[], options: { cwd: string; env: Record<string, string>; stdin: "ignore" }): ExecHandle;
+}
+export function execSessionSpawn(sessions: EngineExecSessions): Spawn {
+	return (argv, options) => sessions.spawn(argv, { cwd: options.cwd, env: options.env, stdin: "ignore" });
+}
+export function runConfined(sessions: EngineExecSessions, input: { root: string; shell: Shell; script: string; signal?: AbortSignal; timeoutMs?: number }): Promise<RestrictedResult> {
+	return runRestricted({ ...input, spawn: execSessionSpawn(sessions) });
+}
+
+/** Session side of the Hub bind (zgw.agent_tool_bind): keeps the rotated secret to sign /internal/agent-tools calls. */
+export interface AgentToolBindExtension {
+	readonly sessionContext: Readonly<Record<string, string>>;
+	readonly rpc: { handle(name: string, handler: (data: unknown) => unknown): void };
+	on(event: "session_start" | "session_shutdown", handler: (event: unknown, ctx: { readonly sessionManager: ManagedCallContext["nativeInstance"] }) => unknown): void;
+}
+export function installAgentToolBinding(pi: AgentToolBindExtension): {
+	context(toolCallId: string, inputId: string, activationId?: string | null): ManagedCallContext | null;
+	/** The bound agent incarnation (lifecycle epoch); null before the Hub bound this session. */
+	lifecycleEpoch(): number | null;
+} {
+	let manager: ManagedCallContext["nativeInstance"] | undefined;
+	let bound: { identity: Omit<ManagedCallIdentity, "inputId" | "toolCallId" | "logicalCallId" | "activationId">; secret: KeyObject } | null = null;
+	pi.on("session_start", (_event, ctx) => { manager = ctx.sessionManager; bound = null; });
+	pi.on("session_shutdown", () => { manager = undefined; bound = null; });
+	pi.rpc.handle("zgw.agent_tool_bind", (data) => {
+		const value = data as { secret?: unknown; identity?: Record<string, unknown> } | null;
+		if (!value || typeof value.secret !== "string" || !/^[a-f0-9]{64}$/.test(value.secret) || !value.identity || !manager) throw new Error("agent_tool_bind_invalid");
+		const identity = parseManagedCallIdentity({ ...value.identity, inputId: "pending", toolCallId: "pending", logicalCallId: "pending", activationId: null });
+		if (identity.role !== "agent" || identity.agentId !== pi.sessionContext.zgw_agent || identity.convId !== pi.sessionContext.zgw_conv ||
+			identity.durableSessionId !== manager.getSessionId() || identity.sessionPath !== manager.getSessionFile()) throw new Error("agent_tool_bind_mismatch");
+		const { inputId: _i, toolCallId: _t, logicalCallId: _l, activationId: _a, ...rest } = identity;
+		bound = { identity: rest, secret: createSecretKey(Buffer.from(value.secret, "hex")) };
+		return { ok: true };
+	});
+	return {
+		lifecycleEpoch: () => bound?.identity.lifecycleEpoch ?? null,
+		context(toolCallId, inputId, activationId = null) {
+			const current = bound, native = manager;
+			if (!current || !native) return null;
+			const identity = parseManagedCallIdentity({ ...current.identity, inputId, toolCallId, logicalCallId: agentToolCall(toolCallId), activationId });
+			return { native: { sessionManager: native }, nativeInstance: native, identity, secret: current.secret,
+				currentIdentity: () => (bound === current ? identity : null) };
+		},
+	};
+}