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

package/src/agent/tool-permissions.ts

@@ -0,0 +1,1366 @@
+/**
+ * 294 persistent agent tool permission ledger (plan C2/C3/C5/C10) and the owner caller helper (C3).
+ *
+ * The ledger lives in the existing Store connection. Grant (request -> granted|denied|cancelled), execution
+ * (ready -> reserved -> started -> succeeded|failed|outcome_unknown, ready/reserved -> cancelled) and resume
+ * (queued -> received -> continued) are separate rows with separate states. Only an owner answer that carries the
+ * server's proposal digest and a verified OwnerPrincipal creates a grant; the answer, the grant, the policy revision
+ * and the execution/resume intent are written by one Store transaction (Store.answerAgentToolDecision).
+ */
+import { createHash, randomBytes } from "node:crypto";
+import type { Database } from "bun:sqlite";
+import type { DeviceRecord } from "../store.ts";
+import type { AgentAccessView, ToolKey } from "./tool-permission-types.ts";
+import type { LegacyScopeItem } from "./definition.ts";
+
+export type { AgentAccessView } from "./tool-permission-types.ts";
+
+export const TOOL_PURPOSES = ["agent_tool_grant", "agent_tool_action", "agent_tool_migration"] as const;
+export type DecisionPurpose = "ordinary" | "native_permission" | (typeof TOOL_PURPOSES)[number];
+
+/** Verified owner of a permission answer or edit. Built only at the caller boundary (AgentToolClients.principal). */
+export interface OwnerPrincipal {
+	readonly ownerRef: "owner";
+	readonly client: "web" | "android";
+	readonly credentialRevision: string;
+	readonly sessionRef: string;
+}
+
+/** Structured answer for the tool purposes. Free text, confirm true or value never become a grant. */
+export interface AgentToolGrantAnswer {
+	readonly expectedRevision: number;
+	readonly submissionId: string;
+	readonly mode: "answer";
+	readonly response: { readonly toolGrant: { readonly choice: "allow" | "deny"; readonly proposalDigest: string } } | { readonly cancelled: true }
+		| { readonly toolMigration: { readonly proposalDigest: string; readonly items: Readonly<Record<string, unknown>> } };
+}
+
+/** The migration card of one agent and lifecycle (purpose agent_tool_migration, plan C9). */
+export interface AgentToolMigrationCard {
+	readonly decisionId: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly proposalDigest: string;
+	readonly items: readonly LegacyScopeItem[];
+	readonly state: "pending" | "confirmed" | "declined" | "applied";
+}
+
+/** Same shape as 292 CollaborationPermissionOutcome (292 contract N6). */
+export interface CollaborationPermissionOutcome {
+	readonly decisionId: string;
+	readonly decisionRevision: number;
+	readonly outcome: "allowed" | "denied" | "cancelled";
+	readonly logicalOperationId: string;
+	readonly continuationId: string;
+	readonly collaborationRequestId: string;
+	readonly blockedActivationId: string;
+	readonly originInputSeq: number;
+	readonly lifecycleEpoch: number;
+	readonly authorityEpoch: number;
+	readonly policyRevision: number;
+}
+
+export interface AgentToolRequestInput {
+	readonly agentId: string;
+	readonly convId: string;
+	readonly originInputSeq: number;
+	readonly originKind: "user" | "agent_collaboration";
+	readonly originAgentId?: string | null;
+	readonly collaborationRequestId?: string | null;
+	readonly activationId?: string | null;
+	readonly durableSessionId: string;
+	readonly logicalCallId: string;
+	readonly sourceToolCallId: string;
+	readonly toolKey: ToolKey;
+	readonly operation: string;
+	readonly args: unknown;
+	readonly scope: unknown;
+}
+
+export interface AgentToolRequestRecord {
+	readonly id: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly convId: string;
+	readonly decisionId: string;
+	readonly proposalDigest: string;
+	readonly argsDigest: string;
+	readonly state: "pending" | "granted" | "denied" | "cancelled" | "superseded";
+	readonly revision: number;
+}
+
+export type InvocationState = "ready" | "reserved" | "started" | "succeeded" | "failed" | "outcome_unknown" | "cancelled";
+
+export interface AgentToolInvocation {
+	readonly id: string;
+	readonly requestId: string | null;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly grantId: string | null;
+	readonly grantRevision: number | null;
+	readonly authorityEpoch: number;
+	readonly policyRevision: number;
+	readonly executorGeneration: number;
+	readonly state: InvocationState;
+	readonly revision: number;
+	readonly resultRef: string | null;
+}
+
+export interface AgentToolGrantRow {
+	readonly id: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly authorityEpoch: number;
+	readonly toolKey: ToolKey;
+	readonly operations: readonly string[];
+	readonly scope: unknown;
+	readonly originDecisionId: string;
+	readonly state: "active" | "revoked" | "suspended";
+	readonly revision: number;
+	/** The exact resources the owner approved (scope.resources of the request). null: a legacy grant with no stored resources. */
+	readonly resources: readonly string[] | null;
+}
+
+export type ToolPermissionErrorCode =
+	| "tool_request_invalid" | "tool_request_not_found" | "tool_request_conflict" | "args_conflict" | "proposal_digest_mismatch"
+	| "lifecycle_epoch_mismatch" | "authority_epoch_mismatch" | "agent_access_blocked" | "grant_not_found" | "grant_conflict"
+	| "policy_conflict" | "invocation_not_found" | "invocation_conflict" | "operation_conflict" | "cursor_invalid" | "cursor_stale";
+
+const STATUS: Record<ToolPermissionErrorCode, number> = {
+	tool_request_invalid: 400, cursor_invalid: 400, tool_request_not_found: 404, grant_not_found: 404, invocation_not_found: 404,
+	tool_request_conflict: 409, args_conflict: 409, proposal_digest_mismatch: 409, lifecycle_epoch_mismatch: 409,
+	authority_epoch_mismatch: 409, grant_conflict: 409, policy_conflict: 409, invocation_conflict: 409, operation_conflict: 409,
+	cursor_stale: 409, agent_access_blocked: 403,
+};
+
+export class AgentToolPermissionError extends Error {
+	readonly status: number;
+	constructor(readonly code: ToolPermissionErrorCode, status: number = STATUS[code]) {
+		super(code);
+		this.status = status;
+	}
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PAGE = 50;
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Key-sorted JSON, so the same structure always has the same digest. */
+export function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (record(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+	return JSON.stringify(value ?? null);
+}
+
+const sha256 = (text: string) => createHash("sha256").update(text).digest("hex");
+
+/**
+ * The resources a request asks the owner to approve: `scope.resources`, sorted and de-duplicated. The proposal digest
+ * already binds the scope, so the stored list is exactly what the owner saw. null when the scope names no resources;
+ * a malformed list is invalid (never silently dropped, which would store a grant without its limits).
+ */
+export function approvedResources(scope: unknown): string[] | null {
+	if (!record(scope) || scope.resources === undefined) return null;
+	const list = scope.resources;
+	if (!Array.isArray(list) || list.length === 0 ||
+		!list.every((entry) => typeof entry === "string" && entry.length > 0 && !entry.includes("\0"))) throw new AgentToolPermissionError("tool_request_invalid");
+	return [...new Set(list as string[])].sort();
+}
+
+const resourcesJson = (scope: unknown): string | null => {
+	const resources = approvedResources(scope);
+	return resources === null ? null : JSON.stringify(resources);
+};
+
+/** Scope keys that name the target itself (opaque handles). An edit changes limits, never the target. */
+const OPAQUE_SCOPE_KEYS = ["kind", "selection", "targetHandle", "targetId", "targetLabel", "targetTitle", "account", "host"] as const;
+
+/** POST .../tool-permissions/:grantId/edit body: the complete post-edit operations and scope. */
+export interface GrantEditInput {
+	readonly operationId: string;
+	readonly expectedRevision: number;
+	readonly operations: readonly string[];
+	readonly scope: Readonly<Record<string, unknown>>;
+}
+
+export type GrantEditResult =
+	| { readonly status: 200; readonly body: { grant: AgentToolGrantRow; policyRevision: number; cancelled: string[]; running: string[] } }
+	| { readonly status: 202; readonly body: { decisionId: string; proposalDigest: string; oldGrant: AgentToolGrantRow } };
+
+/** Data of the agent.tool_permissions.updated event (C10). */
+export interface PolicyUpdatedData {
+	readonly agentId: string;
+	readonly policyRevision: number;
+	readonly authorityEpoch: number;
+	readonly accessState: "open" | "blocked";
+}
+
+export function parseGrantEdit(value: unknown): GrantEditInput {
+	const keys = ["operationId", "expectedRevision", "operations", "scope"];
+	if (!record(value) || Object.keys(value).length !== keys.length || !keys.every((key) => Object.hasOwn(value, key))) throw new AgentToolPermissionError("tool_request_invalid");
+	const { operationId, expectedRevision, operations, scope } = value;
+	if (typeof operationId !== "string" || !UUID.test(operationId) || typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) ||
+		expectedRevision < 1 || !Array.isArray(operations) || operations.length === 0 || !record(scope) ||
+		!operations.every((operation) => typeof operation === "string" && operation.length > 0 && !operation.includes("\0"))) {
+		throw new AgentToolPermissionError("tool_request_invalid");
+	}
+	return { operationId, expectedRevision, operations: [...new Set(operations as string[])].sort(), scope };
+}
+
+const isStringList = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+
+/**
+ * The server's own narrow/widen decision (C8). Widening: an added operation or list value, a dropped scope key or a
+ * changed single value. Narrowing: a removed operation or list value, or a new restriction key. A mixed edit widens.
+ */
+export function classifyGrantEdit(before: { readonly operations: readonly string[]; readonly scope: unknown },
+	after: { readonly operations: readonly string[]; readonly scope: unknown }): "widen" | "narrow" | "same" {
+	if (after.operations.some((operation) => !before.operations.includes(operation))) return "widen";
+	const was = record(before.scope) ? before.scope : {};
+	const now = record(after.scope) ? after.scope : {};
+	let narrowed = before.operations.some((operation) => !after.operations.includes(operation));
+	for (const [key, old] of Object.entries(was)) {
+		if (!Object.hasOwn(now, key)) return "widen";
+		const value = now[key];
+		if (isStringList(old) && isStringList(value)) {
+			if (value.some((entry) => !old.includes(entry))) return "widen";
+			if (old.some((entry) => !value.includes(entry))) narrowed = true;
+		} else if (canonicalJson(old) !== canonicalJson(value)) return "widen";
+	}
+	if (Object.keys(now).some((key) => !Object.hasOwn(was, key))) narrowed = true;
+	return narrowed ? "narrow" : "same";
+}
+
+const policyUpdatedData = (view: AgentAccessView): PolicyUpdatedData =>
+	({ agentId: view.agentId, policyRevision: view.policyRevision, authorityEpoch: view.authorityEpoch, accessState: view.accessState });
+
+/**
+ * 292 owns agent_lifecycle.epoch. Until 292 is on dev the table does not exist; then every agent is in its first
+ * lifecycle (292 starts each agent at 1 with INSERT OR IGNORE ... 1), so 1 is the same value 292 will write.
+ */
+export function lifecycleEpoch(tx: Database, agentId: string): number {
+	const table = tx.query<{ found: number }, []>("SELECT 1 AS found FROM sqlite_master WHERE type = 'table' AND name = 'agent_lifecycle'").get();
+	if (!table) return 1;
+	return tx.query<{ epoch: number }, [string]>("SELECT epoch FROM agent_lifecycle WHERE agent_id = ?").get(agentId)?.epoch ?? 1;
+}
+
+/** 292/293 read this inside their own Store writer transaction, just before a release. Read only. */
+export function access(tx: Database, agentId: string): AgentAccessView {
+	const row = tx.query<{ policy_revision: number; authority_epoch: number; access_state: "open" | "blocked" }, [string]>(
+		"SELECT policy_revision, authority_epoch, access_state FROM agent_permission_epochs WHERE agent_id = ?",
+	).get(agentId);
+	return {
+		agentId, lifecycleEpoch: lifecycleEpoch(tx, agentId),
+		accessState: row?.access_state ?? "open", authorityEpoch: row?.authority_epoch ?? 1, policyRevision: row?.policy_revision ?? 0,
+	};
+}
+
+/** The stored owner outcome of a collaboration permission decision, exactly as committed with the answer; else null. */
+export function permissionOutcome(tx: Database, decisionId: string): CollaborationPermissionOutcome | null {
+	const row = tx.query<{ data: string }, [string]>(
+		"SELECT data FROM agent_tool_outcomes WHERE decision_id = ? AND json_extract(data, '$.collaborationRequestId') IS NOT NULL",
+	).get(decisionId);
+	return row ? JSON.parse(row.data) as CollaborationPermissionOutcome : null;
+}
+
+/** Parses the tool grant answer. Returns null when the body is not a tool grant shape (the caller decides the error). */
+export function parseToolGrantAnswer(value: unknown): AgentToolGrantAnswer | null {
+	if (!record(value) || value.mode !== "answer" || !record(value.response) ||
+		Object.keys(value).some((key) => !["expectedRevision", "submissionId", "mode", "response"].includes(key))) return null;
+	if (typeof value.expectedRevision !== "number" || !Number.isSafeInteger(value.expectedRevision) || value.expectedRevision < 1 ||
+		typeof value.submissionId !== "string" || !UUID.test(value.submissionId)) return null;
+	const common = { expectedRevision: value.expectedRevision, submissionId: value.submissionId, mode: "answer" as const };
+	const response = value.response;
+	if (response.cancelled === true && Object.keys(response).length === 1) return { ...common, response: { cancelled: true } };
+	const migration = response.toolMigration;
+	if (Object.keys(response).length === 1 && record(migration) && Object.keys(migration).length === 2 && record(migration.items) &&
+		typeof migration.proposalDigest === "string" && /^[0-9a-f]{64}$/.test(migration.proposalDigest)) {
+		return { ...common, response: { toolMigration: { proposalDigest: migration.proposalDigest, items: { ...migration.items } } } };
+	}
+	const grant = response.toolGrant;
+	if (Object.keys(response).length !== 1 || !record(grant) || Object.keys(grant).length !== 2 ||
+		(grant.choice !== "allow" && grant.choice !== "deny") || typeof grant.proposalDigest !== "string" ||
+		!/^[0-9a-f]{64}$/.test(grant.proposalDigest)) return null;
+	return { ...common, response: { toolGrant: { choice: grant.choice, proposalDigest: grant.proposalDigest } } };
+}
+
+type RequestRow = {
+	id: string; agent_id: string; incarnation: number; conv_id: string; origin_input_seq: number; origin_kind: string;
+	collaboration_request_id: string | null; activation_id: string | null; durable_session_id: string; tool_key_json: string;
+	operation: string; args_json: string; args_digest: string; scope_json: string; proposal_digest: string; decision_id: string;
+	state: AgentToolRequestRecord["state"]; revision: number;
+};
+type InvocationRow = {
+	id: string; request_id: string | null; agent_id: string; incarnation: number; grant_id: string | null; grant_revision: number | null;
+	authority_epoch: number; policy_revision: number; executor_generation: number; state: InvocationState; revision: number; result_ref: string | null;
+};
+type EditRow = {
+	decision_id: string; grant_id: string; agent_id: string; base_revision: number; operations_json: string; scope_json: string;
+	proposal_digest: string; state: "pending" | "allowed" | "denied" | "cancelled" | "superseded";
+};
+type GrantRow = {
+	id: string; agent_id: string; incarnation: number; authority_epoch: number; tool_key_json: string; operations_json: string;
+	scope_json: string; origin_decision_id: string; state: AgentToolGrantRow["state"]; revision: number; resources_json: string | null;
+};
+
+const requestRecord = (row: RequestRow): AgentToolRequestRecord => ({
+	id: row.id, agentId: row.agent_id, incarnation: row.incarnation, convId: row.conv_id, decisionId: row.decision_id,
+	proposalDigest: row.proposal_digest, argsDigest: row.args_digest, state: row.state, revision: row.revision,
+});
+const invocationRecord = (row: InvocationRow): AgentToolInvocation => ({
+	id: row.id, requestId: row.request_id, agentId: row.agent_id, incarnation: row.incarnation, grantId: row.grant_id,
+	grantRevision: row.grant_revision, authorityEpoch: row.authority_epoch, policyRevision: row.policy_revision,
+	executorGeneration: row.executor_generation, state: row.state, revision: row.revision, resultRef: row.result_ref,
+});
+const grantRecord = (row: GrantRow): AgentToolGrantRow => ({
+	id: row.id, agentId: row.agent_id, incarnation: row.incarnation, authorityEpoch: row.authority_epoch,
+	toolKey: JSON.parse(row.tool_key_json), operations: JSON.parse(row.operations_json), scope: JSON.parse(row.scope_json),
+	originDecisionId: row.origin_decision_id, state: row.state, revision: row.revision,
+	resources: row.resources_json === null ? null : JSON.parse(row.resources_json),
+});
+
+export interface AnswerResult {
+	readonly outcome: "allowed" | "denied" | "cancelled";
+	readonly grantId: string | null;
+	readonly invocationId: string | null;
+}
+
+/**
+ * Ledger rows on the Store's own connection. Every method here runs inside a transaction its caller (Store) owns or
+ * opens its own; none opens a second connection or file.
+ */
+export class AgentToolPermissionStore {
+	/**
+	 * Executor generations that reserved through this ledger instance, i.e. inside this gateway process. The Store is the
+	 * database's only writer, so a reservation of any other generation was left by a gateway process that has ended (C5).
+	 */
+	private readonly liveGenerations = new Set<number>();
+	constructor(private readonly db: Database) {}
+
+	migrate(): void {
+		this.db.transaction(() => {
+			// Purpose is a side table, not a decisions column: existing positional INSERTs and table rebuilds keep working.
+			// A decision without a row here follows its permission boolean (ordinary or native_permission).
+			this.db.exec(`
+				CREATE TABLE IF NOT EXISTS decision_purposes (
+					decision_id TEXT PRIMARY KEY,
+					purpose TEXT NOT NULL CHECK(purpose IN ('agent_tool_grant','agent_tool_action','agent_tool_migration'))
+				);
+				CREATE TABLE IF NOT EXISTS agent_permission_epochs (
+					agent_id TEXT PRIMARY KEY, policy_revision INTEGER NOT NULL DEFAULT 0, authority_epoch INTEGER NOT NULL DEFAULT 1,
+					access_state TEXT NOT NULL DEFAULT 'open' CHECK(access_state IN ('open','blocked')),
+					mode TEXT NOT NULL DEFAULT 'legacy' CHECK(mode IN ('legacy','managed'))
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_grants (
+					id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL, authority_epoch INTEGER NOT NULL,
+					tool_key_json TEXT NOT NULL, operations_json TEXT NOT NULL, scope_json TEXT NOT NULL,
+					origin_decision_id TEXT NOT NULL, origin_submission_id TEXT NOT NULL,
+					state TEXT NOT NULL CHECK(state IN ('active','revoked','suspended')), revision INTEGER NOT NULL CHECK(revision > 0),
+					created_at TEXT NOT NULL, updated_at TEXT NOT NULL, revoked_at TEXT, reason TEXT
+				);
+				CREATE INDEX IF NOT EXISTS agent_tool_grants_agent ON agent_tool_grants(agent_id, state);
+				CREATE TABLE IF NOT EXISTS agent_tool_requests (
+					id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL, conv_id TEXT NOT NULL,
+					origin_input_seq INTEGER NOT NULL, origin_kind TEXT NOT NULL CHECK(origin_kind IN ('user','agent_collaboration')),
+					origin_agent_id TEXT, collaboration_request_id TEXT, activation_id TEXT,
+					durable_session_id TEXT NOT NULL, logical_call_id TEXT NOT NULL, source_tool_call_id TEXT NOT NULL,
+					tool_key_json TEXT NOT NULL, operation TEXT NOT NULL, args_json TEXT NOT NULL, args_digest TEXT NOT NULL,
+					scope_json TEXT NOT NULL, proposal_digest TEXT NOT NULL, decision_id TEXT NOT NULL UNIQUE,
+					state TEXT NOT NULL CHECK(state IN ('pending','granted','denied','cancelled','superseded')),
+					revision INTEGER NOT NULL CHECK(revision > 0),
+					UNIQUE(agent_id, incarnation, conv_id, origin_input_seq, logical_call_id)
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_invocations (
+					id TEXT PRIMARY KEY, request_id TEXT, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL,
+					logical_operation_key TEXT NOT NULL UNIQUE, tool_key_json TEXT NOT NULL, args_json TEXT NOT NULL, args_digest TEXT NOT NULL,
+					target_identity_json TEXT NOT NULL, authority_source TEXT NOT NULL, authority_ref TEXT NOT NULL, resource_revision INTEGER,
+					grant_id TEXT, grant_revision INTEGER, policy_revision INTEGER NOT NULL, authority_epoch INTEGER NOT NULL,
+					action_ticket_id TEXT UNIQUE, executor_generation INTEGER NOT NULL DEFAULT 0,
+					state TEXT NOT NULL CHECK(state IN ('ready','reserved','started','succeeded','failed','outcome_unknown','cancelled')),
+					revision INTEGER NOT NULL CHECK(revision > 0), result_ref TEXT, started_at TEXT, settled_at TEXT
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_continuations (
+					id TEXT PRIMARY KEY, invocation_id TEXT NOT NULL UNIQUE, conv_id TEXT NOT NULL, origin_input_seq INTEGER NOT NULL,
+					durable_session_id TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('queued','received','continued','cancelled')),
+					revision INTEGER NOT NULL CHECK(revision > 0), accepted_input_seq INTEGER
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_action_tickets (
+					id TEXT PRIMARY KEY, origin_decision_id TEXT NOT NULL UNIQUE, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL,
+					authority_epoch INTEGER NOT NULL, args_digest TEXT NOT NULL, target_digest TEXT NOT NULL,
+					state TEXT NOT NULL CHECK(state IN ('unused','consumed','revoked')), invocation_id TEXT UNIQUE,
+					revision INTEGER NOT NULL CHECK(revision > 0)
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_session_policy (
+					durable_session_id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL,
+					executor_generation INTEGER NOT NULL, desired_revision INTEGER NOT NULL, applied_revision INTEGER, status TEXT NOT NULL
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_outcomes (
+					decision_id TEXT PRIMARY KEY, request_id TEXT NOT NULL UNIQUE,
+					outcome TEXT NOT NULL CHECK(outcome IN ('allowed','denied','cancelled')),
+					data TEXT NOT NULL, principal TEXT NOT NULL, created_at TEXT NOT NULL
+				);
+				CREATE TABLE IF NOT EXISTS agent_tool_operations (
+					operation_id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, kind TEXT NOT NULL,
+					request_json TEXT NOT NULL, result_json TEXT NOT NULL, created_at TEXT NOT NULL
+				);
+			`);
+			// Step 2 (294 resources): the approved resources of each grant. Existing rows stay NULL (legacy, no resources), so
+			// an upgrade never widens them: a scoped tool class denies a grant without resources.
+			const grantColumns = this.db.query<{ name: string }, []>("PRAGMA table_info(agent_tool_grants)").all();
+			if (!grantColumns.some((column) => column.name === "resources_json")) this.db.exec("ALTER TABLE agent_tool_grants ADD COLUMN resources_json TEXT");
+			// Step 3 (294 item 11): one migration card per agent and lifecycle; a cancelled card leaves room for a new one.
+			this.db.exec(`
+				CREATE TABLE IF NOT EXISTS agent_tool_migrations (
+					id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, incarnation INTEGER NOT NULL, conv_id TEXT NOT NULL,
+					decision_id TEXT NOT NULL UNIQUE, items_json TEXT NOT NULL, proposal_digest TEXT NOT NULL,
+					state TEXT NOT NULL CHECK(state IN ('pending','confirmed','declined','applied','cancelled')), choices_json TEXT,
+					revision INTEGER NOT NULL CHECK(revision > 0), created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+				);
+				CREATE INDEX IF NOT EXISTS agent_tool_migrations_agent ON agent_tool_migrations(agent_id, incarnation, state);
+			`);
+			// Step 4 (294 grant edit): a widening waits on its inbox card; the stored scope is what an allow applies.
+			this.db.exec(`
+				CREATE TABLE IF NOT EXISTS agent_tool_grant_edits (
+					decision_id TEXT PRIMARY KEY, grant_id TEXT NOT NULL, agent_id TEXT NOT NULL, base_revision INTEGER NOT NULL,
+					operations_json TEXT NOT NULL, scope_json TEXT NOT NULL, proposal_digest TEXT NOT NULL,
+					state TEXT NOT NULL CHECK(state IN ('pending','allowed','denied','cancelled','superseded')),
+					created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+				);
+				CREATE INDEX IF NOT EXISTS agent_tool_grant_edits_grant ON agent_tool_grant_edits(grant_id, state);
+			`);
+		}).immediate();
+	}
+
+	purpose(decisionId: string): DecisionPurpose | null {
+		return this.db.query<{ purpose: DecisionPurpose }, [string]>(
+			`SELECT COALESCE(p.purpose, CASE WHEN d.permission = 1 THEN 'native_permission' ELSE 'ordinary' END) AS purpose
+			FROM decisions d LEFT JOIN decision_purposes p ON p.decision_id = d.id WHERE d.id = ?`,
+		).get(decisionId)?.purpose ?? null;
+	}
+
+	isToolPurpose(decisionId: string): boolean {
+		const purpose = this.purpose(decisionId);
+		return purpose !== null && (TOOL_PURPOSES as readonly string[]).includes(purpose);
+	}
+
+	private epochs(agentId: string): { policy_revision: number; authority_epoch: number; access_state: "open" | "blocked" } {
+		this.db.query("INSERT OR IGNORE INTO agent_permission_epochs (agent_id) VALUES (?)").run(agentId);
+		return this.db.query<{ policy_revision: number; authority_epoch: number; access_state: "open" | "blocked" }, [string]>(
+			"SELECT policy_revision, authority_epoch, access_state FROM agent_permission_epochs WHERE agent_id = ?",
+		).get(agentId)!;
+	}
+
+	private bumpPolicy(agentId: string): number {
+		this.epochs(agentId);
+		this.db.query("UPDATE agent_permission_epochs SET policy_revision = policy_revision + 1, mode = 'managed' WHERE agent_id = ?").run(agentId);
+		const revision = this.epochs(agentId).policy_revision;
+		// Apply intent: every live session of this agent must apply this revision before it may run a new tool.
+		this.db.query("UPDATE agent_tool_session_policy SET desired_revision = ? WHERE agent_id = ?").run(revision, agentId);
+		return revision;
+	}
+
+	private requestRow(where: string, ...values: (string | number)[]): RequestRow | null {
+		return this.db.query<RequestRow, (string | number)[]>(`SELECT * FROM agent_tool_requests WHERE ${where}`).get(...values);
+	}
+
+	requestByDecision(decisionId: string): AgentToolRequestRecord | null {
+		const row = this.requestRow("decision_id = ?", decisionId);
+		return row ? requestRecord(row) : null;
+	}
+
+	/** The existing request for the same logical call, or null. Same call with other args or tool is a conflict (409). */
+	existingRequest(input: AgentToolRequestInput): AgentToolRequestRecord | null {
+		const incarnation = lifecycleEpoch(this.db, input.agentId);
+		const row = this.requestRow("agent_id = ? AND incarnation = ? AND conv_id = ? AND origin_input_seq = ? AND logical_call_id = ?",
+			input.agentId, incarnation, input.convId, input.originInputSeq, input.logicalCallId);
+		if (!row) return null;
+		if (row.args_digest !== sha256(canonicalJson(input.args)) || row.tool_key_json !== canonicalJson(input.toolKey) ||
+			row.operation !== input.operation || row.scope_json !== canonicalJson(input.scope)) throw new AgentToolPermissionError("args_conflict");
+		return requestRecord(row);
+	}
+
+	/**
+	 * Validates the request and computes the server proposal. The digest binds agent, lifecycle, tool, operation, scope and args;
+	 * an external action card (C8) also binds its purpose, so a grant answer can never confirm an action or the reverse.
+	 */
+	proposal(input: AgentToolRequestInput, purpose: "agent_tool_grant" | "agent_tool_action" = "agent_tool_grant"): { requestId: string; incarnation: number; argsDigest: string; proposalDigest: string; payload: Record<string, unknown> } {
+		if (!input.agentId || !input.convId || !Number.isSafeInteger(input.originInputSeq) || input.originInputSeq < 1 ||
+			!input.durableSessionId || !input.logicalCallId || !input.sourceToolCallId || !input.operation ||
+			!record(input.toolKey) || !input.toolKey.originalName || !input.toolKey.registrationDigest ||
+			(input.originKind === "agent_collaboration") !== Boolean(input.collaborationRequestId && input.activationId)) {
+			throw new AgentToolPermissionError("tool_request_invalid");
+		}
+		approvedResources(input.scope);
+		const view = this.epochs(input.agentId);
+		if (view.access_state === "blocked") throw new AgentToolPermissionError("agent_access_blocked");
+		const incarnation = lifecycleEpoch(this.db, input.agentId);
+		const argsDigest = sha256(canonicalJson(input.args));
+		const proposalDigest = sha256(canonicalJson({
+			agentId: input.agentId, incarnation, authorityEpoch: view.authority_epoch, toolKey: input.toolKey,
+			operation: input.operation, scope: input.scope ?? null, argsDigest, ...(purpose === "agent_tool_action" ? { purpose } : {}),
+		}));
+		return {
+			requestId: crypto.randomUUID(), incarnation, argsDigest, proposalDigest,
+			payload: {
+				purpose, agentId: input.agentId, toolKey: input.toolKey, operation: input.operation,
+				scope: input.scope ?? null, proposalDigest, originKind: input.originKind,
+				...(input.originAgentId ? { originAgentId: input.originAgentId } : {}),
+			},
+		};
+	}
+
+	insertRequest(input: AgentToolRequestInput, proposal: ReturnType<AgentToolPermissionStore["proposal"]>, decisionId: string,
+		purpose: "agent_tool_grant" | "agent_tool_action" = "agent_tool_grant"): AgentToolRequestRecord {
+		this.db.query("INSERT INTO decision_purposes (decision_id, purpose) VALUES (?, ?)").run(decisionId, purpose);
+		this.db.query("UPDATE decisions SET reason = ? WHERE id = ?").run(purpose === "agent_tool_action" ? "agent_tool_action" : "agent_tool_permission", decisionId);
+		this.db.query(`INSERT INTO agent_tool_requests (id, agent_id, incarnation, conv_id, origin_input_seq, origin_kind, origin_agent_id,
+			collaboration_request_id, activation_id, durable_session_id, logical_call_id, source_tool_call_id, tool_key_json, operation,
+			args_json, args_digest, scope_json, proposal_digest, decision_id, state, revision)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 1)`).run(
+			proposal.requestId, input.agentId, proposal.incarnation, input.convId, input.originInputSeq, input.originKind,
+			input.originAgentId ?? null, input.collaborationRequestId ?? null, input.activationId ?? null, input.durableSessionId,
+			input.logicalCallId, input.sourceToolCallId, canonicalJson(input.toolKey), input.operation, canonicalJson(input.args),
+			proposal.argsDigest, canonicalJson(input.scope), proposal.proposalDigest, decisionId);
+		return requestRecord(this.requestRow("id = ?", proposal.requestId)!);
+	}
+
+	/** The owner answer to any tool purpose card, in the caller's transaction: a widening edit card, else answer(). */
+	answerToolDecision(decisionId: string, decisionRevision: number, answer: AgentToolGrantAnswer, principal: OwnerPrincipal): AnswerResult {
+		const edit = this.db.query<EditRow, [string]>("SELECT * FROM agent_tool_grant_edits WHERE decision_id = ?").get(decisionId);
+		if (edit) return this.answerEdit(edit, answer);
+		return this.answer(decisionId, decisionRevision, answer, principal);
+	}
+
+	/**
+	 * Records the owner answer in the caller's transaction: request state, grant, policy revision, execution intent
+	 * (ready invocation) and the stored owner outcome. Throws before any write when the answer does not match.
+	 */
+	answer(decisionId: string, decisionRevision: number, answer: AgentToolGrantAnswer, principal: OwnerPrincipal): AnswerResult {
+		if (this.purpose(decisionId) === "agent_tool_migration") return this.answerMigration(decisionId, answer);
+		const row = this.requestRow("decision_id = ?", decisionId);
+		if (!row) throw new AgentToolPermissionError("tool_request_not_found");
+		if (row.state !== "pending") throw new AgentToolPermissionError("tool_request_conflict");
+		if ("toolMigration" in answer.response) throw new AgentToolPermissionError("tool_request_invalid");
+		let outcome: AnswerResult["outcome"] = "cancelled";
+		if ("toolGrant" in answer.response) {
+			if (answer.response.toolGrant.proposalDigest !== row.proposal_digest) throw new AgentToolPermissionError("proposal_digest_mismatch");
+			outcome = answer.response.toolGrant.choice === "allow" ? "allowed" : "denied";
+		}
+		const lifecycle = lifecycleEpoch(this.db, row.agent_id);
+		if (outcome === "allowed" && lifecycle !== row.incarnation) throw new AgentToolPermissionError("lifecycle_epoch_mismatch");
+		let view = this.epochs(row.agent_id);
+		let grantId: string | null = null;
+		let invocationId: string | null = null;
+		const now = new Date().toISOString();
+		if (outcome === "allowed" && this.purpose(decisionId) === "agent_tool_action") {
+			({ grantId, invocationId } = this.issueActionTicket(row, decisionId, view));
+		} else if (outcome === "allowed") {
+			// An explicit allow after a revoke-all re-opens access at the current epoch; older grants stay revoked.
+			if (view.access_state === "blocked") this.db.query("UPDATE agent_permission_epochs SET access_state = 'open' WHERE agent_id = ?").run(row.agent_id);
+			const policyRevision = this.bumpPolicy(row.agent_id);
+			view = this.epochs(row.agent_id);
+			const existing = this.db.query<GrantRow, [string, number, number, string, string]>(
+				`SELECT * FROM agent_tool_grants WHERE agent_id = ? AND incarnation = ? AND authority_epoch = ? AND tool_key_json = ?
+				AND scope_json = ? AND state = 'active' ORDER BY created_at LIMIT 1`,
+			).get(row.agent_id, row.incarnation, view.authority_epoch, row.tool_key_json, row.scope_json);
+			let grantRevision: number;
+			if (existing && (JSON.parse(existing.operations_json) as string[]).includes(row.operation)) {
+				grantId = existing.id;
+				grantRevision = existing.revision;
+			} else {
+				grantId = crypto.randomUUID();
+				grantRevision = 1;
+				this.db.query(`INSERT INTO agent_tool_grants (id, agent_id, incarnation, authority_epoch, tool_key_json, operations_json,
+					scope_json, origin_decision_id, origin_submission_id, state, revision, created_at, updated_at, resources_json)
+					VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', 1, ?, ?, ?)`).run(grantId, row.agent_id, row.incarnation, view.authority_epoch,
+					row.tool_key_json, JSON.stringify([row.operation]), row.scope_json, decisionId, answer.submissionId, now, now,
+					resourcesJson(JSON.parse(row.scope_json)));
+			}
+			invocationId = crypto.randomUUID();
+			this.db.query(`INSERT INTO agent_tool_invocations (id, request_id, agent_id, incarnation, logical_operation_key, tool_key_json,
+				args_json, args_digest, target_identity_json, authority_source, authority_ref, grant_id, grant_revision, policy_revision,
+				authority_epoch, state, revision) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'persistent_tool', ?, ?, ?, ?, ?, 'ready', 1)`).run(
+				invocationId, row.id, row.agent_id, row.incarnation, `request:${row.id}`, row.tool_key_json, row.args_json, row.args_digest,
+				row.scope_json, grantId, grantId, grantRevision, policyRevision, view.authority_epoch);
+		}
+		this.db.query("UPDATE agent_tool_requests SET state = ?, revision = revision + 1 WHERE id = ?")
+			.run(outcome === "allowed" ? "granted" : outcome, row.id);
+		const stored = {
+			decisionId, decisionRevision, outcome, logicalOperationId: `request:${row.id}`,
+			continuationId: crypto.randomUUID(), collaborationRequestId: row.collaboration_request_id,
+			blockedActivationId: row.activation_id, originInputSeq: row.origin_input_seq, lifecycleEpoch: lifecycle,
+			authorityEpoch: view.authority_epoch, policyRevision: view.policy_revision,
+		};
+		this.db.query("INSERT INTO agent_tool_outcomes (decision_id, request_id, outcome, data, principal, created_at) VALUES (?, ?, ?, ?, ?, ?)")
+			.run(decisionId, row.id, outcome, JSON.stringify(stored),
+				JSON.stringify({ client: principal.client, credentialRevision: principal.credentialRevision, sessionRef: principal.sessionRef }), now);
+		return { outcome, grantId, invocationId };
+	}
+
+	/**
+	 * The active grant of this exact tool registration that names the catalog operation, at the agent's current lifecycle
+	 * and authority epoch; null when there is none. An external action needs it on top of its one-shot ticket (C8).
+	 */
+	actionGrant(agentId: string, toolKey: unknown, operation: string): AgentToolGrantRow | null {
+		const view = this.epochs(agentId);
+		if (view.access_state === "blocked") return null;
+		return this.db.query<GrantRow, [string, number, number, string]>(
+			`SELECT * FROM agent_tool_grants WHERE agent_id = ? AND incarnation = ? AND authority_epoch = ? AND tool_key_json = ? AND state = 'active'
+			ORDER BY created_at, id`,
+		).all(agentId, lifecycleEpoch(this.db, agentId), view.authority_epoch, canonicalJson(toolKey)).map(grantRecord)
+			.find((grant) => grant.operations.includes(operation)) ?? null;
+	}
+
+	/**
+	 * C8 owner allow of an agent_tool_action card, in the answer transaction: one unused ticket bound to the exact args and
+	 * target digest and one ready execution that names it. No grant or policy revision changes; start consumes the ticket.
+	 */
+	private issueActionTicket(row: RequestRow, decisionId: string, view: { authority_epoch: number; policy_revision: number; access_state: "open" | "blocked" }):
+		{ grantId: string; invocationId: string } {
+		if (view.access_state === "blocked") throw new AgentToolPermissionError("agent_access_blocked");
+		const grant = this.actionGrant(row.agent_id, JSON.parse(row.tool_key_json), row.operation);
+		if (!grant) throw new AgentToolPermissionError("grant_conflict");
+		const ticketId = `act_${crypto.randomUUID()}`;
+		this.db.query(`INSERT INTO agent_tool_action_tickets (id, origin_decision_id, agent_id, incarnation, authority_epoch, args_digest, target_digest, state, revision)
+			VALUES (?, ?, ?, ?, ?, ?, ?, 'unused', 1)`).run(ticketId, decisionId, row.agent_id, row.incarnation, view.authority_epoch, row.args_digest, sha256(row.scope_json));
+		const invocationId = crypto.randomUUID();
+		this.db.query(`INSERT INTO agent_tool_invocations (id, request_id, agent_id, incarnation, logical_operation_key, tool_key_json,
+			args_json, args_digest, target_identity_json, authority_source, authority_ref, grant_id, grant_revision, policy_revision,
+			authority_epoch, action_ticket_id, state, revision) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'action_ticket', ?, ?, ?, ?, ?, ?, 'ready', 1)`).run(
+			invocationId, row.id, row.agent_id, row.incarnation, `request:${row.id}`, row.tool_key_json, row.args_json, row.args_digest,
+			row.scope_json, ticketId, grant.id, grant.revision, view.policy_revision, view.authority_epoch, ticketId);
+		return { grantId: grant.id, invocationId };
+	}
+
+	/** What the delivery carries to the session for an action execution: the stored args and the ticket id; null for other executions. */
+	actionCarry(invocationId: string): { args: unknown; ticket: string } | null {
+		const row = this.db.query<{ args_json: string; action_ticket_id: string | null }, [string]>(
+			"SELECT args_json, action_ticket_id FROM agent_tool_invocations WHERE id = ?").get(invocationId);
+		return row?.action_ticket_id ? { args: JSON.parse(row.args_json), ticket: row.action_ticket_id } : null;
+	}
+
+	mode(agentId: string): "legacy" | "managed" {
+		return this.db.query<{ mode: "legacy" | "managed" }, [string]>("SELECT mode FROM agent_permission_epochs WHERE agent_id = ?").get(agentId)?.mode ?? "legacy";
+	}
+
+	/** A new agent, clone or new-id restore: managed with zero grants from the start (C9). Never called for an existing id. */
+	startManaged(agentId: string): void {
+		this.db.transaction(() => {
+			this.epochs(agentId);
+			this.db.query("UPDATE agent_permission_epochs SET mode = 'managed' WHERE agent_id = ?").run(agentId);
+		}).immediate();
+	}
+
+	/** The open (not cancelled) migration card of the agent's current lifecycle, or null. */
+	currentMigration(agentId: string): AgentToolMigrationCard | null {
+		const row = this.db.query<{ decision_id: string; agent_id: string; incarnation: number; proposal_digest: string; items_json: string; state: AgentToolMigrationCard["state"] }, [string, number]>(
+			`SELECT decision_id, agent_id, incarnation, proposal_digest, items_json, state FROM agent_tool_migrations
+			WHERE agent_id = ? AND incarnation = ? AND state != 'cancelled' ORDER BY created_at DESC, rowid DESC LIMIT 1`,
+		).get(agentId, lifecycleEpoch(this.db, agentId));
+		if (!row) return null;
+		return { decisionId: row.decision_id, agentId: row.agent_id, incarnation: row.incarnation, proposalDigest: row.proposal_digest,
+			items: JSON.parse(row.items_json), state: row.state };
+	}
+
+	/** The card payload and its digest, which binds agent, lifecycle and every listed scope. */
+	migrationProposal(agentId: string, items: readonly LegacyScopeItem[]): { incarnation: number; proposalDigest: string; payload: Record<string, unknown> } {
+		const incarnation = lifecycleEpoch(this.db, agentId);
+		const proposalDigest = sha256(canonicalJson({ purpose: "agent_tool_migration", agentId, incarnation, items }));
+		return { incarnation, proposalDigest, payload: { purpose: "agent_tool_migration", agentId, items, proposalDigest } };
+	}
+
+	insertMigration(agentId: string, convId: string, items: readonly LegacyScopeItem[], proposal: ReturnType<AgentToolPermissionStore["migrationProposal"]>, decisionId: string): AgentToolMigrationCard {
+		this.db.query("INSERT INTO decision_purposes (decision_id, purpose) VALUES (?, 'agent_tool_migration')").run(decisionId);
+		this.db.query("UPDATE decisions SET reason = 'agent_tool_migration' WHERE id = ?").run(decisionId);
+		const now = new Date().toISOString();
+		this.db.query(`INSERT INTO agent_tool_migrations (id, agent_id, incarnation, conv_id, decision_id, items_json, proposal_digest, state, revision, created_at, updated_at)
+			VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 1, ?, ?)`).run(crypto.randomUUID(), agentId, proposal.incarnation, convId, decisionId,
+			JSON.stringify(items), proposal.proposalDigest, now, now);
+		return this.currentMigration(agentId)!;
+	}
+
+	/**
+	 * The owner answer to a migration card, in the caller's transaction. Every listed scope needs its own allow or deny;
+	 * only allowed scopes become grants (with their exact resources). The mode stays legacy: the running turn finishes with
+	 * its legacy scope, and applyMigrationAtIdle switches at the next idle boundary. A cancel keeps legacy and grants nothing.
+	 */
+	private answerMigration(decisionId: string, answer: AgentToolGrantAnswer): AnswerResult {
+		const row = this.db.query<{ id: string; agent_id: string; incarnation: number; items_json: string; proposal_digest: string; state: string }, [string]>(
+			"SELECT id, agent_id, incarnation, items_json, proposal_digest, state FROM agent_tool_migrations WHERE decision_id = ?").get(decisionId);
+		if (!row) throw new AgentToolPermissionError("tool_request_not_found");
+		if (row.state !== "pending") throw new AgentToolPermissionError("tool_request_conflict");
+		const response = answer.response;
+		if ("toolGrant" in response) throw new AgentToolPermissionError("tool_request_invalid");
+		const now = new Date().toISOString();
+		if (!("toolMigration" in response)) {
+			this.db.query("UPDATE agent_tool_migrations SET state = 'cancelled', revision = revision + 1, updated_at = ? WHERE id = ?").run(now, row.id);
+			return { outcome: "cancelled", grantId: null, invocationId: null };
+		}
+		if (response.toolMigration.proposalDigest !== row.proposal_digest) throw new AgentToolPermissionError("proposal_digest_mismatch");
+		const items = JSON.parse(row.items_json) as LegacyScopeItem[];
+		const choices = response.toolMigration.items;
+		if (Object.keys(choices).length !== items.length || !items.every((item) => choices[item.id] === "allow" || choices[item.id] === "deny")) {
+			throw new AgentToolPermissionError("tool_request_invalid");
+		}
+		const allowed = items.filter((item) => choices[item.id] === "allow");
+		if (allowed.length > 0 && lifecycleEpoch(this.db, row.agent_id) !== row.incarnation) throw new AgentToolPermissionError("lifecycle_epoch_mismatch");
+		const view = this.epochs(row.agent_id);
+		for (const item of allowed) {
+			for (const grant of item.grants) {
+				this.db.query(`INSERT INTO agent_tool_grants (id, agent_id, incarnation, authority_epoch, tool_key_json, operations_json,
+					scope_json, origin_decision_id, origin_submission_id, state, revision, created_at, updated_at, resources_json)
+					VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', 1, ?, ?, ?)`).run(crypto.randomUUID(), row.agent_id, row.incarnation, view.authority_epoch,
+					canonicalJson(grant.toolKey), JSON.stringify(grant.operations), canonicalJson({ migration: item.id, resources: grant.resources }),
+					decisionId, answer.submissionId, now, now, JSON.stringify(grant.resources));
+			}
+		}
+		if (allowed.length > 0) {
+			this.db.query("UPDATE agent_permission_epochs SET policy_revision = policy_revision + 1 WHERE agent_id = ?").run(row.agent_id);
+			this.db.query("UPDATE agent_tool_session_policy SET desired_revision = ? WHERE agent_id = ?").run(this.epochs(row.agent_id).policy_revision, row.agent_id);
+		}
+		this.db.query("UPDATE agent_tool_migrations SET state = ?, choices_json = ?, revision = revision + 1, updated_at = ? WHERE id = ?")
+			.run(allowed.length > 0 ? "confirmed" : "declined", canonicalJson(choices), now, row.id);
+		return { outcome: allowed.length > 0 ? "allowed" : "denied", grantId: null, invocationId: null };
+	}
+
+	/** At an idle boundary: an answered (confirmed or declined) card switches the agent to managed. True when it switched. */
+	applyMigrationAtIdle(agentId: string): boolean {
+		return this.db.transaction(() => {
+			const row = this.db.query<{ id: string }, [string]>(
+				"SELECT id FROM agent_tool_migrations WHERE agent_id = ? AND state IN ('confirmed','declined') ORDER BY created_at DESC, rowid DESC LIMIT 1").get(agentId);
+			if (!row) return false;
+			// answerMigration created the epochs row when it recorded the answer.
+			this.db.query("UPDATE agent_permission_epochs SET mode = 'managed' WHERE agent_id = ?").run(agentId);
+			this.db.query("UPDATE agent_tool_migrations SET state = 'applied', revision = revision + 1, updated_at = ? WHERE id = ?").run(new Date().toISOString(), row.id);
+			return true;
+		}).immediate();
+	}
+
+	grant(id: string): AgentToolGrantRow | null {
+		const row = this.db.query<GrantRow, [string]>("SELECT * FROM agent_tool_grants WHERE id = ?").get(id);
+		return row ? grantRecord(row) : null;
+	}
+
+	grants(agentId: string): AgentToolGrantRow[] {
+		return this.db.query<GrantRow, [string]>("SELECT * FROM agent_tool_grants WHERE agent_id = ? ORDER BY created_at, id").all(agentId).map(grantRecord);
+	}
+
+	invocation(id: string): AgentToolInvocation | null {
+		const row = this.db.query<InvocationRow, [string]>("SELECT * FROM agent_tool_invocations WHERE id = ?").get(id);
+		return row ? invocationRecord(row) : null;
+	}
+
+	invocationByRequest(requestId: string): AgentToolInvocation | null {
+		const row = this.db.query<InvocationRow, [string]>("SELECT * FROM agent_tool_invocations WHERE request_id = ?").get(requestId);
+		return row ? invocationRecord(row) : null;
+	}
+
+	/** The access view and every active grant of the agent: a full read, never a page (the engine policy must be complete). */
+	policyGrants(agentId: string): { view: AgentAccessView; grants: AgentToolGrantRow[] } {
+		return this.db.transaction(() => ({
+			view: access(this.db, agentId),
+			grants: this.db.query<GrantRow, [string]>("SELECT * FROM agent_tool_grants WHERE agent_id = ? AND state = 'active' ORDER BY created_at, id").all(agentId).map(grantRecord),
+		}))();
+	}
+
+	/** The engine revision of the current policy. The engine requires >= 1, so no change yet is revision 1 on both sides. */
+	private currentRevision(agentId: string): number {
+		return Math.max(access(this.db, agentId).policyRevision, 1);
+	}
+
+	/**
+	 * Persists the engine's ACK of the current policy revision for one durable session (agent_tool_session_policy, created by
+	 * migrate). Another revision is policy_conflict: an ACK of an older policy never authorizes a start.
+	 */
+	ackPolicy(durableSessionId: string, agentId: string, revision: number): { revision: number } {
+		return this.db.transaction(() => {
+			const current = this.currentRevision(agentId);
+			if (!durableSessionId || revision !== current) throw new AgentToolPermissionError("policy_conflict");
+			this.db.query(`INSERT INTO agent_tool_session_policy (durable_session_id, agent_id, incarnation, executor_generation, desired_revision, applied_revision, status)
+				VALUES (?, ?, ?, 0, ?, ?, 'applied') ON CONFLICT(durable_session_id) DO UPDATE SET agent_id = excluded.agent_id, incarnation = excluded.incarnation,
+				desired_revision = excluded.desired_revision, applied_revision = excluded.applied_revision, status = 'applied'`)
+				.run(durableSessionId, agentId, lifecycleEpoch(this.db, agentId), current, revision);
+			return { revision };
+		}).immediate();
+	}
+
+	appliedRevision(durableSessionId: string, agentId: string): number | null {
+		return this.db.query<{ applied_revision: number | null }, [string, string]>(
+			"SELECT applied_revision FROM agent_tool_session_policy WHERE durable_session_id = ? AND agent_id = ?").get(durableSessionId, agentId)?.applied_revision ?? null;
+	}
+
+	/** Where a granted execution is delivered. The operation id is the engine's held operation (the request's logical call). */
+	deliveryTarget(invocationId: string): { invocationId: string; operationId: string; agentId: string; convId: string; durableSessionId: string; collaboration: boolean } | null {
+		const row = this.db.query<{ logical_call_id: string; agent_id: string; conv_id: string; durable_session_id: string; collaboration_request_id: string | null }, [string]>(
+			`SELECT r.logical_call_id, r.agent_id, r.conv_id, r.durable_session_id, r.collaboration_request_id
+			FROM agent_tool_invocations i JOIN agent_tool_requests r ON r.id = i.request_id WHERE i.id = ?`).get(invocationId);
+		return row ? { invocationId, operationId: row.logical_call_id, agentId: row.agent_id, convId: row.conv_id,
+			durableSessionId: row.durable_session_id, collaboration: row.collaboration_request_id !== null } : null;
+	}
+
+	/**
+	 * Owner-only executions of a conversation still owed a delivery, oldest first: ready rows, reservations of a generation
+	 * that is not live in this process (reserve takes them over), and stored results whose continuation is still queued
+	 * (C5: only the stored result is delivered again; nothing re-runs). Delivered when the conversation's session opens.
+	 */
+	readyInvocations(convId: string): string[] {
+		return this.db.query<{ id: string; state: InvocationState; executor_generation: number }, [string]>(
+			`SELECT i.id, i.state, i.executor_generation FROM agent_tool_invocations i JOIN agent_tool_requests r ON r.id = i.request_id
+			LEFT JOIN agent_tool_continuations c ON c.invocation_id = i.id
+			WHERE r.conv_id = ? AND r.collaboration_request_id IS NULL
+			AND (i.state IN ('ready','reserved') OR (i.state IN ('succeeded','failed') AND c.state = 'queued')) ORDER BY i.rowid`).all(convId)
+			.filter((row) => row.state !== "reserved" || !this.liveGenerations.has(row.executor_generation)).map((row) => row.id);
+	}
+
+	/** Owner-only executions of a conversation a generation that is not live in this process started without a result (C5: unknown). */
+	staleStarted(convId: string): string[] {
+		return this.db.query<{ id: string; executor_generation: number }, [string]>(
+			`SELECT i.id, i.executor_generation FROM agent_tool_invocations i JOIN agent_tool_requests r ON r.id = i.request_id
+			WHERE r.conv_id = ? AND r.collaboration_request_id IS NULL AND i.state = 'started' ORDER BY i.rowid`).all(convId)
+			.filter((row) => !this.liveGenerations.has(row.executor_generation)).map((row) => row.id);
+	}
+
+	/** C4 queued -> continued: the engine accepted the continuation (or already had it). Persisted, so a restart never re-delivers it. */
+	continued(continuationId: string): boolean {
+		return this.db.query("UPDATE agent_tool_continuations SET state = 'continued', revision = revision + 1 WHERE id = ? AND state = 'queued'")
+			.run(continuationId).changes === 1;
+	}
+
+	/** C5: a started execution whose result cannot be proven becomes outcome_unknown; it is never run or offered again. */
+	markOutcomeUnknown(invocationId: string): boolean {
+		return this.db.query("UPDATE agent_tool_invocations SET state = 'outcome_unknown', revision = revision + 1, settled_at = ? WHERE id = ? AND state = 'started'")
+			.run(new Date().toISOString(), invocationId).changes === 1;
+	}
+
+	/** Same operation id and body returns the stored result; another body is 409. */
+	private operation<T>(operationId: string, agentId: string, kind: string, request: unknown, run: () => T): T {
+		if (!UUID.test(operationId)) throw new AgentToolPermissionError("tool_request_invalid");
+		const previous = this.db.query<{ agent_id: string; kind: string; request_json: string; result_json: string }, [string]>(
+			"SELECT agent_id, kind, request_json, result_json FROM agent_tool_operations WHERE operation_id = ?").get(operationId);
+		if (previous) {
+			if (previous.agent_id !== agentId || previous.kind !== kind || previous.request_json !== canonicalJson(request)) {
+				throw new AgentToolPermissionError("operation_conflict");
+			}
+			return JSON.parse(previous.result_json) as T;
+		}
+		const result = run();
+		this.db.query("INSERT INTO agent_tool_operations VALUES (?, ?, ?, ?, ?, ?)")
+			.run(operationId, agentId, kind, canonicalJson(request), JSON.stringify(result), new Date().toISOString());
+		return result;
+	}
+
+	/** Cancels unstarted executions of the grants; returns started ones, which keep running until their result or abort ACK. */
+	private stopExecutions(where: string, ...values: string[]): { cancelled: string[]; running: string[] } {
+		const rows = this.db.query<{ id: string; state: InvocationState }, string[]>(
+			`SELECT id, state FROM agent_tool_invocations WHERE ${where} AND state IN ('ready','reserved','started') ORDER BY id`).all(...values);
+		const cancelled = rows.filter((row) => row.state !== "started").map((row) => row.id);
+		for (const id of cancelled) {
+			this.db.query("UPDATE agent_tool_invocations SET state = 'cancelled', revision = revision + 1, settled_at = ? WHERE id = ?")
+				.run(new Date().toISOString(), id);
+		}
+		return { cancelled, running: rows.filter((row) => row.state === "started").map((row) => row.id) };
+	}
+
+	revokeGrant(agentId: string, grantId: string, input: { operationId: string; expectedRevision: number }, principal: OwnerPrincipal):
+		{ grant: AgentToolGrantRow; policyRevision: number; cancelled: string[]; running: string[] } {
+		void principal;
+		return this.db.transaction(() => this.operation(input.operationId, agentId, "revoke", { grantId, expectedRevision: input.expectedRevision }, () => {
+			const grant = this.grant(grantId);
+			if (!grant || grant.agentId !== agentId) throw new AgentToolPermissionError("grant_not_found");
+			if (grant.revision !== input.expectedRevision || grant.state === "revoked") throw new AgentToolPermissionError("grant_conflict");
+			const now = new Date().toISOString();
+			this.db.query("UPDATE agent_tool_grants SET state = 'revoked', revision = revision + 1, revoked_at = ?, updated_at = ?, reason = 'owner_revoke' WHERE id = ?")
+				.run(now, now, grantId);
+			const policyRevision = this.bumpPolicy(agentId);
+			const stopped = this.stopExecutions("grant_id = ?", grantId);
+			this.supersedeEdits("grant_id = ?", grantId);
+			return { grant: this.grant(grantId)!, policyRevision, ...stopped };
+		})).immediate();
+	}
+
+	/**
+	 * C10 revoke-all: blocks access, raises authority epoch and policy revision, revokes every persistent grant, cancels
+	 * unstarted executions and pending requests (closing their inbox cards). Started executions are returned as running.
+	 */
+	revokeAll(agentId: string, input: { operationId: string; expectedPolicyRevision: number }, principal: OwnerPrincipal):
+		{ view: AgentAccessView; revokedGrants: string[]; cancelled: string[]; running: string[]; closedDecisions: string[] } {
+		void principal;
+		return this.db.transaction(() => this.operation(input.operationId, agentId, "revoke_all", { expectedPolicyRevision: input.expectedPolicyRevision }, () => {
+			const before = this.epochs(agentId);
+			if (before.policy_revision !== input.expectedPolicyRevision) throw new AgentToolPermissionError("policy_conflict");
+			const now = new Date().toISOString();
+			const revokedGrants = this.db.query<{ id: string }, [string]>("SELECT id FROM agent_tool_grants WHERE agent_id = ? AND state != 'revoked' ORDER BY id")
+				.all(agentId).map((row) => row.id);
+			this.db.query("UPDATE agent_tool_grants SET state = 'revoked', revision = revision + 1, revoked_at = ?, updated_at = ?, reason = 'revoke_all' WHERE agent_id = ? AND state != 'revoked'")
+				.run(now, now, agentId);
+			this.db.query("UPDATE agent_permission_epochs SET access_state = 'blocked', authority_epoch = authority_epoch + 1 WHERE agent_id = ?").run(agentId);
+			this.bumpPolicy(agentId);
+			const stopped = this.stopExecutions("agent_id = ?", agentId);
+			const pending = this.db.query<{ id: string; decision_id: string }, [string]>(
+				"SELECT id, decision_id FROM agent_tool_requests WHERE agent_id = ? AND state = 'pending' ORDER BY id").all(agentId);
+			for (const request of pending) {
+				this.db.query("UPDATE agent_tool_requests SET state = 'cancelled', revision = revision + 1 WHERE id = ?").run(request.id);
+				this.db.query(`UPDATE decisions SET status = 'closed', reason = 'agent_access_revoked', revision = revision + 1, updated_at = ?
+					WHERE id = ? AND status IN ('pending','needs_review')`).run(now, request.decision_id);
+			}
+			const closedEdits = this.supersedeEdits("agent_id = ?", agentId);
+			return { view: access(this.db, agentId), revokedGrants, ...stopped, closedDecisions: [...pending.map((request) => request.decision_id), ...closedEdits] };
+		})).immediate();
+	}
+
+	/**
+	 * C3/C8 grant scope edit, in the caller's (Store) transaction. The server classifies the complete post-edit values:
+	 * a narrowing applies at once (C5); a widening opens an agent_tool_grant inbox card through `createDecision` and the
+	 * old grant stays valid and unchanged until the card is answered. Same operation id and payload replays the response.
+	 */
+	editGrant(agentId: string, grantId: string, input: GrantEditInput, principal: OwnerPrincipal,
+		createDecision: (ownerConv: string, sourceRequestId: string, payload: Record<string, unknown>) => string): GrantEditResult {
+		void principal;
+		const operations = [...new Set(input.operations)].sort();
+		const request = { grantId, expectedRevision: input.expectedRevision, operations, scope: input.scope };
+		return this.operation(input.operationId, agentId, "edit", request, (): GrantEditResult => {
+			const grant = this.grant(grantId);
+			if (!grant || grant.agentId !== agentId) throw new AgentToolPermissionError("grant_not_found");
+			const view = this.epochs(agentId);
+			if (view.access_state === "blocked") throw new AgentToolPermissionError("agent_access_blocked", 409);
+			if (grant.state !== "active" || grant.revision !== input.expectedRevision) throw new AgentToolPermissionError("grant_conflict");
+			if (grant.authorityEpoch !== view.authority_epoch || grant.incarnation !== lifecycleEpoch(this.db, agentId)) throw new AgentToolPermissionError("policy_conflict");
+			const was = record(grant.scope) ? grant.scope : {};
+			if (OPAQUE_SCOPE_KEYS.some((key) => Object.hasOwn(was, key) !== Object.hasOwn(input.scope, key) || canonicalJson(was[key]) !== canonicalJson(input.scope[key]))) {
+				throw new AgentToolPermissionError("tool_request_invalid");
+			}
+			approvedResources(input.scope);
+			const kind = classifyGrantEdit(grant, { operations, scope: input.scope });
+			if (kind === "same") return { status: 200, body: { grant, policyRevision: view.policy_revision, cancelled: [], running: [] } };
+			this.supersedeEdits("grant_id = ?", grantId);
+			if (kind === "narrow") return { status: 200, body: this.applyGrantScope(grant, operations, input.scope) };
+			const proposalDigest = sha256(canonicalJson({
+				purpose: "agent_tool_grant_edit", agentId, incarnation: grant.incarnation, authorityEpoch: view.authority_epoch, grantId,
+				baseRevision: grant.revision, toolKey: grant.toolKey, operations, scope: input.scope,
+			}));
+			const ownerConv = this.db.query<{ owner_conv: string }, [string]>("SELECT owner_conv FROM decisions WHERE id = ?").get(grant.originDecisionId)?.owner_conv ?? "main";
+			const decisionId = createDecision(ownerConv, `agent-tool-edit:${grantId}:${input.operationId}`, {
+				purpose: "agent_tool_grant", agentId, toolKey: grant.toolKey, operation: operations[0], operations, scope: input.scope, proposalDigest,
+				originKind: "user", edit: { grantId, baseRevision: grant.revision, operations: grant.operations, scope: grant.scope },
+			});
+			this.db.query("INSERT INTO decision_purposes (decision_id, purpose) VALUES (?, 'agent_tool_grant')").run(decisionId);
+			this.db.query("UPDATE decisions SET reason = 'agent_tool_permission' WHERE id = ?").run(decisionId);
+			const now = new Date().toISOString();
+			this.db.query(`INSERT INTO agent_tool_grant_edits (decision_id, grant_id, agent_id, base_revision, operations_json, scope_json, proposal_digest, state, created_at, updated_at)
+				VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)`).run(decisionId, grantId, agentId, grant.revision, JSON.stringify(operations), canonicalJson(input.scope), proposalDigest, now, now);
+			return { status: 202, body: { decisionId, proposalDigest, oldGrant: grant } };
+		});
+	}
+
+	/**
+	 * Replaces the grant's operations, scope and resources (revision +1, policy revision bump). Unstarted executions still
+	 * inside the new scope move to the new revision; the others are cancelled. Started ones outside it keep running (C5).
+	 */
+	private applyGrantScope(grant: AgentToolGrantRow, operations: readonly string[], scope: unknown):
+		{ grant: AgentToolGrantRow; policyRevision: number; cancelled: string[]; running: string[] } {
+		const now = new Date().toISOString();
+		this.db.query("UPDATE agent_tool_grants SET operations_json = ?, scope_json = ?, resources_json = ?, revision = revision + 1, updated_at = ? WHERE id = ?")
+			.run(JSON.stringify(operations), canonicalJson(scope), resourcesJson(scope), now, grant.id);
+		const policyRevision = this.bumpPolicy(grant.agentId);
+		const updated = this.grant(grant.id)!;
+		const rows = this.db.query<{ id: string; state: InvocationState; operation: string | null; target_identity_json: string }, [string]>(
+			`SELECT i.id, i.state, r.operation, i.target_identity_json FROM agent_tool_invocations i LEFT JOIN agent_tool_requests r ON r.id = i.request_id
+			WHERE i.grant_id = ? AND i.state IN ('ready','reserved','started') ORDER BY i.id`).all(grant.id);
+		const cancelled: string[] = [];
+		const running: string[] = [];
+		for (const row of rows) {
+			const inside = row.operation !== null &&
+				classifyGrantEdit({ operations, scope }, { operations: [row.operation], scope: JSON.parse(row.target_identity_json) }) !== "widen";
+			if (row.state === "started") {
+				if (!inside) running.push(row.id);
+			} else if (inside) {
+				this.db.query("UPDATE agent_tool_invocations SET grant_revision = ?, policy_revision = ?, revision = revision + 1 WHERE id = ?").run(updated.revision, policyRevision, row.id);
+			} else {
+				this.db.query("UPDATE agent_tool_invocations SET state = 'cancelled', revision = revision + 1, settled_at = ? WHERE id = ?").run(now, row.id);
+				cancelled.push(row.id);
+			}
+		}
+		return { grant: updated, policyRevision, cancelled, running };
+	}
+
+	/** The owner answer to a widening card: deny or cancel changes nothing; allow applies the stored scope if the grant is unchanged. */
+	private answerEdit(edit: EditRow, answer: AgentToolGrantAnswer): AnswerResult {
+		if (edit.state !== "pending") throw new AgentToolPermissionError("tool_request_conflict");
+		const response = answer.response;
+		if ("toolMigration" in response) throw new AgentToolPermissionError("tool_request_invalid");
+		let outcome: AnswerResult["outcome"] = "cancelled";
+		if ("toolGrant" in response) {
+			if (response.toolGrant.proposalDigest !== edit.proposal_digest) throw new AgentToolPermissionError("proposal_digest_mismatch");
+			outcome = response.toolGrant.choice === "allow" ? "allowed" : "denied";
+		}
+		const setState = () => this.db.query("UPDATE agent_tool_grant_edits SET state = ?, updated_at = ? WHERE decision_id = ?")
+			.run(outcome, new Date().toISOString(), edit.decision_id);
+		if (outcome !== "allowed") {
+			setState();
+			return { outcome, grantId: null, invocationId: null };
+		}
+		// editGrant stored this row for an existing grant, and grant rows are never deleted (revoke only changes state).
+		const grant = this.grant(edit.grant_id)!;
+		const view = this.epochs(edit.agent_id);
+		if (grant.state !== "active" || grant.revision !== edit.base_revision || view.access_state === "blocked" ||
+			grant.authorityEpoch !== view.authority_epoch || grant.incarnation !== lifecycleEpoch(this.db, edit.agent_id)) {
+			throw new AgentToolPermissionError("grant_conflict");
+		}
+		this.applyGrantScope(grant, JSON.parse(edit.operations_json), JSON.parse(edit.scope_json));
+		setState();
+		return { outcome: "allowed", grantId: grant.id, invocationId: null };
+	}
+
+	/** Closes the pending widening cards the condition matches (the grant changed or was revoked); returns their decision ids. */
+	private supersedeEdits(where: string, value: string): string[] {
+		const ids = this.db.query<{ decision_id: string }, [string]>(
+			`SELECT decision_id FROM agent_tool_grant_edits WHERE ${where} AND state = 'pending' ORDER BY decision_id`).all(value).map((row) => row.decision_id);
+		const now = new Date().toISOString();
+		for (const id of ids) {
+			this.db.query("UPDATE agent_tool_grant_edits SET state = 'superseded', updated_at = ? WHERE decision_id = ?").run(now, id);
+			this.db.query(`UPDATE decisions SET status = 'closed', reason = 'agent_tool_edit_superseded', revision = revision + 1, updated_at = ?
+				WHERE id = ? AND status IN ('pending','needs_review')`).run(now, id);
+		}
+		return ids;
+	}
+
+	/** The event data for the agent's current policy. */
+	policyEvent(agentId: string): PolicyUpdatedData {
+		return policyUpdatedData(access(this.db, agentId));
+	}
+
+	/** After a widening card was answered (allow, deny or cancel): the agent's policy event data; otherwise null. */
+	answeredEditPolicy(decisionId: string): PolicyUpdatedData | null {
+		const row = this.db.query<{ agent_id: string }, [string]>(
+			"SELECT agent_id FROM agent_tool_grant_edits WHERE decision_id = ? AND state IN ('allowed','denied','cancelled')").get(decisionId);
+		return row ? this.policyEvent(row.agent_id) : null;
+	}
+
+	/**
+	 * One executor takes the execution. Not yet permission to run: start re-checks everything. A cancelled row is returned
+	 * unchanged (a revoke that committed first wins; start reports it). C5 recovery: a reservation of a generation that is not
+	 * live in this process never started (start is its own durable transition), so this generation takes it over; the start
+	 * CAS still fences on the generation, so the old executor can never start it and the call runs at most once.
+	 */
+	reserve(invocationId: string, executorGeneration: number): AgentToolInvocation {
+		return this.db.transaction(() => {
+			const current = this.invocation(invocationId);
+			if (!current) throw new AgentToolPermissionError("invocation_not_found");
+			if (!Number.isSafeInteger(executorGeneration) || executorGeneration < 1) throw new AgentToolPermissionError("invocation_conflict");
+			if (current.state === "cancelled") return current;
+			if (current.state === "reserved" && current.executorGeneration === executorGeneration) {
+				this.liveGenerations.add(executorGeneration);
+				return current;
+			}
+			const takeover = current.state === "reserved" && !this.liveGenerations.has(current.executorGeneration);
+			if (current.state !== "ready" && !takeover) throw new AgentToolPermissionError("invocation_conflict");
+			this.db.query("UPDATE agent_tool_invocations SET state = 'reserved', executor_generation = ?, revision = revision + 1 WHERE id = ? AND state = ? AND executor_generation = ?")
+				.run(executorGeneration, invocationId, current.state, current.executorGeneration);
+			this.liveGenerations.add(executorGeneration);
+			return this.invocation(invocationId)!;
+		}).immediate();
+	}
+
+	/**
+	 * Start CAS. Access, authority epoch, lifecycle and the exact grant revision are re-checked in the same transaction a
+	 * revoke uses, so whichever commits first wins: revoke first means zero executions.
+	 */
+	start(invocationId: string, executorGeneration: number, ack?: { readonly durableSessionId: string }): { readonly state: "started" } | { readonly state: "cancelled"; readonly reason: string } {
+		return this.db.transaction(() => {
+			const current = this.invocation(invocationId);
+			if (!current) throw new AgentToolPermissionError("invocation_not_found");
+			// A revoke that committed first wins over every other check, including the stale session ACK it caused (C5).
+			if (current.state === "cancelled") return { state: "cancelled" as const, reason: "cancelled" };
+			// With an ACK requirement the session must have applied the current revision, checked in the start transaction.
+			if (ack && this.appliedRevision(ack.durableSessionId, current.agentId) !== this.currentRevision(current.agentId)) {
+				throw new AgentToolPermissionError("policy_conflict");
+			}
+			if (current.state === "started" && current.executorGeneration === executorGeneration) return { state: "started" as const };
+			if (current.state !== "reserved" || current.executorGeneration !== executorGeneration) throw new AgentToolPermissionError("invocation_conflict");
+			const view = access(this.db, current.agentId);
+			const grant = current.grantId ? this.grant(current.grantId) : null;
+			const reason = view.accessState === "blocked" ? "agent_access_blocked"
+				: view.authorityEpoch !== current.authorityEpoch ? "authority_epoch_mismatch"
+					: view.lifecycleEpoch !== current.incarnation ? "lifecycle_epoch_mismatch"
+						: !grant || grant.state !== "active" || grant.revision !== current.grantRevision ? "grant_not_active" : null;
+			const now = new Date().toISOString();
+			if (reason || !this.consumeActionTicket(invocationId, current)) {
+				this.db.query("UPDATE agent_tool_invocations SET state = 'cancelled', revision = revision + 1, settled_at = ? WHERE id = ?").run(now, invocationId);
+				return { state: "cancelled" as const, reason: reason ?? "action_ticket_required" };
+			}
+			this.db.query("UPDATE agent_tool_invocations SET state = 'started', revision = revision + 1, started_at = ? WHERE id = ?").run(now, invocationId);
+			return { state: "started" as const };
+		}).immediate();
+	}
+
+	/**
+	 * C8, inside the start transaction: an execution without a ticket passes; an action execution passes only by consuming its
+	 * own unused ticket of the same agent, lifecycle and authority epoch. A used, revoked or foreign ticket refuses the start.
+	 */
+	private consumeActionTicket(invocationId: string, current: AgentToolInvocation): boolean {
+		const ticketId = this.db.query<{ action_ticket_id: string | null }, [string]>("SELECT action_ticket_id FROM agent_tool_invocations WHERE id = ?").get(invocationId)?.action_ticket_id;
+		if (!ticketId) return true;
+		return this.db.query(`UPDATE agent_tool_action_tickets SET state = 'consumed', invocation_id = ?, revision = revision + 1
+			WHERE id = ? AND state = 'unused' AND invocation_id IS NULL AND agent_id = ? AND incarnation = ? AND authority_epoch = ?`)
+			.run(invocationId, ticketId, current.agentId, current.incarnation, current.authorityEpoch).changes === 1;
+	}
+
+	/** Records the owned result once and the resume intent (queued continuation) in the same transaction. */
+	result(invocationId: string, executorGeneration: number, outcome: { state: "succeeded" | "failed" | "outcome_unknown"; resultRef: string }):
+		{ invocation: AgentToolInvocation; continuationId: string } {
+		return this.db.transaction(() => {
+			const current = this.invocation(invocationId);
+			if (!current) throw new AgentToolPermissionError("invocation_not_found");
+			const continuation = () => this.db.query<{ id: string }, [string]>("SELECT id FROM agent_tool_continuations WHERE invocation_id = ?").get(invocationId);
+			if (current.state === outcome.state && current.resultRef === outcome.resultRef && current.executorGeneration === executorGeneration) {
+				return { invocation: current, continuationId: continuation()!.id };
+			}
+			if (current.state !== "started" || current.executorGeneration !== executorGeneration) throw new AgentToolPermissionError("invocation_conflict");
+			this.db.query("UPDATE agent_tool_invocations SET state = ?, result_ref = ?, revision = revision + 1, settled_at = ? WHERE id = ?")
+				.run(outcome.state, outcome.resultRef, new Date().toISOString(), invocationId);
+			const request = current.requestId ? this.requestRow("id = ?", current.requestId) : null;
+			if (!request) throw new AgentToolPermissionError("tool_request_not_found");
+			const id = crypto.randomUUID();
+			this.db.query(`INSERT INTO agent_tool_continuations (id, invocation_id, conv_id, origin_input_seq, durable_session_id, state, revision)
+				VALUES (?, ?, ?, ?, ?, 'queued', 1)`).run(id, invocationId, request.conv_id, request.origin_input_seq, request.durable_session_id);
+			return { invocation: this.invocation(invocationId)!, continuationId: id };
+		}).immediate();
+	}
+
+	/** GET /api/agents/:id/tool-permissions page: 50 grants per page, cursor bound to agent and policy revision. */
+	list(agentId: string, cursor: string | null): { items: AgentToolGrantRow[]; pending: AgentToolRequestRecord[]; policy: AgentAccessView; nextCursor: string | null } {
+		return this.db.transaction(() => {
+			const policy = access(this.db, agentId);
+			let offset = 0;
+			if (cursor !== null) {
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+				} catch {
+					throw new AgentToolPermissionError("cursor_invalid");
+				}
+				if (!record(parsed) || parsed.agentId !== agentId || typeof parsed.offset !== "number" || !Number.isSafeInteger(parsed.offset) || parsed.offset < 0) {
+					throw new AgentToolPermissionError("cursor_invalid");
+				}
+				if (parsed.policyRevision !== policy.policyRevision) throw new AgentToolPermissionError("cursor_stale");
+				offset = parsed.offset;
+			}
+			const rows = this.db.query<GrantRow, [string, number, number]>(
+				"SELECT * FROM agent_tool_grants WHERE agent_id = ? AND state != 'revoked' ORDER BY created_at, id LIMIT ? OFFSET ?",
+			).all(agentId, PAGE + 1, offset);
+			const items = rows.slice(0, PAGE).map(grantRecord);
+			const nextCursor = rows.length > PAGE
+				? Buffer.from(JSON.stringify({ agentId, policyRevision: policy.policyRevision, offset: offset + PAGE })).toString("base64url") : null;
+			const pending = this.db.query<RequestRow, [string]>("SELECT * FROM agent_tool_requests WHERE agent_id = ? AND state = 'pending' ORDER BY id")
+				.all(agentId).map(requestRecord);
+			return { items, pending, policy, nextCursor };
+		})();
+	}
+}
+
+/** Where the request came in: the trusted (web) listener, or the app port with its gated device. */
+export interface AgentToolRequestContext {
+	readonly trusted: boolean;
+	readonly device: DeviceRecord | null;
+}
+
+export interface AgentToolClientDeps {
+	readonly webOrigins: readonly string[];
+	/** Random per gateway process; a restart invalidates every web client session. */
+	readonly generation: string;
+	/** The current device row (existing Store device registry). */
+	readonly currentDevice: (id: string) => DeviceRecord | null;
+	/** Existing device credential revision (src/attachments/service.ts deviceRevision). */
+	readonly deviceRevision: (device: DeviceRecord) => string;
+}
+
+export const AGENT_TOOL_COOKIE = "zigmini_agent_tool";
+export const AGENT_TOOL_CLIENT_HEADER = "x-zigmini-agent-tool-client";
+export const AGENT_TOOL_NONCE_HEADER = "x-zigmini-page-nonce";
+const PAGES_PER_SESSION = 32;
+
+const refuse = (error: string, status: number) => Response.json({ error }, { status, headers: { "Cache-Control": "no-store" } });
+
+function cookie(headers: Headers): string | null {
+	for (const part of (headers.get("cookie") ?? "").split(";")) {
+		const [name, value] = part.trim().split("=");
+		if (name === AGENT_TOOL_COOKIE && value) return value;
+	}
+	return null;
+}
+
+/**
+ * C3 caller helper. Web: HttpOnly SameSite=Strict cookie bound to this gateway generation, a page nonce bound to that
+ * session, exact Origin and Host, and a custom header (CSRF). Android: the existing approved device credential, re-read
+ * on every call. Sessions live in memory only; a restart drops them and nothing is replayed.
+ */
+export class AgentToolClients {
+	private readonly sessions = new Map<string, { generation: string; pages: string[] }>();
+	private readonly hosts: ReadonlySet<string>;
+
+	constructor(private readonly deps: AgentToolClientDeps) {
+		this.hosts = new Set(deps.webOrigins.map((origin) => new URL(origin).host));
+	}
+
+	private webRefusal(req: Request, ctx: AgentToolRequestContext): Response | null {
+		if (!ctx.trusted || ctx.device) return refuse("forbidden", 403);
+		if (!this.hosts.has(req.headers.get("host") ?? "")) return refuse("forbidden_host", 403);
+		// D8: browsers send no Origin on a same-origin GET. Such a GET still needs the Host above, the custom header below,
+		// and the Strict cookie and page nonce (principal). A sent Origin must match, a sent Sec-Fetch-Site must be
+		// same-origin, and every other method keeps requiring the matching Origin.
+		const site = req.headers.get("sec-fetch-site");
+		if (site !== null && site !== "same-origin") return refuse("forbidden_origin", 403);
+		const origin = req.headers.get("origin");
+		if (origin === null ? req.method !== "GET" : !this.deps.webOrigins.includes(origin)) return refuse("forbidden_origin", 403);
+		if (req.headers.get(AGENT_TOOL_CLIENT_HEADER) !== "1") return refuse("custom_header_required", 403);
+		return null;
+	}
+
+	private device(ctx: AgentToolRequestContext): { device: DeviceRecord; revision: string } | null {
+		if (ctx.trusted || !ctx.device) return null;
+		const current = this.deps.currentDevice(ctx.device.id);
+		if (!current || current.status !== "approved") return null;
+		const revision = this.deps.deviceRevision(current);
+		return revision === this.deps.deviceRevision(ctx.device) ? { device: current, revision } : null;
+	}
+
+	/** POST /api/agent-tool-client. Never exposed to tools: the internal listener routes do not reach it. */
+	issue(req: Request, ctx: AgentToolRequestContext): Response {
+		if (req.method !== "POST") return refuse("method_not_allowed", 405);
+		if (!ctx.trusted) {
+			const device = this.device(ctx);
+			if (!device) return refuse("device_not_approved", 401);
+			return Response.json({ client: "android", credentialRevision: device.revision }, { headers: { "Cache-Control": "no-store" } });
+		}
+		const denied = this.webRefusal(req, ctx);
+		if (denied) return denied;
+		let value = cookie(req.headers);
+		let session = value ? this.sessions.get(sha256(value)) : undefined;
+		let setCookie: string | null = null;
+		if (!value || !session || session.generation !== this.deps.generation) {
+			value = randomBytes(32).toString("hex");
+			session = { generation: this.deps.generation, pages: [] };
+			this.sessions.set(sha256(value), session);
+			setCookie = `${AGENT_TOOL_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict`;
+		}
+		const pageNonce = randomBytes(24).toString("base64url");
+		session.pages.push(pageNonce);
+		if (session.pages.length > PAGES_PER_SESSION) session.pages.shift();
+		const headers: Record<string, string> = { "Cache-Control": "no-store" };
+		if (setCookie) headers["set-cookie"] = setCookie;
+		return Response.json({ client: "web", pageNonce, generation: this.deps.generation }, { headers });
+	}
+
+	/** The verified owner of this request, or the refusal to return. */
+	principal(req: Request, ctx: AgentToolRequestContext): OwnerPrincipal | Response {
+		if (!ctx.trusted) {
+			const device = this.device(ctx);
+			if (!device) return refuse("device_not_approved", 401);
+			return { ownerRef: "owner", client: "android", credentialRevision: device.revision, sessionRef: `device:${device.device.id}` };
+		}
+		const denied = this.webRefusal(req, ctx);
+		if (denied) return denied;
+		const value = cookie(req.headers);
+		const key = value ? sha256(value) : null;
+		const session = key ? this.sessions.get(key) : undefined;
+		if (!key || !session || session.generation !== this.deps.generation) return refuse("agent_tool_client_required", 403);
+		const nonce = req.headers.get(AGENT_TOOL_NONCE_HEADER);
+		if (!nonce || !session.pages.includes(nonce)) return refuse("page_nonce_invalid", 403);
+		return { ownerRef: "owner", client: "web", credentialRevision: this.deps.generation, sessionRef: `web:${key}` };
+	}
+
+	/** Explicit client revoke (browser session end). */
+	revoke(sessionRef: string): boolean {
+		return sessionRef.startsWith("web:") && this.sessions.delete(sessionRef.slice(4));
+	}
+}
+
+export interface AgentToolHttpDeps {
+	readonly ledger: AgentToolPermissionStore;
+	readonly clients: AgentToolClients;
+	/** Publishes inbox changes (closed cards after revoke-all). */
+	readonly changed: () => void;
+	/** The agent's migration card (created once, then the same card), or null for a managed agent (Hub.ensureToolMigration). */
+	readonly migration?: (agentId: string) => AgentToolMigrationCard | null;
+	/** The grant scope edit in one Store transaction (Store.editAgentToolGrant). Without it the edit route is 404. */
+	readonly editGrant?: (agentId: string, grantId: string, input: GrantEditInput, principal: OwnerPrincipal) => GrantEditResult;
+	/** Publishes agent.tool_permissions.updated (C10). */
+	readonly policyChanged?: (data: PolicyUpdatedData) => void;
+}
+
+export function agentToolRoute(pathname: string): boolean {
+	return pathname === "/api/agent-tool-client" || /^\/api\/agents\/[^/]+\/tool-permissions(?:\/|$)/.test(pathname);
+}
+
+const BODY_LIMIT = 16 * 1024;
+
+async function body(req: Request): Promise<Record<string, unknown>> {
+	if (Number(req.headers.get("content-length") ?? 0) > BODY_LIMIT) throw new AgentToolPermissionError("tool_request_invalid");
+	const text = await req.text();
+	if (Buffer.byteLength(text) > BODY_LIMIT) throw new AgentToolPermissionError("tool_request_invalid");
+	let value: unknown = null;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		throw new AgentToolPermissionError("tool_request_invalid");
+	}
+	if (!record(value)) throw new AgentToolPermissionError("tool_request_invalid");
+	return value;
+}
+
+/** Owner routes of C3: client nonce, list, edit, revoke, revoke-all and migrate. */
+export async function agentToolHttp(req: Request, ctx: AgentToolRequestContext, deps: AgentToolHttpDeps): Promise<Response> {
+	const url = new URL(req.url);
+	if (url.pathname === "/api/agent-tool-client") return deps.clients.issue(req, ctx);
+	const migrate = /^\/api\/agents\/([^/]+)\/tool-permissions\/migrate$/.exec(url.pathname);
+	const route = migrate ? null : /^\/api\/agents\/([^/]+)\/tool-permissions(?:\/(revoke-all)|\/([^/]+)\/(revoke|edit))?$/.exec(url.pathname);
+	if ((!route && !(migrate && deps.migration)) || (route?.[4] === "edit" && !deps.editGrant)) return refuse("not_found", 404);
+	const principal = deps.clients.principal(req, ctx);
+	if (principal instanceof Response) return principal;
+	try {
+		if (migrate && deps.migration) {
+			// C3 migrate: shows the existing scopes on an inbox card. It never grants anything by itself.
+			if (req.method !== "POST") return refuse("method_not_allowed", 405);
+			const input = await body(req);
+			if (typeof input.operationId !== "string" || !UUID.test(input.operationId)) throw new AgentToolPermissionError("tool_request_invalid");
+			const card = deps.migration(decodeURIComponent(migrate[1]!));
+			if (!card) return refuse("agent_managed", 409);
+			deps.changed();
+			return Response.json(card, { headers: { "Cache-Control": "no-store" } });
+		}
+		if (!route) return refuse("not_found", 404);
+		const agentId = decodeURIComponent(route[1]!);
+		if (!route[2] && !route[4]) {
+			if (req.method !== "GET") return refuse("method_not_allowed", 405);
+			return Response.json(deps.ledger.list(agentId, url.searchParams.get("cursor")), { headers: { "Cache-Control": "no-store" } });
+		}
+		if (req.method !== "POST") return refuse("method_not_allowed", 405);
+		const input = await body(req);
+		if (typeof input.operationId !== "string") throw new AgentToolPermissionError("tool_request_invalid");
+		if (route[2]) {
+			if (typeof input.expectedPolicyRevision !== "number") throw new AgentToolPermissionError("tool_request_invalid");
+			const result = deps.ledger.revokeAll(agentId, { operationId: input.operationId, expectedPolicyRevision: input.expectedPolicyRevision }, principal);
+			deps.changed();
+			deps.policyChanged?.(deps.ledger.policyEvent(agentId));
+			return Response.json(result);
+		}
+		if (route[4] === "edit" && deps.editGrant) {
+			const edited = deps.editGrant(agentId, decodeURIComponent(route[3]!), parseGrantEdit(input), principal);
+			deps.changed();
+			if (edited.status === 200) deps.policyChanged?.(deps.ledger.policyEvent(agentId));
+			return Response.json(edited.body, { status: edited.status, headers: { "Cache-Control": "no-store" } });
+		}
+		if (typeof input.expectedRevision !== "number") throw new AgentToolPermissionError("tool_request_invalid");
+		const result = deps.ledger.revokeGrant(agentId, decodeURIComponent(route[3]!), { operationId: input.operationId, expectedRevision: input.expectedRevision }, principal);
+		deps.changed();
+		deps.policyChanged?.(deps.ledger.policyEvent(agentId));
+		return Response.json(result);
+	} catch (error) {
+		if (error instanceof AgentToolPermissionError) return refuse(error.code, error.status);
+		if (error instanceof URIError) return refuse("tool_request_invalid", 400);
+		throw error;
+	}
+}