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

package/src/hub.ts

@@ -4,25 +4,40 @@ import type { SttProvider } from "./adapters/voice/stt.ts";
 import { blockingCompaction, compactionOutcome, OmoCommandError, type CompactionFailureKind, type OmoEvent, type OmoStatus } from "./omo/client.ts";
 import type { OmoRpc } from "./omo/generations.ts";
 import { type ActionAnswerData, type ConversationActivity, type ConversationInfo, type Envelope, type MessageReference, PROTOCOL_VERSION, type Source, type Trust } from "./protocol.ts";
-import { readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import { mediaFile } from "./media.ts";
-import type { Decision, DecisionSubmission, LedgerEntry, LedgerEntryInput, LedgerState, MainInput, MainInputSource, Store, StoredEvent } from "./store.ts";
+import { releasedWorkQuestion, type Decision, type DecisionSubmission, type LedgerEntry, type LedgerEntryInput, type LedgerState, type MainInput, type MainInputSource, type Store, type StoredEvent } from "./store.ts";
 import { type TranscriptLog, toRecord } from "./transcript.ts";
 import { MaintenanceError, nativeMaintenanceBlocker } from "./maintenance.ts";
 import { isVersionCommand, VERSION_COMMAND } from "./version.ts";
 import { isUsageCommand, USAGE_COMMAND } from "./usage.ts";
 import { COMPACT_COMMAND, compactInstructions } from "./compact.ts";
 import { MessageReferenceError, referencedInput, resolveMessageReferences } from "./message-references.ts";
+import type { AttachmentService } from "./attachments/service.ts";
+import { AttachmentStoreError, type AttachmentMetadata } from "./attachments/types.ts";
 import { readProfile } from "./profile.ts";
-import type { MessageGuard, SecurityChecker } from "./security-check.ts";
+import { countFindings, type MessageGuard, type SecurityChecker, type SecurityFinding } from "./security-check.ts";
 import { SecurityRuntimeError, type SecurityReceipt } from "./security-allow.ts";
 import { nativeReplyEntry, type NativeReplyObserver } from "./reply-notifications.ts";
 import { notificationHistory } from "./notification-history.ts";
 import { messageTimestamp, nativeTurnStarted, nativeTurnStats } from "./turn-stats.ts";
 import { join } from "node:path";
 import { mergeAgentDefinition, AgentDefinitionError, type MergedAgentDefinition } from "./agent/definition.ts";
+import { legacyToolScopes } from "./agent/definition.ts";
+import type { AgentToolMigrationCard } from "./agent/tool-permissions.ts";
 import { AgentFileStore } from "./agent/files.ts";
+import type { CollaborationLifecycle } from "./agent/collaboration-session.ts";
+import { CollaborationStoreError, collaborationNever } from "./agent/collaboration-types.ts";
 import { type Language, say, serverLanguage, type Text, textIn } from "./server-text.ts";
+import { createSecretKey, randomBytes, randomUUID, type KeyObject } from "node:crypto";
+import { ManagedCallError, verifyManagedCall, type ManagedCallBinding, type ManagedCallBindingResolver, type ManagedCallIdentity, type VerifiedManagedCall } from "./agent/managed-call.ts";
+import type { ManagedSession } from "./attachments/managed-binding.ts";
+import { AgentToolPermissionError, type AgentAccessView, type AgentToolGrantRow, type AgentToolRequestInput, type AgentToolRequestRecord } from "./agent/tool-permissions.ts";
+import { agentToolActionId, agentToolOperationId, engineCommands, grantedOperations, pushSessionPolicy } from "./agent/tool-delivery.ts";
+import { ASIDE_OPERATIONS } from "./agent/tool-catalog.ts";
+import { maintenanceAuth } from "./maintenance.ts";
+import { testCrashPoint } from "./test-crash.ts";
 
 class AgentSessionError extends Error {
 	constructor() {
@@ -79,6 +94,10 @@ export interface HubOptions {
 	usageReport?: () => Promise<string>;
 	/** Improvement 165: the security check of user text; a finding keeps the text from omo and the store. */
 	guard?: Pick<MessageGuard, "check" | "hold" | "existing">;
+	/** Selected host documents; absent when this gateway has no attachment service wired. */
+	documents?: AttachmentService;
+	/** 294: agent session binding for /internal/agent-tools/*; `ready` runs after a bind so held grants are delivered. */
+	agentTools?: { readonly bindings: AgentToolBindings; readonly ready?: (convId: string) => void };
 }
 
 /** Anthropic rejects images over 5 MB; bigger attachments reach the agent as a file path only. */
@@ -232,6 +251,8 @@ function describeBlockers(blockers: readonly RotationBlocker[]): string {
 const HANDOFF_MAX_CHARS = 8000;
 const HANDOFF_LINE_CHARS = 600;
 const CONTEXT_OVERFLOW = /prompt is too long|context overflow/i;
+/** ensureSession/prompt refusals that mean "the session is not ready now", not a dispatch failure. */
+const DISPATCH_NOT_READY = new Set(["omo_not_ready", "stale_open_session", "session_rotating", "omo_owner_not_ready", "agent_busy"]);
 const COMPACTION_REQUIRED_MESSAGE: Text = {
 	en: "The engine did not receive this message because the conversation summary did not finish. The message stays in the history and will not be sent again automatically. Fix the cause of the summary failure or press 'New session'.",
 	ko: "대화 요약이 끝나지 않아 엔진이 이 메시지를 받지 않았습니다. 메시지는 기록에 남아 있고 자동으로 다시 보내지 않습니다. 요약 실패 원인을 해결하거나 '새 세션'을 눌러 주세요.",
@@ -281,8 +302,33 @@ export const HUB_TEXT = {
 	recoveredMany: { en: " Filled in {count} missed answers.", ko: " 놓친 답변 {count}개를 채웠습니다." },
 	multiSelect: { en: " (multiple choices allowed)", ko: " (여러 개 선택 가능)" },
 	questionUnreachable: { en: "The question window did not reach the web. Press Stop, then answer in the chat.", ko: "질문 창이 웹에 도착하지 않았습니다. 중단 버튼을 누른 뒤 채팅으로 답해 주세요." },
+	collaborationRequestSent: { en: "Sent a collaboration request", ko: "협업 요청을 보냈습니다" },
+	collaborationRequestReceived: { en: "Received a collaboration request", ko: "협업 요청을 받았습니다" },
+	collaborationResultSent: { en: "Sent the collaboration result", ko: "협업 결과를 보냈습니다" },
+	collaborationResultReceived: { en: "Received the collaboration result", ko: "협업 결과를 받았습니다" },
+	collaborationEndedWithoutResult: { en: "The collaboration request ended without a result", ko: "협업 요청이 결과 없이 끝났습니다" },
 } as const satisfies Record<string, Text>;
 
+/**
+ * C-4 fallback for apps that do not know `message.collaboration`: one `notice {kind:"collaboration",requestId,direction,message}`
+ * in the same conversation as each stored collaboration message (the web skips it next to its card). A result-less final
+ * reply (`agent.collaboration.final_reply`) is the requester's reply too and names its final state and reason. Null for anything else.
+ */
+export function collaborationNotice(event: Pick<StoredEvent, "type" | "data">): { readonly kind: "collaboration"; readonly requestId: string; readonly direction: "request" | "reply"; readonly message: string } | null {
+	const data = event.data;
+	if (event.type === "agent.collaboration.final_reply" && typeof data === "object" && data !== null && "requestId" in data && typeof data.requestId === "string" &&
+		"state" in data && typeof data.state === "string" && "reason" in data && typeof data.reason === "string") {
+		return { kind: "collaboration", requestId: data.requestId, direction: "reply", message: `${say(HUB_TEXT.collaborationEndedWithoutResult)}: ${data.state} (${data.reason})` };
+	}
+	if (event.type !== "message.collaboration" || typeof data !== "object" || data === null || !("requestId" in data) || typeof data.requestId !== "string" ||
+		!("direction" in data) || (data.direction !== "request" && data.direction !== "reply")) return null;
+	const outgoing = "outgoing" in data && data.outgoing === true;
+	const label = data.direction === "request" ? (outgoing ? HUB_TEXT.collaborationRequestSent : HUB_TEXT.collaborationRequestReceived)
+		: (outgoing ? HUB_TEXT.collaborationResultSent : HUB_TEXT.collaborationResultReceived);
+	const text = "text" in data && typeof data.text === "string" ? data.text.trim() : "";
+	return { kind: "collaboration", requestId: data.requestId, direction: data.direction, message: text ? `${say(label)}: ${text}` : `${say(label)}.` };
+}
+
 /** Why a session was replaced. The user notice uses the UI language; the engine context keeps the Korean text. */
 const ROTATION_REASON = {
 	size: { en: "the session file reached {mb} MB", ko: "세션 파일이 {mb}MB에 닿음" },
@@ -343,6 +389,10 @@ interface ConvRuntime {
 	atomicQueuedResume: boolean;
 	/** `open_session` state.sessionId: the session file's own identity, which survives reconnects. */
 	durableId: string | null;
+	/** Current attachment-read binding of this native session. */
+	documentIncarnation?: string;
+	/** The host advertises document input and this session's gateway extension registered the resolver. */
+	documentResolver?: boolean;
 	waking: Promise<void> | null;
 	wake: WorkWake | null;
 	notified: Set<string>;
@@ -430,6 +480,12 @@ export const MAIN_QUESTION_RELEASED =
 	"question open in the user's inbox and returned at once. The user has not answered yet. The answer arrives later as a " +
 	"ZGW_DECISION_COMMAND user message with the question and the response. Until then, do not take the action that depends on " +
 	"this answer and do not ask it again; handle every other message as usual.";
+/** Bug 236: the tool result a work gets for its required question when a newer instruction was queued behind it. */
+export const WORK_QUESTION_RELEASED =
+	"ZGW_QUESTION_OPEN This note is from the gateway, not the user's answer. A newer instruction arrived while this work waited " +
+	"on this question, so the gateway ended the wait and kept the question open in the user's inbox. The user has not answered " +
+	"yet. The answer arrives later as a ZGW_WORK_COMMAND with the question and the response. Until then, do not take the action " +
+	"that depends on this answer and do not ask it again; handle the newer instruction and every other message as usual.";
 const PERMISSION_PREFIX = "Permission required:";
 const AUTO_CONTINUE_LIMIT = 2;
 const CONTINUE_PROMPT =
@@ -471,6 +527,11 @@ export function modelOptions(models: OmoModel[]): ModelChoice[] {
 }
 
 export class Hub {
+	private collaboration: CollaborationLifecycle | undefined;
+	private readonly collaborationFlights = new Map<string, Promise<void>>();
+	private readonly settling = new Map<string, number>();
+	private readonly collaborationGeneration = crypto.randomUUID();
+	private readonly collaborationIncarnations = new Map<string, string>();
 	private readonly runtime = new Map<string, ConvRuntime>();
 	private readonly deletingAgents = new Set<string>();
 	private readonly sessionToConv = new Map<string, string>();
@@ -514,12 +575,266 @@ export class Hub {
 	) {
 		if (!store.getConversation("main")) store.createConversation("main", "main");
 		this.maintenanceId = store.getSetting("maintenance.owner") || null;
+		store.onCollaborationEvents = () => this.publishCollaborationEvents();
 	}
 
 	attachOmo(omo: OmoRpc): void {
 		this.omo = omo;
 	}
 
+	attachCollaboration(lifecycle: CollaborationLifecycle): void { this.collaboration = lifecycle; }
+
+	checkCollaborationText(text: string): void {
+		// Artifact/peer review is not an owner message closure. T7 owns that purpose-specific ingress.
+		if (this.options.guard?.check([text])) throw new CollaborationStoreError("collaboration_security_review_required");
+	}
+
+	/** The finding kinds and counts of the texts a collaboration read would release; empty when the check passes or no guard is set. */
+	collaborationFindings(texts: readonly string[]): SecurityFinding[] {
+		return countFindings(this.options.guard?.check(texts) ?? []);
+	}
+
+	/** A security hold's decision changed outside the DecisionService (created, reviewed, settled, resumed): publish its decision.updated. */
+	refreshDecisions(): void {
+		this.decisions?.refresh();
+	}
+
+	/** Owner allow and the reader's settle both call this; whichever comes second queues the one reviewed read. */
+	resumeArtifactReview(holdId: string): void {
+		try {
+			const hold = this.store.artifactSecurityHold(holdId), lifecycle = this.collaboration;
+			if (!lifecycle || !hold || hold.state !== "allowed" || hold.answerSubmissionId === null || !hold.continuation.settledReceipt ||
+				hold.continuation.resumeSubmissionId !== null) return;
+			this.store.resumeArtifactRead({ holdId, expectedRevision: hold.revision, resumeSubmissionId: hold.answerSubmissionId, readOperationId: hold.readOperationId,
+				scopeDigest: hold.scopeDigest, ownerPrincipalRef: hold.ownerPrincipalRef }, this.store.artifactReaderBinding(hold.readOperationId), lifecycle.artifactRead(hold));
+			void this.dispatchCollaboration(hold.readScope.granteeConv);
+		} finally {
+			// The settle before this call and the resume itself both moved the hold's decision revision.
+			this.decisions?.refresh();
+		}
+	}
+
+	/** Internal 294 consumer. This is not an owner answer endpoint or an ordinary permission router. */
+	acceptCollaborationPermission(outcome: import("./agent/collaboration-types.ts").CollaborationPermissionOutcome) {
+		if (!this.collaboration) throw new CollaborationStoreError("authority_adapter_required", 503);
+		const activation = this.collaboration.permission(outcome);
+		void this.dispatchCollaboration(activation.targetConv);
+		return { activationId: activation.id, inputId: activation.inputId, state: activation.state };
+	}
+
+	/** A lease of an already-open native session; HTTP callers cannot open or select another conversation. */
+	collaborationSession(convId: string) {
+		const conv = this.store.listConversations(false).find(row => row.id === convId), rt = this.runtime.get(convId);
+		const incarnation = this.collaborationIncarnations.get(convId);
+		if (!conv || !conv.threadId || !rt?.sessionId || !rt.durableId || !incarnation ||
+			this.omoStatus !== "ready" || rt.rotating || this.maintenanceId || this.deletingAgents.has(convId)) return null;
+		const sessionId = rt.sessionId, durableId = rt.durableId, generation = this.generation;
+		const ownerInputRevision = this.store.lastSeq(convId, "message.user");
+		const current = () => this.omoStatus === "ready" && generation === this.generation && !rt.rotating &&
+			!this.maintenanceId && rt.sessionId === sessionId && rt.durableId === durableId &&
+			this.collaborationIncarnations.get(convId) === incarnation &&
+			this.sessionToConv.get(sessionId) === convId && this.store.getConversation(convId)?.threadId === conv.threadId &&
+			this.store.listConversations(false).some(row => row.id === convId && row.createdAt === conv.createdAt && row.agentId === conv.agentId) &&
+			!this.deletingAgents.has(convId) && this.store.lastSeq(convId, "message.user") === ownerInputRevision;
+		return { sessionId, durableId, sessionPath: conv.threadId, agentId: conv.agentId ?? null, incarnation,
+			generation: `${this.collaborationGeneration}:${generation}`, ownerInputRevision,
+			convEpoch: Date.parse(conv.createdAt), current,
+			rpc: (type: string, params: Record<string, unknown> = {}): Promise<unknown> =>
+				this.requireOmo().command(type, { ...params, sessionId }) };
+	}
+
+	/**
+	 * A peer's tool call can reach HTTP before this Hub handles the input's user message_end frame. The caller has already
+	 * authenticated the native consumption; record it from the same ledger evidence so the Store never refuses the call.
+	 */
+	async recordCollaborationConsumption(convId: string, inputId: string): Promise<void> {
+		const sessionId = this.rt(convId).sessionId, generation = this.generation;
+		const input = this.store.mainTurn(convId)?.inputs.find(row => (row.data as MainInput).input_id === inputId);
+		if (!sessionId || !input || this.store.mainInputConsumed(input)) return;
+		const data: MainInput = JSON.parse(JSON.stringify(input.data));
+		if (data.origin !== "agent_collaboration" && data.origin !== "agent_tool_permission") return;
+		const ledger = await this.currentLedger(convId, sessionId, generation);
+		const entry = ledger && this.ledgerInputEntry(ledger, data);
+		if (!ledger || !entry || generation !== this.generation) return;
+		const consumed = this.store.consumeMainInput(input, { entry, durableId: ledger.durableId });
+		if (consumed) this.publishStored(consumed);
+	}
+
+	/** Publish only the committed queued records; T6 owns subsequent dispatch and consumption. */
+	collaborationQueued(requestId: string, cursors: ReadonlyMap<string, number>): void {
+		for (const [conv, cursor] of cursors) for (const event of this.store.eventsAfter(conv, cursor)) {
+			if (event.type === "message.collaboration" || event.type === "agent.collaboration.status") {
+				const data = event.data;
+				if (typeof data === "object" && data !== null && "requestId" in data && data.requestId === requestId) {
+					this.publishStored(event);
+					this.noticeCollaboration(event);
+				}
+			}
+		}
+		// The same admission may have moved the parent request (waiting_peer); its status goes out with the rest.
+		this.publishCollaborationEvents();
+		const request = this.store.getAgentRequest(requestId);
+		if (request) void this.dispatchCollaboration(request.targetConv);
+	}
+
+	/**
+	 * F3 D1: every stored collaboration event the Store queued since the last call reaches the open pages now, on the same
+	 * frames their history replay uses (the requester's status changes and a result's two reply messages), so a page never
+	 * has to reload to see a card finish, stop or wait for the owner. The receiving conversation stores no status of its
+	 * own (its listing carries the state), so its open page gets the requester's status as a live frame that is not stored.
+	 * Called at the Hub's own points and by the Store one microtask after any other transaction that queued events.
+	 */
+	publishCollaborationEvents(): void {
+		for (const event of this.store.takeCollaborationEvents()) {
+			this.publishStored(event);
+			if (event.type !== "agent.collaboration.status") continue;
+			const data = event.data;
+			const request = typeof data === "object" && data !== null && "requestId" in data && typeof data.requestId === "string" ? this.store.getAgentRequest(data.requestId) : null;
+			if (request && request.targetConv !== event.conv) this.emit(request.targetConv, "agent.collaboration.status", data, false);
+		}
+	}
+
+	/** Asks the conversation's current extension to drain and seal the outputs listed by its frozen result execute. */
+	async collaborationSnapshot(convId: string, call: { readonly requestId: string; readonly requestRevision: number; readonly operationKey: string;
+		readonly bindingDigest: string; readonly paths: readonly string[] }): Promise<
+		{ readonly ok: true; readonly files: readonly { readonly sealedName: string; readonly sha256: string; readonly bytes: number; readonly mediaType: string; readonly name: string }[] } |
+		{ readonly ok: false; readonly error: string }> {
+		const sessionId = this.rt(convId).sessionId;
+		if (!sessionId || this.omoStatus !== "ready") throw new CollaborationStoreError("collaboration_session_unavailable", 503);
+		return this.requireOmo().command("extension_request", { sessionId, name: "zgw.agent_snapshot", data: { ...call, paths: [...call.paths] } });
+	}
+
+	/**
+	 * Cooperative interrupt for executions whose request is cancel_requested, sent only while that exact activation is still
+	 * the conversation's current binding and run. An owner turn or a later activation is never aborted.
+	 */
+	async interruptCancelledCollaboration(): Promise<void> {
+		for (const { conv, activationId } of this.store.cancelRequestedExecutions()) {
+			const rt = this.rt(conv), sessionId = rt.sessionId;
+			if (!sessionId || !rt.running || this.omoStatus !== "ready" || this.store.agentBinding(conv)?.activationId !== activationId) continue;
+			await this.requireOmo().command("abort", { sessionId });
+		}
+	}
+
+	/** A settled execution commits its explicit result once (waking the requester) or records result_missing. */
+	private finalizeCollaboration(activationId: string): void {
+		const lifecycle = this.collaboration;
+		if (!lifecycle) return;
+		const finished = this.store.finalizeAgentActivation(activationId, request => lifecycle.gate(request));
+		if (finished.result) {
+			testCrashPoint("collaboration.result.committed");
+			// The committed status and reply messages reach the open pages before their fallback notices.
+			this.publishCollaborationEvents();
+			// The result's two reply messages were just committed as the last collaboration message of each side.
+			const request = this.store.getAgentRequest(finished.result.requestId);
+			for (const conv of request ? [request.requesterConv, request.targetConv] : []) {
+				const reply = this.store.getEvent(this.store.lastSeq(conv, "message.collaboration"));
+				const data = reply?.data;
+				if (reply && typeof data === "object" && data !== null && "resultId" in data && data.resultId === finished.result.id) this.noticeCollaboration(reply);
+			}
+		}
+		for (const decisionId of this.store.collaborationPermissionDecisions(activationId)) this.continueCollaborationPermission(decisionId);
+		this.wakeCollaborationReplies();
+	}
+
+	/** Sent once, when the collaboration message itself is first published, so a replay never repeats it. */
+	private noticeCollaboration(event: StoredEvent): void {
+		const notice = collaborationNotice(event);
+		if (notice) this.emit(event.conv, "notice", notice);
+	}
+
+	/** A reply queued by a result or by a final state without one wakes its requester; dispatch keeps owner turns first. */
+	wakeCollaborationReplies(): void {
+		// The pages get a cancel or a result-less end at once, whatever the engine's state (a closed Store queues nothing).
+		this.publishCollaborationEvents();
+		// A disconnected Hub dispatches nothing; its Store may already be closed under a late continuation.
+		if (this.omoStatus !== "ready") return;
+		for (const reply of this.store.takeFinalReplies()) this.noticeCollaboration(reply);
+		for (const conv of this.store.queuedAgentReplyConvs()) void this.dispatchCollaboration(conv);
+	}
+
+	/** Only Hub opens the existing conversation. A queued peer never steers an active owner. */
+	dispatchCollaboration(convId: string): Promise<void> {
+		const active = this.collaborationFlights.get(convId);
+		if (active) return active;
+		const lifecycle = this.collaboration, rt = this.rt(convId);
+		const available = () => this.omoStatus === "ready" && !this.maintenanceId && !rt.rotating &&
+			!this.closeUncertain(convId) && !rt.running && rt.admitting === 0 && !rt.waking && !rt.wake &&
+			!this.settling.get(convId) && !this.store.mainTurn(convId) && this.store.pendingMainUsers(convId).length === 0;
+		// Liveness first: a prompt finishing after its engine disconnected (and its Store closed) must not read the Store.
+		if (!lifecycle || !available()) return Promise.resolve();
+		const first = this.store.nextAgentInput(convId);
+		const firstRead = this.store.nextArtifactReadInput(convId);
+		if (!first && !firstRead) return Promise.resolve();
+		const generation = this.generation, run = rt.run;
+		const flight = (async () => {
+			const conv = this.store.getConversation(convId);
+			if (!conv) return;
+			let readable = firstRead;
+			if (readable) {
+				try { lifecycle.artifactRead(readable.hold); }
+				catch (error) {
+					if (!(error instanceof CollaborationStoreError) || error.status !== 503) throw error;
+					this.emit(convId, "agent.collaboration.blocked", { code: error.code, holdId: readable.hold.id });
+					readable = null;
+				}
+			}
+			if (!first && !readable) return;
+			const { sessionId } = await this.ensureSession(conv);
+			const state = await this.requireOmo().command<{ isStreaming?: boolean; pendingMessageCount?: number; isCompacting?: boolean;
+				isBashRunning?: boolean }>("get_state", { sessionId });
+			const runtime = await this.requireOmo().command<{ ownedInFlight?: number }>("extension_request",
+				{ sessionId, name: "zgw.agent_collaboration_runtime" });
+			if (generation !== this.generation || rt.run !== run || rt.sessionId !== sessionId || !available() ||
+				state.isStreaming !== false || state.pendingMessageCount !== 0 || state.isCompacting || state.isBashRunning ||
+				runtime.ownedInFlight !== 0) return;
+			const next = this.store.nextAgentInput(convId);
+			const read = readable && this.store.nextArtifactReadInput(convId);
+			if (read && (!next || read.seq < next.activation.inputSeq)) {
+				const body = `ZGW_COLLABORATION_INPUT ${JSON.stringify({ origin: "collaboration_artifact_read",
+					holdId: read.hold.id, readOperationId: read.hold.readOperationId, continuationId: read.hold.continuation.id,
+					reviewedScopeDigest: read.hold.scopeDigest, read: read.hold.readArguments, trust: "delegated" })}`;
+				await this.prompt(convId, body, { artifactRead: read.hold });
+				return;
+			}
+			if (!next) return;
+			const event = this.store.getEvent(next.activation.inputSeq);
+			const intent: import("./agent/collaboration-types.ts").CollaborationIntent = JSON.parse(JSON.stringify(event?.data));
+			let payload: unknown;
+			switch (intent.origin) {
+				case "agent_collaboration": payload = this.store.getEvent(intent.messageSeq)?.data; break;
+				case "agent_tool_permission": payload = intent.outcome; break;
+				case "collaboration_artifact_read": case "collaboration_stage": throw new CollaborationStoreError("input_source_mismatch");
+				default: return collaborationNever(intent);
+			}
+			// A single JSON value keeps slash/control/envelope-looking peer bytes literal.
+			const body = `ZGW_COLLABORATION_INPUT ${JSON.stringify({ origin: intent.origin, requestId: next.request.id,
+				rootId: next.request.rootId, activationId: next.activation.id, trust: "delegated", payload })}`;
+			await this.prompt(convId, body, { collaboration: next });
+		})().catch(error => {
+			// Every caller drops this promise (`void`), so nothing may escape it. A flight whose engine generation ended, or
+			// whose session was not ready, is stale rather than failed: its input was never claimed and stays queued for the
+			// next ready/settle dispatch.
+			if (generation !== this.generation || this.omoStatus !== "ready" || error instanceof MaintenanceError ||
+				(error instanceof Error && DISPATCH_NOT_READY.has(error.message))) {
+				console.info(`collaboration dispatch (${convId}) not ready: ${errorMessage(error)}`);
+				return;
+			}
+			// Any other failure is logged and reported on the conversation. An input that never crossed the prompt stays
+			// queued (the next dispatch retries it); prompt() itself already recorded the delivery state of one that did.
+			console.error(`collaboration dispatch failed (${convId}): ${errorMessage(error)}`);
+			this.emit(convId, "agent.collaboration.blocked", { code: error instanceof CollaborationStoreError ? error.code : "dispatch_failed" });
+		}).finally(() => {
+			if (this.collaborationFlights.get(convId) !== flight) return;
+			this.collaborationFlights.delete(convId);
+			// A settle before the prompt ACK must not lose the wake for the next FIFO item.
+			if (available() && (this.store.nextAgentInput(convId)?.activation.id !== first?.activation.id ||
+				this.store.nextArtifactReadInput(convId)?.hold.id !== firstRead?.hold.id)) void this.dispatchCollaboration(convId);
+		}).catch(error => console.error(`collaboration dispatch wake failed (${convId}): ${errorMessage(error)}`));
+		this.collaborationFlights.set(convId, flight);
+		return flight;
+	}
+
 	/** Explicit mode activation snapshots every existing main source before admitting new occurrences. */
 	async notificationBaseline(): Promise<void> {
 		for (const conv of this.store.listConversations()) {
@@ -539,6 +854,27 @@ export class Hub {
 
 	attachDecisions(decisions: DecisionService): void {
 		this.decisions = decisions;
+		decisions.useToolAnswered(decisionId => this.continueCollaborationPermission(decisionId));
+	}
+
+	/**
+	 * Q-07: the owner's stored answer to a 294 card asked inside a collaboration execution continues that request once.
+	 * Called after the answer commits and after the asking execution settles; the dispatcher dedupes the exact outcome, so
+	 * whichever comes second is the one that continues. A refusal is reported on the request's conversation.
+	 */
+	continueCollaborationPermission(decisionId: string): void {
+		const outcome = this.store.collaborationPermissionOutcome(decisionId);
+		if (!outcome || !this.collaboration) return;
+		const blocked = this.store.getAgentActivation(outcome.blockedActivationId);
+		if (!blocked?.quiesced) return;
+		try {
+			this.acceptCollaborationPermission(outcome);
+			// The answer also released the requests below the held one (as a question answer does).
+			for (const conv of this.store.agentDecisionDependents(decisionId)) void this.dispatchCollaboration(conv);
+		} catch (error) {
+			if (!(error instanceof CollaborationStoreError)) throw error;
+			this.emit(blocked.targetConv, "agent.collaboration.blocked", { code: error.code, decisionId });
+		}
 	}
 
 	decisionLiveBinding(decision: Decision): DecisionSubmission["liveBinding"] {
@@ -572,7 +908,7 @@ export class Hub {
 	async dispatchDecisionMain(input: StoredEvent): Promise<void> {
 		const data = input.data as { text: string };
 		this.publishStored(input);
-		await this.prompt(input.conv, data.text, [], input.seq, true);
+		await this.prompt(input.conv, data.text, { messageSeq: input.seq, admitted: true });
 	}
 
 	/**
@@ -583,9 +919,12 @@ export class Hub {
 		const conv = this.store.getConversation(convId);
 		if (!conv || this.omoStatus !== "ready") return;
 		const generation = this.generation;
+		const started = conv.threadId;
 		const { sessionId } = await this.ensureSession(conv);
 		const ledger = await this.currentLedger(convId, sessionId, generation, 30_000);
-		if (!ledger) return;
+		// Evidence read for the settled session never judges the decisions of a session the conversation rotated to meanwhile.
+		if (!ledger || (started && ledger.sessionPath !== started) ||
+			ledger.sessionPath !== this.store.getConversation(convId)?.threadId) return;
 		const path = ledger.sessionPath;
 		const owner = { conv: convId, scope: this.conversationScope(convId), sessionPath: path };
 		const userMessages = this.store.ledgerUserTexts(path);
@@ -625,6 +964,10 @@ export class Hub {
 		return this.omoStatus === "ready" && sessionId !== undefined && this.sessionToConv.has(sessionId);
 	}
 
+	hasSession(conv: string): boolean {
+		return this.runtime.get(conv)?.sessionId != null;
+	}
+
 	/** Execution indicator, not authority to replace the native runtime. */
 	busy(): boolean {
 		for (const rt of this.runtime.values()) if (rt.admitting > 0 || rt.running || rt.rotating || rt.opening || rt.waking || rt.wake) return true;
@@ -750,12 +1093,13 @@ export class Hub {
 	}
 
 	/**
-	 * Main questions kept open without their native wait still wait for the user: their cards (and so the device question
-	 * notifications) come from the stored decisions, which outlive a gateway restart.
+	 * Main questions kept open without their native wait, and work questions released for a newer instruction (bug 236),
+	 * still wait for the user: their cards (and so the device question notifications) come from the stored decisions,
+	 * which outlive a gateway restart.
 	 */
 	private releasedMainCards(): (QuestionCard & { decisionId: string })[] {
-		return this.store.allDecisions().filter((d) => d.workId === null && d.method === "question" && d.status === "pending" &&
-			d.bindingState === "closed" && d.reason === "main_released" && d.sourceSessionPath !== null).map((d) => {
+		return this.store.allDecisions().filter((d) => d.method === "question" && d.status === "pending" && d.sourceSessionPath !== null &&
+			((d.workId === null && d.bindingState === "closed" && d.reason === "main_released") || releasedWorkQuestion(d))).map((d) => {
 			const payload = d.payload as { title?: unknown; questions?: unknown };
 			return {
 				actionId: d.legacyActionId ?? scopedActionId(d.scope, d.sourceRequestId), scope: d.scope, conv: d.ownerConv,
@@ -787,7 +1131,8 @@ export class Hub {
 	 */
 	history(conv: string, query: HistoryQuery = {}): HistoryPage {
 		const limit = Math.min(Math.max(Math.trunc(query.limit ?? HISTORY_PAGE), 1), HISTORY_MAX_PAGE);
-		const toEnvelope = (e: StoredEvent): Envelope => {
+		const toEnvelope = (stored: StoredEvent): Envelope => {
+			const e = this.withAttachmentState(stored);
 			const action = e.data;
 			if (e.type !== "action.request" || typeof action !== "object" || action === null || Array.isArray(action) ||
 				!("actionId" in action) || typeof action.actionId !== "string" || "decisionId" in action) {
@@ -912,7 +1257,9 @@ export class Hub {
 				rt.sessionId = null;
 			}
 			const entry = trash();
-			this.store.setConversationHidden(convId, true);
+			const hide = () => this.store.setConversationHidden(convId, true);
+			if (this.options.documents) this.options.documents.retireRecipient(convId, conv.agentId, hide);
+			else hide();
 			return entry;
 		} finally {
 			this.deletingAgents.delete(convId);
@@ -925,6 +1272,8 @@ export class Hub {
 		// A connection change is an observation too: a ledger read issued before it is never shared after it.
 		this.eventCount += 1;
 		if (status !== "ready") {
+			this.collaboration?.retire();
+			this.collaborationIncarnations.clear();
 			this.generation += 1;
 			for (const recovery of this.closeRecoveries.values()) {
 				if (recovery.timer !== undefined) this.clearCloseTimer(recovery.timer);
@@ -954,6 +1303,8 @@ export class Hub {
 				}
 			}
 		}
+		// A fresh connection (gateway start or reconnect) owns no earlier native run: deliveries left mid-boundary are uncertain.
+		if (status === "ready") this.store.markUncertainAgentDeliveries();
 		this.publishAllActivities();
 		this.emit("*", "omo.status", { status, detail: detail ?? null }, false);
 		return status === "ready" && !this.maintenanceId
@@ -983,9 +1334,9 @@ export class Hub {
 				if (pendingUsers.length > 0) {
 					await this.ensureSession(current);
 					for (const user of pendingUsers) {
-						const data = user.data as { text: string; images?: string[]; references?: MessageReference[] };
-						const input = referencedInput(data.text, data.images ?? [], data.references);
-						await this.prompt(conv.id, input.text, input.images, user.seq, true);
+						const data = user.data as { text: string; images?: string[]; references?: MessageReference[]; attachments?: AttachmentMetadata[]; documentFallback?: boolean };
+						const input = referencedInput(data.documentFallback ? "" : data.text, data.images ?? [], data.references, data.attachments);
+						await this.prompt(conv.id, input.text, { images: input.images, messageSeq: user.seq, admitted: true, documents: data.attachments });
 					}
 				} else if (this.hasUnfinishedTurn(conv.id)) await this.recoverConversation(current);
 				else if (this.openQuestionCards(conv.id, this.conversationScope(conv.id)).size > 0) await this.ensureSession(current);
@@ -1004,6 +1355,7 @@ export class Hub {
 				}
 				// Opening main comes first. A notification ACK or worker reconciliation cannot hold readiness.
 				void this.notifyWorkUpdates(conv.id);
+				void this.dispatchCollaboration(conv.id);
 			} catch (error) {
 				if (generation === this.generation && activityRecovery === this.activityRecoveryGeneration) {
 					this.activityRecoveryFailedGeneration = activityRecovery;
@@ -1015,7 +1367,7 @@ export class Hub {
 	}
 
 	/** `images` are names of files already uploaded to the media folder; unknown names are dropped. */
-	async sendText(convId: string, text: string, src: Source, trust: Trust, images: string[] = [], referenceIds?: unknown, checked = false, submissionId?: string): Promise<void> {
+	async sendText(convId: string, text: string, src: Source, trust: Trust, images: string[] = [], referenceIds?: unknown, checked = false, submissionId?: string, principal: string | null = null): Promise<void> {
 		if (this.maintenanceId) throw new MaintenanceError("maintenance_held");
 		this.requireVisibleAgent(convId);
 		if (submissionId !== undefined && !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(submissionId)) throw new SecurityRuntimeError("held_conflict");
@@ -1027,6 +1379,9 @@ export class Hub {
 		const body = text.trim();
 		const source = structuredClone(src);
 		const references = structuredClone(resolveMessageReferences(this.store, convId, referenceIds));
+		if (references.some((reference) => reference.attachments?.length)) {
+			return this.sendDocuments({ convId, text, src: source, trust, images, referenceIds, attachments: [], submissionId, principal });
+		}
 		if (this.options.versionReport && images.length === 0 && references.length === 0 && isVersionCommand(body)) {
 			this.emit(convId, "notice", { kind: "version", level: "info", message: await this.options.versionReport() });
 			return;
@@ -1069,7 +1424,8 @@ export class Hub {
 					message: say(HUB_TEXT.closeChecking) });
 				return;
 			}
-			await this.prompt(convId, prompt.text, prompt.images, input.seq, true, attachmentSnapshot, receipt !== undefined);
+			await this.prompt(convId, prompt.text, { images: prompt.images, messageSeq: input.seq, admitted: true,
+				attachmentSnapshot, protectedPayload: receipt !== undefined });
 		};
 		// The approved closure owns the inspected references, body and image bytes. Never re-resolve reference ids.
 		const found = checked ? null : this.options.guard?.check([prompt.text]);
@@ -1080,6 +1436,108 @@ export class Hub {
 		await send();
 	}
 
+	/**
+	 * Documents enter through one Store transaction after the exact manifest is inspected. This path has no command
+	 * shortcuts, and a held send keeps its fixed plan: release fails if the prepared content changed meanwhile.
+	 */
+	async sendDocuments(input: { convId: string; text: string; src: Source; trust: Trust; images: string[]; referenceIds: unknown; attachments: string[]; submissionId: string | undefined; principal: string | null; reply?: (frame: unknown) => void }): Promise<void> {
+		const { convId, text, src, trust, images, referenceIds, attachments, submissionId, principal } = input;
+		if (this.maintenanceId) throw new MaintenanceError("maintenance_held");
+		this.requireVisibleAgent(convId);
+		const documents = this.options.documents;
+		if (!documents) throw new AttachmentStoreError("attachment_provider_invalid", 503);
+		if (principal === null) throw new AttachmentStoreError("attachment_owner_inactive", 403);
+		if (submissionId === undefined) throw new AttachmentStoreError("invalid_attachment_input", 400);
+		const context = { key: JSON.stringify(["message", convId, submissionId]), submissionId,
+			snapshot: structuredClone({ text, src, trust, images, referenceIds, attachments }) };
+		// An approved hold is already an accepted submission: the plan below returns its receipt or refuses a changed payload.
+		const held = this.options.guard?.existing(context);
+		if (held && held.status !== "sent") return;
+		const references = structuredClone(resolveMessageReferences(this.store, convId, referenceIds));
+		const dir = this.options.media?.dir;
+		const attached = dir ? [...new Set(images)].filter((n) => mediaFile(dir, n)) : [];
+		const plan = await documents.plan({ convId, principal, text, images: attached, references, src: structuredClone(src), trust, submissionId, attachments });
+		const imageSnapshot = this.attachments(attached);
+		const send = async (receipt?: (ref: SecurityReceipt) => void) => {
+			this.requireVisibleAgent(convId);
+			const accepted = documents.commit(plan, receipt);
+			const stored = this.store.getEvent(accepted.messageSeq);
+			// Only the live frame names the submission: the stored message and its request digest keep their shape.
+			const echoed = stored && { ...stored, data: { ...(this.withAttachmentState(stored).data as Record<string, unknown>), submissionId } };
+			if (!accepted.fresh) {
+				if (echoed) input.reply?.({ v: PROTOCOL_VERSION, id: this.nextId("e"), ts: echoed.ts, conv: echoed.conv, type: echoed.type, data: echoed.data, seq: echoed.seq });
+				return;
+			}
+			if (echoed) this.publishStored(echoed);
+			this.decisions?.refresh();
+			const rotationDone = this.rt(convId).rotationDone;
+			if (rotationDone) await rotationDone;
+			if (this.closeUncertain(convId)) {
+				this.scheduleCloseRecovery(convId);
+				return;
+			}
+			const prompt = referencedInput(plan.body, attached, references, accepted.attachments);
+			await this.prompt(convId, prompt.text, { images: prompt.images, messageSeq: accepted.messageSeq, admitted: true,
+				attachmentSnapshot: imageSnapshot, protectedPayload: receipt !== undefined, documents: accepted.attachments });
+		};
+		if (plan.findings) {
+			this.options.guard?.hold(convId, "message", [...plan.findings], send, plan.body, context);
+			return;
+		}
+		await send();
+	}
+
+	/**
+	 * The live session's provider, API and input types pick the representation; a client never supplies them. A native
+	 * route also needs a host that registered this gateway's resolver, otherwise support is unproven and pages are used.
+	 */
+	async documentRoute(convId: string): Promise<"native-document" | "pages" | "ocr"> {
+		const conv = this.store.getConversation(convId);
+		if (!conv) throw new Error(`unknown_conversation:${convId}`);
+		const { sessionId } = await this.ensureSession(conv);
+		const state = await this.requireOmo().command<{ model?: { input?: unknown; provider?: unknown; api?: unknown } | null }>("get_state", { sessionId });
+		const input = state.model?.input;
+		if (!Array.isArray(input)) throw new Error("model_capability_unknown");
+		if (!input.includes("image")) return "ocr";
+		const publicRoute = (state.model?.provider === "openai" && state.model?.api === "openai-responses") ||
+			(state.model?.provider === "anthropic" && state.model?.api === "anthropic-messages");
+		return publicRoute && this.rt(convId).documentResolver === true ? "native-document" : "pages";
+	}
+
+	emitNotice(convId: string, kind: string): void {
+		this.emit(convId, "notice", { kind, level: "warning", message: kind });
+	}
+
+	/** Rotates the read secret on every native open; a failed bind leaves only a refused tool. */
+	private async bindDocuments(conv: ConversationInfo, sessionId: string, sessionPath: string, rt: ConvRuntime, generation: number): Promise<void> {
+		const documents = this.options.documents;
+		if (!documents || !rt.durableId) return;
+		const issued = documents.bindings.bind({
+			role: conv.agentId ? "agent" : "main", agentId: conv.agentId ?? null, convId: conv.id, convEpoch: 1, lifecycleEpoch: documents.lifecycleEpoch(conv.id),
+			sessionPath, durableSessionId: rt.durableId,
+		}, () => generation === this.generation && rt.sessionId === sessionId);
+		rt.documentIncarnation = issued.identity.sessionIncarnation;
+		const last = this.store.getEvent(this.store.lastSeq(conv.id, "main.input"));
+		const data = last?.data as { input_id?: unknown; session_path?: unknown } | undefined;
+		const inputId = typeof data?.input_id === "string" && data.session_path === sessionPath ? data.input_id : null;
+		if (last && inputId) documents.bindings.setInput(conv.id, issued.identity.sessionIncarnation, inputId, last.seq);
+		try {
+			const bound = await this.requireOmo().command<{ documentResolver?: unknown } | null>("extension_request", { sessionId, name: "zgw.attachment_bind", data: { secret: issued.secret, identity: issued.identity, inputId } });
+			const protocol = this.requireOmo().protocolInfo as { capabilities?: unknown } | null;
+			rt.documentResolver = bound?.documentResolver === true && Array.isArray(protocol?.capabilities) && protocol.capabilities.includes("document_content_v1");
+		} catch (error) {
+			documents.bindings.retire(conv.id);
+			rt.documentResolver = false;
+			console.error(`attachment read bind failed (${conv.id}): ${errorMessage(error)}`);
+		}
+	}
+
+	/** The extension signs with this id, so it must learn it before the native turn can call the tool. */
+	private async announceDocumentInput(sessionId: string, incarnation: string, inputId: string): Promise<void> {
+		try { await this.requireOmo().command("extension_request", { sessionId, name: "zgw.attachment_input", data: { sessionIncarnation: incarnation, inputId } }); }
+		catch (error) { console.error(`attachment read input failed: ${errorMessage(error)}`); }
+	}
+
 	/** Reserve gateway report admission before its HTTP body is parsed. The source
 	 * is not known yet, so this short request conservatively holds every conversation.
 	 * It never waits for a worker run or interrupts native work.
@@ -1115,6 +1573,8 @@ export class Hub {
 	notifyWorkUpdates(convId: string): Promise<void> {
 		if (this.maintenanceId) return Promise.resolve();
 		const rt = this.rt(convId);
+		const source = this.store.mainTurn(convId)?.source;
+		if (source && source.origin !== "user" && source.origin !== "work_update") return Promise.resolve();
 		if (this.omoStatus !== "ready") return Promise.resolve();
 		if (rt.rotating || this.closeUncertain(convId)) return Promise.resolve();
 		if (rt.waking) return rt.waking;
@@ -1139,6 +1599,7 @@ export class Hub {
 	}
 
 	private async injectWorkUpdates(convId: string, generation: number): Promise<void> {
+		this.collaboration?.retire(convId);
 		const conv = this.store.getConversation(convId);
 		if (!conv) return;
 		const { sessionId } = await this.ensureSession(conv);
@@ -1223,6 +1684,56 @@ export class Hub {
 		const generation = this.generation;
 		const run = rt.run;
 		const wake = rt.wake;
+		const authored = this.store.mainTurn(conv)?.inputs.filter(input => {
+			const data: MainInput = JSON.parse(JSON.stringify(input.data));
+			return data.origin !== "user" && data.origin !== "work_update";
+		}) ?? [];
+		if (authored.length) {
+			const [ledger, state, runtime] = await Promise.all([
+				this.currentLedger(conv, sessionId, generation),
+				this.requireOmo().command<{ isStreaming?: boolean; pendingMessageCount?: number }>("get_state", { sessionId }),
+				this.requireOmo().command<{ ownedInFlight?: number }>("extension_request", { sessionId, name: "zgw.agent_collaboration_runtime" }),
+			]);
+			if (!ledger || generation !== this.generation || rt.sessionId !== sessionId || rt.run !== run ||
+				state.isStreaming !== false || state.pendingMessageCount !== 0 || runtime.ownedInFlight !== 0) return;
+			for (const input of authored) {
+				const data: MainInput = JSON.parse(JSON.stringify(input.data));
+				const entry = this.ledgerInputEntry(ledger, data);
+				const after = entry && this.ledgerAfter(ledger, entry);
+				// The cooperative cancel interrupt ends its run with an aborted final message; that run is over, so it settles too.
+				// A stopped reply to a root requester executes no request, so nothing else could ever settle it.
+				const cancelInterrupted = !!after && turnAborted(after) && (data.origin === "agent_collaboration" || data.origin === "agent_tool_permission") &&
+					(this.store.cancelRequestedExecutions().some(execution => execution.activationId === data.input_ref.activation_id) ||
+						this.store.agentReplyWithoutExecution(data.input_ref.activation_id));
+				if (!entry || !after || !(turnFinished(after) || cancelInterrupted)) return;
+				const consumed = this.store.consumeMainInput(input, { entry, durableId: ledger.durableId });
+				if (consumed) this.publishStored(consumed);
+				switch (data.origin) {
+					case "agent_collaboration": case "agent_tool_permission": {
+						const activation = this.store.getAgentActivation(data.input_ref.activation_id);
+						if (activation?.binding && activation.state === "consumed" && !activation.quiesced) {
+							const evidence = { settlementId: `${ledger.durableId}:${ledger.leafId}`, ownedInFlight: runtime.ownedInFlight ?? -1, reconciled: true };
+							this.store.settleAgentActivation({ activationId: activation.id, expectedRevision: activation.revision, ...evidence }, activation.binding);
+							// A read held in this activation becomes resumable only at its exact settle.
+							for (const hold of this.store.unsettledArtifactHolds(activation.id)) {
+								this.store.settleArtifactRead(hold.id, evidence, activation.binding);
+								this.resumeArtifactReview(hold.id);
+							}
+							this.finalizeCollaboration(activation.id);
+						}
+						break;
+					}
+					case "collaboration_artifact_read": {
+						const binding = this.store.agentBinding(conv);
+						if (binding && binding.inputId === data.input_id) this.store.settleArtifactRead(data.input_ref.holdId,
+							{ settlementId: `${ledger.durableId}:${ledger.leafId}`, ownedInFlight: runtime.ownedInFlight, reconciled: true }, binding);
+						break;
+					}
+					case "user": case "work_update": break;
+					default: return collaborationNever(data);
+				}
+			}
+		}
 		try {
 			if (this.store.mainConsumedSource(conv)?.origin !== "user" &&
 				wake && !this.store.mainInputConsumed(wake.input)) {
@@ -1367,6 +1878,17 @@ export class Hub {
 		return { images, note: `[첨부 이미지 ${names.length}장: ${names.map((n) => `${where}/${n}`).join(", ")}]` };
 	}
 
+	/**
+	 * Opens an agent conversation's next session now, after a rotation that asked for it, so a saved definition is applied
+	 * without a user message (ensureSession records agent.applied). Main never opens here: its rotation behaviour is unchanged.
+	 */
+	async openAgentSession(convId: string): Promise<boolean> {
+		const conv = this.store.getConversation(convId);
+		if (!conv || conv.agentId === null) return false;
+		await this.ensureSession(conv);
+		return true;
+	}
+
 	/**
 	 * Moves the conversation to a fresh omo session file. The chat history stays; the old session file stays on disk,
 	 * and the next prompt carries a short note with the recent exchange (the handoff) so the new session has context.
@@ -1922,13 +2444,20 @@ export class Hub {
 	}
 
 	/** Sends input once. Native same-session compaction owns overflow recovery, never gateway replay. */
-	private async prompt(convId: string, body: string, images: string[] = [], messageSeq?: number, admitted = false, attachmentSnapshot?: ReturnType<Hub["attachments"]>, protectedPayload = false): Promise<void> {
+	private async prompt(convId: string, body: string, options: { readonly images?: string[]; readonly messageSeq?: number;
+		readonly admitted?: boolean; readonly attachmentSnapshot?: ReturnType<Hub["attachments"]>; readonly protectedPayload?: boolean;
+		readonly documents?: readonly AttachmentMetadata[];
+	} & ({ readonly collaboration?: NonNullable<ReturnType<Store["nextAgentInput"]>>; readonly artifactRead?: never } |
+		{ readonly artifactRead: import("./security-allow.ts").ArtifactSecurityHold; readonly collaboration?: never }) = {}): Promise<void> {
+		const { images = [], messageSeq, admitted = false, attachmentSnapshot, protectedPayload = false, documents = [], collaboration, artifactRead } = options;
+		const authored = collaboration !== undefined || artifactRead !== undefined;
 		this.requireVisibleAgent(convId);
 		const conv = this.store.getConversation(convId);
 		if (!conv) return;
 		const rt = this.rt(convId);
 		if (rt.rotating) return; // Accepted user intent remains definitely unsent until rotation finishes.
 		const generation = this.generation;
+		const run = rt.run;
 		let input: StoredEvent | null = null;
 		let nativeCommand = false;
 		let sessionId: string | null = null;
@@ -1941,39 +2470,96 @@ export class Hub {
 		try {
 			({ sessionId } = await this.ensureSession(conv));
 			if (generation !== this.generation || this.omoStatus !== "ready") return;
+			this.toolMigrationBeforeTurn(convId);
 			const reference = messageSeq ?? this.store.lastSeq(convId, "message.user");
 			// sendText and reconnect recovery can share admission; only one may cross the write boundary.
 			if (admitted && this.store.mainUserDispatched(convId, reference)) return;
 			const commandName = body.slice(1).split(" ", 1)[0];
-			nativeCommand = (body === "." && images.length === 0) ||
-				(body.startsWith("/") && (await this.commands(convId)).some((command) => command.name === commandName));
+			nativeCommand = !authored && ((body === "." && images.length === 0) ||
+				(body.startsWith("/") && (await this.commands(convId)).some((command) => command.name === commandName)));
 			if (generation !== this.generation || this.omoStatus !== "ready" || rt.sessionId !== sessionId) return;
 			if (admitted && this.store.mainUserDispatched(convId, reference)) return;
-			const handoff = nativeCommand ? null : this.store.getSessionMeta(convId).handoff;
+			const handoff = nativeCommand || authored ? null : this.store.getSessionMeta(convId).handoff;
 			const attached = attachmentSnapshot ?? this.attachments(images);
 			const text = [body, attached.note].filter(Boolean).join("\n\n");
 			const context = handoff ? `${handoff}\n\nZGW_WORK_STATE ${JSON.stringify(this.workSummary(convId))}` : null;
-			const inputId = crypto.randomUUID();
+			const inputId = collaboration?.activation.inputId ?? crypto.randomUUID();
 			const message = context ? `${context}\n\n[이번 메시지]\n${text}` : text;
 			const wire = nativeCommand || rt.clientInputIdentity ? message : `ZGW_MAIN_INPUT ${JSON.stringify({ input_id: inputId, message_seq: reference })}\n${message}`;
 			const params: Record<string, unknown> = {
 				sessionId, message: wire,
 				streamingBehavior: "steer",
-				sessionTitlePrompt: body,
+				...(!authored ? { sessionTitlePrompt: body } : {}),
 				...(rt.clientInputIdentity ? { clientInputId: inputId } : {}),
 			};
 			if (attached.images.length) params.images = attached.images;
-			input = this.emit(convId, "main.input", {
+			// Mac documents and their read binding belong to the owner's own input only; authored peer inputs never carry them.
+			const incarnation = !authored && this.options.documents ? rt.documentIncarnation : undefined;
+			if (!authored) {
+				const native = documents.filter((item) => item.readMode === "native-document");
+				if (native.length && this.options.documents && rt.clientInputIdentity) {
+					try { Object.assign(params, this.options.documents.dispatchDocuments(convId, native)); }
+					catch (error) { if (!(error instanceof AttachmentStoreError)) throw error; }
+				}
+				if (incarnation && sessionId) await this.announceDocumentInput(sessionId, incarnation, inputId);
+			}
+			if (authored) {
+				const lifecycle = this.collaboration;
+				if (!lifecycle) throw new CollaborationStoreError("collaboration_session_unavailable", 503);
+				this.checkCollaborationText(body);
+				const previousBinding = this.store.agentBinding(convId);
+				if (!rt.clientInputIdentity) throw new CollaborationStoreError("client_input_identity_unavailable", 503);
+				const context = collaboration ? { activationId: collaboration.activation.id,
+					requestId: collaboration.activation.direction === "reply" ? collaboration.request.parentId : collaboration.request.id,
+					rootId: collaboration.request.rootId } : { activationId: null, requestId: null, rootId: null };
+				await lifecycle.bind(convId, inputId, { ...context,
+					...(artifactRead ? { read: { continuationId: artifactRead.continuation.id, arguments: artifactRead.readArguments } } : {}),
+					claim: binding => {
+						if (generation !== this.generation || this.omoStatus !== "ready" || rt.sessionId !== sessionId ||
+							rt.running || rt.run !== run || rt.admitting !== 1 || rt.rotating || this.maintenanceId) {
+							throw new CollaborationStoreError("conversation_busy");
+						}
+						if (collaboration) {
+							const { activation, request } = collaboration;
+							input = this.store.admitAgentInput({ activationId: activation.id, activationRevision: activation.revision,
+								requestRevision: request.revision, previousBinding, wireMessage: wire, nativeIdentity: rt.clientInputIdentity },
+							binding, lifecycle.gate(request));
+						} else if (artifactRead && previousBinding) {
+							input = this.store.admitArtifactRead({ holdId: artifactRead.id, expectedRevision: artifactRead.revision,
+								previousBinding, wireMessage: wire }, binding, lifecycle.artifactRead(artifactRead));
+						} else throw new CollaborationStoreError("artifact_resume_conflict");
+						this.publishStored(input);
+					} });
+			} else input = this.emit(convId, "main.input", {
 				origin: "user", input_ref: { message_seq: reference },
 				session_path: this.store.getConversation(convId)?.threadId, handoff,
 				...(!nativeCommand || rt.clientInputIdentity ? {
 					input_id: inputId, wire_message: wire, native_identity: rt.clientInputIdentity,
 				} : {}),
 			});
+			if (incarnation && input) this.options.documents?.bindings.setInput(convId, incarnation, inputId, input.seq);
 			if (admitted) this.store.appendEvent(convId, "main.user.dispatched", { message_seq: reference, input_seq: input?.seq });
-			const receipt = await this.requireOmo().command<{ disposition?: string }>("prompt", params);
+			if (!authored) {
+				if (!nativeCommand && rt.clientInputIdentity) {
+					// The owner's own message never depends on collaboration capability: a refused bind only leaves the tools unbound.
+					try { await this.collaboration?.bind(convId, inputId); }
+					catch (error) {
+						if (!(error instanceof CollaborationStoreError) && !(error instanceof OmoCommandError)) throw error;
+						this.collaboration?.retire(convId);
+						this.emit(convId, "agent.collaboration.blocked", { code: error instanceof CollaborationStoreError ? error.code : "collaboration_native_unavailable" });
+					}
+				} else this.collaboration?.retire(convId);
+			}
+			const sent = this.requireOmo().command<{ disposition?: string }>("prompt", params);
+			if (collaboration) testCrashPoint("collaboration.input.rpc-written");
+			const receipt = await sent;
 			if (input && generation === this.generation && this.omoStatus === "ready" && rt.sessionId === sessionId) {
 				this.store.ackMainInput(input);
+				if (collaboration) {
+					const activation = this.store.getAgentActivation(collaboration.activation.id);
+					if (activation?.binding) this.store.recordAgentActivationEvidence({ activationId: activation.id,
+						expectedRevision: activation.revision, state: "acknowledged" }, activation.binding);
+				}
 				if (nativeCommand && receipt?.disposition === "handled") this.emit(convId, "main.input.handled", { input_seq: input.seq });
 				if (!rt.running && receipt?.disposition === "queued") void this.reconcileMainUsers(convId, sessionId, generation);
 			}
@@ -1989,11 +2575,35 @@ export class Hub {
 			if (refused && input) this.emit(convId, "main.input.handled", { input_seq: input.seq, reason: "prompt_rejected" });
 			if (protectedPayload) throw new SecurityRuntimeError("dispatch_unknown");
 			if (retired) return;
+			if (collaboration) {
+				const activation = this.store.getAgentActivation(collaboration.activation.id);
+				if (error instanceof CollaborationStoreError && ["target_forbidden", "lifecycle_conflict", "agent_access_blocked",
+					"authority_epoch_mismatch", "collaboration_security_review_required", "version_conflict"].includes(error.code)) {
+					this.store.rejectQueuedAgentInput(collaboration.activation.id, error.code);
+					this.wakeCollaborationReplies();
+				}
+				if (activation?.binding && activation.state !== "queued") this.store.recordAgentActivationEvidence({
+					activationId: activation.id, expectedRevision: activation.revision, state: "unknown" }, activation.binding);
+				if (error instanceof CollaborationStoreError) this.emit(convId, "agent.collaboration.blocked", { code: error.code });
+				else this.emit(convId, "agent.collaboration.blocked", { code: "dispatch_unknown" });
+				return;
+			}
+			if (artifactRead) {
+				const hold = this.store.artifactSecurityHold(artifactRead.id);
+				if (hold?.continuation.state === "dispatched" && hold.continuation.targetBinding) this.store.recordArtifactDelivery({
+					holdId: hold.id, dispatchReceiptId: hold.continuation.dispatchReceiptId,
+					releaseReceiptId: hold.continuation.releaseReceiptId, state: "unknown" }, hold.continuation.targetBinding);
+				this.emit(convId, "agent.collaboration.blocked", { code: error instanceof CollaborationStoreError ? error.code : "dispatch_unknown",
+					holdId: artifactRead.id });
+				return;
+			}
 			if (error instanceof AgentSessionError) return; // The definition failure was already persisted and broadcast.
 			const message = errorMessage(error);
 			this.emit(convId, "error", refused ? { kind: "compaction-required", message: say(COMPACTION_REQUIRED_MESSAGE) } : this.continuityError(message));
 		} finally {
 			releaseAdmission();
+			// An owner input that superseded a peer execution ended that request and queued its requester's reply.
+			if (!authored) { void this.dispatchCollaboration(convId); this.wakeCollaborationReplies(); }
 		}
 	}
 
@@ -2026,7 +2636,19 @@ export class Hub {
 		if (this.maintenanceId) throw new MaintenanceError("maintenance_held");
 		const rt = this.rt(convId);
 		if (!rt.sessionId || !rt.running) return;
-		await this.requireOmo().command("abort", { sessionId: rt.sessionId });
+		// Stopping a run that executes a peer request is the owner cancelling that request: it is recorded before the abort,
+		// so the aborted run settles once on the cancel path and the requester gets one result-less final reply.
+		const activationId = this.store.agentBinding(convId)?.activationId ?? null;
+		const executing = activationId !== null && (this.store.mainTurn(convId)?.inputs.some(input => {
+			const data: MainInput = JSON.parse(JSON.stringify(input.data));
+			return (data.origin === "agent_collaboration" || data.origin === "agent_tool_permission") && data.input_ref.activation_id === activationId;
+		}) ?? false);
+		const cancelled = executing ? this.store.cancelStoppedAgentExecution(convId, activationId, "owner_stopped") : null;
+		if (cancelled) {
+			this.wakeCollaborationReplies();
+			// Aborts this run and any running execution of a child cancelled with it.
+			await this.interruptCancelledCollaboration();
+		} else await this.requireOmo().command("abort", { sessionId: rt.sessionId });
 		this.dialogs.cancelScope(this.conversationScope(convId), say(HUB_TEXT.userStopped));
 	}
 
@@ -2140,7 +2762,7 @@ export class Hub {
 		return this.dialogs.answer(request.actionId, answer);
 	}
 
-	onEvent(event: OmoEvent): void | Promise<void> {
+	async onEvent(event: OmoEvent): Promise<void> {
 		this.eventCount += 1;
 		const sessionId = typeof event.sessionId === "string" ? event.sessionId : null;
 		const conv = sessionId ? this.sessionToConv.get(sessionId) : undefined;
@@ -2210,7 +2832,20 @@ export class Hub {
 				if (message?.role === "user") {
 					const input = this.store.mainUserInput(conv, owner.sessionPath, contentText(message.content), message.clientInputId);
 					if (input) {
-						const consumed = this.store.consumeMainInput(input);
+						const data: MainInput = JSON.parse(JSON.stringify(input.data));
+						let native: { entry: LedgerEntry; durableId: string } | undefined;
+						switch (data.origin) {
+							case "user": case "work_update": break;
+							case "agent_collaboration": case "agent_tool_permission": case "collaboration_artifact_read": {
+								const ledger = await this.currentLedger(conv, sessionId, this.generation);
+								const entry = ledger && this.ledgerInputEntry(ledger, data);
+								if (!ledger || !entry) return;
+								native = { entry, durableId: ledger.durableId };
+								break;
+							}
+							default: return collaborationNever(data);
+						}
+						const consumed = this.store.consumeMainInput(input, native);
 						if (consumed) this.publishStored(consumed);
 						this.startMainTurn(conv);
 					}
@@ -2307,18 +2942,34 @@ export class Hub {
 				return;
 			}
 			case "agent_settled": {
+				const source = this.store.mainTurn(conv)?.source;
+				if (source && source.origin !== "user" && source.origin !== "work_update") {
+					const generation = this.generation, run = rt.run;
+					const state = await this.requireOmo().command<{ isStreaming?: boolean; pendingMessageCount?: number }>("get_state", { sessionId });
+					if (generation !== this.generation || rt.run !== run || rt.sessionId !== sessionId ||
+						state.isStreaming !== false || state.pendingMessageCount !== 0) return;
+				}
+				this.collaboration?.retire(conv);
 				rt.running = false;
 				rt.statsTurnId = null;
 				rt.statsMessageIndex = 0;
 				this.publishActivity(conv);
 				this.unwatchConversation(conv);
 				this.dialogs.cancelScope(owner.scope, say(HUB_TEXT.turnEnded));
+				this.toolMigrationIdle(conv);
 				if (this.decisions) {
+					const settledPath = this.store.getConversation(conv)?.threadId;
 					void this.reconcileDecisionMain(conv)
-						.then(() => this.decisions?.settled(owner.scope))
+						.then(() => { if (this.store.getConversation(conv)?.threadId === settledPath) this.decisions?.settled(owner.scope); })
 						.catch((error) => console.error("main decision reconciliation:", error));
 				}
-				const settled = this.settleMainTurn(conv, sessionId);
+				this.settling.set(conv, (this.settling.get(conv) ?? 0) + 1);
+				const settled = this.settleMainTurn(conv, sessionId).finally(() => {
+					const remaining = (this.settling.get(conv) ?? 1) - 1;
+					if (remaining) this.settling.set(conv, remaining);
+					else this.settling.delete(conv);
+					void this.dispatchCollaboration(conv);
+				});
 				return conv === "main" && this.modelPending
 					? Promise.all([settled, this.refreshPendingModel()]).then(() => undefined)
 					: settled;
@@ -2328,6 +2979,8 @@ export class Hub {
 				return;
 			case "session_closed":
 			case "session_parked":
+				this.collaboration?.retire(conv);
+				this.collaborationIncarnations.delete(conv);
 				this.sessionToConv.delete(sessionId);
 				this.releaseScopedUiOwner(owner);
 				rt.sessionId = null;
@@ -2403,6 +3056,7 @@ export class Hub {
 				...(event.nativePermission ? { nativePermission: event.nativePermission } : {}) },
 			deadlineAt: typeof event.timeout === "number" ? Date.now() + event.timeout : request.deadlineAt,
 		});
+		if (decision) this.linkCollaborationQuestion(owner.conv, decision.id);
 		this.emit(owner.conv, "action.request", decision ? { ...request, decisionId: decision.id } : request);
 	}
 
@@ -2419,6 +3073,19 @@ export class Hub {
 		this.emit(owner.conv, "action.resolved", resolution);
 	}
 
+	/**
+	 * A question asked inside a collaboration execution holds that request (and its descendants) in waiting_owner until
+	 * the owner's real answer; independent requests keep running. A refused link is reported, never treated as an answer.
+	 */
+	private linkCollaborationQuestion(conv: string, decisionId: string): void {
+		try {
+			if (this.store.linkCurrentAgentDecision(conv, decisionId)) this.emit(conv, "agent.collaboration.waiting_owner", { decisionId });
+		} catch (error) {
+			if (!(error instanceof CollaborationStoreError)) throw error;
+			this.emit(conv, "agent.collaboration.blocked", { code: error.code, decisionId });
+		}
+	}
+
 	/** Shows an ask_user_question card once; a replay of a card already in the conversation history only re-arms it. */
 	private openQuestion(owner: ScopedUiOwner, frame: ScopedQuestionFrame): void {
 		const actionId = scopedActionId(owner.scope, frame.id);
@@ -2448,6 +3115,7 @@ export class Hub {
 				...(frame.waitForAnswer === false ? { waitForAnswer: false } : {}) },
 			deadlineAt: frame.deadlineAtMs ?? null,
 		});
+		if (decision) this.linkCollaborationQuestion(owner.conv, decision.id);
 		const open = this.openQuestionCards(owner.conv, owner.scope);
 		if (open.has(frame.id)) this.legacyQuestionHistoryAliases.set(actionId, frame.id);
 		if (!open.has(actionId) && !open.has(frame.id)) {
@@ -2461,6 +3129,23 @@ export class Hub {
 		}
 	}
 
+	/**
+	 * Bug 236: a newer instruction was queued behind this work's turn. Each required question the turn waits on ends its
+	 * native wait (the queued instruction then runs at the tool boundary) and stays open in the inbox.
+	 */
+	releaseScopedQuestions(owner: ScopedUiOwner): void {
+		if (!this.isCurrentScopedUiOwner(owner)) return;
+		for (const [actionId, card] of [...this.questions]) {
+			if (card.scope !== owner.scope || card.targetSessionPath !== owner.sessionPath) continue;
+			const decision = this.store.getDecisionBySource({ scope: owner.scope, sourceSessionPath: owner.sessionPath, sourceRequestId: card.sourceRequestId });
+			if (!decision || !this.decisions?.releaseWorkWait(decision.id)) continue;
+			this.questions.delete(actionId);
+			this.legacyQuestionHistoryAliases.delete(actionId);
+			this.releasedQuestions.add(actionId);
+			this.omo?.send({ type: "extension_ui_response", id: card.sourceRequestId, sessionId: owner.sessionId, answers: {}, comment: WORK_QUESTION_RELEASED });
+		}
+	}
+
 	private answerQuestion(card: QuestionCard, data: ActionAnswerData): boolean {
 		const owner = this.currentScopedUiOwner(card.scope, card.targetSessionPath);
 		if (!owner || !this.omo) return false;
@@ -2596,6 +3281,22 @@ export class Hub {
 		if (!ledger) throw new Error("session_history_unavailable");
 		const currentTurn = this.store.mainTurn(conv.id);
 		if (!currentTurn || currentTurn.seq !== turn.seq) return;
+		switch (turn.source.origin) {
+			case "agent_collaboration": case "agent_tool_permission": case "collaboration_artifact_read":
+				// Reconcile exact evidence only. Recovery never creates a replacement peer input.
+				for (const input of turn.inputs) {
+					const data: MainInput = JSON.parse(JSON.stringify(input.data));
+					const entry = this.ledgerInputEntry(ledger, data);
+					if (!entry) continue;
+					const consumed = this.store.consumeMainInput(input, { entry, durableId: ledger.durableId });
+					if (consumed) this.publishStored(consumed);
+				}
+				// A native run that finished while no gateway was attached sends no later agent_end; settle it on the same evidence.
+				if (!streaming) await this.settleMainTurn(conv.id, sessionId);
+				return;
+			case "user": case "work_update": break;
+			default: return collaborationNever(turn.source);
+		}
 		const workInputs = turn.inputs.filter((input) => (input.data as MainInput).origin === "work_update");
 		for (const input of workInputs) {
 			const data = input.data as MainInput;
@@ -2688,7 +3389,7 @@ export class Hub {
 		const lastUser = this.store.getEvent(turn.source.input_ref.message_seq)?.data as { text?: string; images?: string[] } | undefined;
 		const message = promptReached || !lastUser?.text ? CONTINUE_PROMPT : lastUser.text;
 		this.emit(conv.id, "notice", { kind: "auto-continue", level: "warning", message: say(HUB_TEXT.autoContinue, { attempt: tries + 1, limit: AUTO_CONTINUE_LIMIT, recovered: recoveredNote(recovered) }) });
-		await this.prompt(conv.id, message, promptReached ? [] : lastUser?.images ?? [], turn.source.input_ref.message_seq);
+		await this.prompt(conv.id, message, { images: promptReached ? [] : lastUser?.images ?? [], messageSeq: turn.source.input_ref.message_seq });
 	}
 
 	private hasUnfinishedTurn(conv: string): boolean {
@@ -2812,7 +3513,12 @@ export class Hub {
 	}
 
 	private ledgerInputEntry(ledger: LedgerState, data: MainInput): LedgerEntry | null {
-		if (data.origin !== "user" || typeof data.input_id !== "string") return null;
+		switch (data.origin) {
+			case "work_update": return null;
+			case "user": case "agent_collaboration": case "agent_tool_permission": case "collaboration_artifact_read": break;
+			default: return collaborationNever(data);
+		}
+		if (typeof data.input_id !== "string" || data.session_path !== ledger.sessionPath) return null;
 		if (data.native_identity) return this.store.ledgerUser(ledger.sessionPath, { clientInputId: data.input_id });
 		return typeof data.wire_message === "string" ? this.store.ledgerUser(ledger.sessionPath, { text: data.wire_message }) : null;
 	}
@@ -2893,6 +3599,8 @@ export class Hub {
 				throw new AgentSessionError();
 			}
 		}
+		const resumed = existsSync(sessionPath);
+		const agentMode = conv.agentId ? this.store.toolPermissions.mode(conv.agentId) : null;
 		const opened = this.requireOmo().command<{ sessionId: string; attached?: boolean; state?: {
 			isStreaming?: boolean; pendingQuestions?: ScopedQuestionFrame[];
 			clientInputIdentity?: boolean; atomicQueuedResume?: boolean;
@@ -2903,15 +3611,16 @@ export class Hub {
 			...(model ?? {}),
 			...(typeof agent?.fields.thinking === "string" ? { thinkingLevel: agent.fields.thinking } : {}),
 			cwd,
-			permissionPreset: this.options.permissionPreset,
+			permissionPreset: agentSessionPreset(this.options.permissionPreset, agentMode),
 			retain_on_disconnect: true,
 			kind: "interactive",
 			promptSurface: "app",
 			context: conv.agentId
-				? { zgw_conv: conv.id, zgw_role: "agent", zgw_agent: conv.agentId }
+				// C6: the session's adapter learns that the agent authority (not a native preset) governs it.
+				? { zgw_conv: conv.id, zgw_role: "agent", zgw_agent: conv.agentId, ...(agentMode === "managed" ? { zgw_tool_authority: "managed" } : {}) }
 				: { zgw_conv: conv.id, zgw_role: "main" },
 		});
-		return { sessionPath, opened, agent };
+		return { sessionPath, opened, agent, resumed };
 	}
 
 	private watchAsk(conv: string, toolCallId: string, args: unknown): void {
@@ -2964,12 +3673,13 @@ export class Hub {
 		if (rt.sessionId) return { sessionId: rt.sessionId, streaming: rt.running };
 		if (rt.opening) return rt.opening;
 		const generation = this.generation;
-		const { sessionPath, opened, agent } = this.openSession(conv);
+		const { sessionPath, opened, agent, resumed } = this.openSession(conv);
 		const opening = opened
 			.then(async (data) => {
 				if (generation !== this.generation || this.omoStatus !== "ready") throw new Error("stale_open_session");
 				rt.sessionId = data.sessionId;
 				rt.durableId = typeof data.state?.sessionId === "string" ? data.state.sessionId : null;
+				this.collaborationIncarnations.set(conv.id, crypto.randomUUID());
 				rt.clientInputIdentity = data.state?.clientInputIdentity === true;
 				rt.atomicQueuedResume = data.state?.atomicQueuedResume === true;
 				this.sessionToConv.set(data.sessionId, conv.id);
@@ -2980,19 +3690,65 @@ export class Hub {
 				}
 				const owner = { conv: conv.id, scope: this.conversationScope(conv.id), sessionId: data.sessionId, sessionPath };
 				if (!this.bindScopedUiOwner(owner)) throw new Error("omo_owner_not_ready");
-				if (agent && data.attached !== true) {
-					// Notification policy is a session snapshot too; edits must not change a live session.
-					this.emit(conv.id, "agent.applied", { sha: agent.sha, at: new Date(this.now()).toISOString(), notify: agent.fields.notify === true });
+				await this.bindDocuments(conv, data.sessionId, sessionPath, rt, generation);
+				await this.bindAgentTools(conv, data.sessionId, sessionPath, rt, generation);
+				if (agent) {
+					const rotated = this.store.lastSeq(conv.id, "session.rotated");
 					let warnings: { code: string; message: string }[] = [];
+					let appliedSha: string | undefined;
 					try {
-						const result = await this.requireOmo().command<{ warnings?: { code: string; message: string }[] } | null>(
+						const result = await this.requireOmo().command<{ warnings?: { code: string; message: string }[]; appliedSha?: unknown } | null>(
 							"extension_request", { sessionId: data.sessionId, name: "zgw.agent_warnings" });
+						if (typeof result?.appliedSha === "string") appliedSha = result.appliedSha;
 						if (Array.isArray(result?.warnings)) warnings = result.warnings;
 						else console.error(`agent startup warnings failed (${conv.id}): invalid warnings response`);
 					} catch (error) {
 						console.error(`agent startup warnings failed (${conv.id}): ${errorMessage(error)}`);
 					}
-					for (const warning of warnings) this.emit(conv.id, "notice", { kind: "agent-warning", level: "warning", ...warning });
+					// A report belongs to the session that requested it, even if a native handle is reused.
+					if (generation !== this.generation || rt.sessionId !== data.sessionId ||
+						rotated !== this.store.lastSeq(conv.id, "session.rotated")) throw new Error("stale_open_session");
+					const last = this.store.eventsAfter(conv.id, this.store.lastSeq(conv.id, "session.rotated"))
+						.filter(event => event.type === "agent.applied").at(-1)?.data;
+					const previous = typeof last === "object" && last !== null ? last : undefined;
+					let snapshot: Record<string, unknown> | undefined;
+					if (data.attached !== true && !resumed) {
+						// Only a new file uses creation defaults. Old extensions retain the open-time fallback.
+						snapshot = appliedSha === undefined || appliedSha === agent.sha
+							? { sha: agent.sha, model: agent.fields.model ?? null, thinking: agent.fields.thinking ?? null }
+							: { sha: null, mixed: true };
+					} else if (appliedSha !== undefined) {
+						if (data.attached === true) {
+							// A retained native session never reloads its creation controls.
+							if (previous && "sha" in previous && previous.sha !== appliedSha) snapshot = { sha: null, mixed: true };
+						} else if (!previous || !("sha" in previous) || previous.sha !== appliedSha) {
+							// Cold resume reloads the extension, but keeps the model/thinking in the file.
+							let loaded = agent;
+							if (loaded.sha !== appliedSha && conv.agentId) {
+								try {
+									const files = this.options.agents ?? new AgentFileStore();
+									loaded = mergeAgentDefinition(files.read(conv.agentId), files.readDefaults());
+								} catch {
+									// A concurrent invalid save cannot prove which definition the extension loaded.
+									console.error(`agent resumed definition unavailable (${conv.id})`);
+								}
+							}
+							snapshot = loaded.sha === appliedSha && previous && "model" in previous && "thinking" in previous &&
+								isDeepStrictEqual(previous.model, loaded.fields.model ?? null) && previous.thinking === (loaded.fields.thinking ?? null)
+								? { sha: appliedSha, model: loaded.fields.model ?? null, thinking: loaded.fields.thinking ?? null }
+								: { sha: null, mixed: true };
+						}
+					}
+					if (snapshot) {
+						// Reattachment does not change the live notification policy.
+						const notify = data.attached === true
+							? previous !== undefined && "notify" in previous && previous.notify === true
+							: agent.fields.notify === true;
+						this.emit(conv.id, "agent.applied", { ...snapshot, at: new Date(this.now()).toISOString(), notify });
+					}
+					if (data.attached !== true) {
+						for (const warning of warnings) this.emit(conv.id, "notice", { kind: "agent-warning", level: "warning", ...warning });
+					}
 				}
 				this.syncScopedQuestions(owner, data.state?.pendingQuestions ?? []);
 				this.publishActivity(conv.id);
@@ -3024,6 +3780,84 @@ export class Hub {
 		return rt;
 	}
 
+	/** 294: host-only engine commands for the conversation's current session; null while it has none. */
+	agentToolEngine(convId: string): ((type: string, params: Record<string, unknown>) => Promise<unknown>) | null {
+		const sessionId = this.runtime.get(convId)?.sessionId;
+		if (!sessionId || this.omoStatus !== "ready") return null;
+		return (type, params) => this.requireOmo().command(type, { ...params, sessionId });
+	}
+
+	/**
+	 * 294 item 11: the migration card of a legacy agent, built from its current definition (C9). The same open card is
+	 * returned again; a managed agent (new, clone, or already switched) gets null. Creating the card grants nothing and
+	 * never blocks or restarts a running turn.
+	 */
+	ensureToolMigration(agentId: string, files: AgentFileStore = this.options.agents ?? new AgentFileStore()): AgentToolMigrationCard | null {
+		const ledger = this.store.toolPermissions;
+		const current = ledger.currentMigration(agentId);
+		if (current && current.state !== "applied") return current;
+		if (ledger.mode(agentId) === "managed") return null;
+		const conv = this.store.listConversations(true).find((row) => row.agentId === agentId);
+		if (!conv) return null;
+		const merged = mergeAgentDefinition(files.read(agentId), files.readDefaults());
+		const card = this.store.createAgentToolMigration(agentId, conv.id, legacyToolScopes(merged, join(files.root, agentId, "knowledge")));
+		this.decisions?.refresh();
+		return card;
+	}
+
+	/**
+	 * 294 item 11: an idle conversation about to start a turn is also an idle boundary, so a card answered while the agent
+	 * was idle applies to the next turn. A prompt steered into a running turn switches nothing; that turn ends legacy.
+	 */
+	toolMigrationBeforeTurn(convId: string): void {
+		if (!this.rt(convId).running) this.toolMigrationIdle(convId);
+	}
+
+	/** 294 item 11: the idle boundary after a turn. An answered migration card switches its agent to managed here only. */
+	toolMigrationIdle(convId: string): void {
+		const agentId = this.store.getConversation(convId)?.agentId;
+		if (!agentId) return;
+		try {
+			if (this.store.toolPermissions.applyMigrationAtIdle(agentId)) this.decisions?.refresh();
+		} catch (error) {
+			console.error(`agent tool migration switch failed (${convId}): ${errorMessage(error)}`);
+		}
+	}
+
+	/** 294: rotates the agent session's internal-route secret on every native open; a failed bind leaves only refused calls. */
+	private async bindAgentTools(conv: ConversationInfo, sessionId: string, sessionPath: string, rt: ConvRuntime, generation: number): Promise<void> {
+		if (conv.agentId) {
+			try {
+				this.ensureToolMigration(conv.agentId);
+			} catch (error) {
+				console.error(`agent tool migration card failed (${conv.id}): ${errorMessage(error)}`);
+			}
+		}
+		const agentTools = this.options.agentTools;
+		if (!agentTools || !conv.agentId || !rt.durableId) return;
+		const issued = agentTools.bindings.bind({
+			role: "agent", agentId: conv.agentId, convId: conv.id, convEpoch: 1, lifecycleEpoch: this.store.toolPermissions.policyGrants(conv.agentId).view.lifecycleEpoch,
+			sessionPath, durableSessionId: rt.durableId,
+		}, () => generation === this.generation && rt.sessionId === sessionId);
+		try {
+			await this.requireOmo().command("extension_request", { sessionId, name: "zgw.agent_tool_bind", data: { secret: issued.secret, identity: issued.identity } });
+		} catch (error) {
+			agentTools.bindings.retire(conv.id);
+			console.error(`agent tool bind failed (${conv.id}): ${errorMessage(error)}`);
+			return;
+		}
+		// D2: the authority is in place before the first turn, so an ungranted call is held for consent, not refused.
+		try {
+			const omo = this.requireOmo();
+			const pushed = await pushSessionPolicy({ ledger: this.store.toolPermissions, engine: engineCommands((type, params) => omo.command(type, { ...params, sessionId })) },
+				{ agentId: conv.agentId, durableSessionId: rt.durableId });
+			if (pushed.state === "policy_unacknowledged") console.error(`agent tool policy not acknowledged (${conv.id}): revision ${pushed.revision}`);
+		} catch (error) {
+			console.error(`agent tool policy push failed (${conv.id}): ${errorMessage(error)}`);
+		}
+		agentTools.ready?.(conv.id);
+	}
+
 	private nextId(prefix: string): string {
 		return `${prefix}${Date.now().toString(36)}${(this.counter++).toString(36)}`;
 	}
@@ -3062,7 +3896,11 @@ export class Hub {
 				console.error(`transcript append failed (${conv}): ${errorMessage(error)}`);
 			}
 		}
-		this.broadcast({ v: PROTOCOL_VERSION, id: this.nextId("e"), ts: stored.ts, conv, type, data, seq: stored.seq });
+		this.broadcast({ v: PROTOCOL_VERSION, id: this.nextId("e"), ts: stored.ts, conv, type, data: this.withAttachmentState(stored).data, seq: stored.seq });
+	}
+
+	private withAttachmentState(stored: StoredEvent): StoredEvent {
+		return stored.type === "message.user" ? { ...stored, data: this.store.attachments.withGrantState(stored.data) } : stored;
 	}
 }
 
@@ -3143,12 +3981,228 @@ function turnFinished(entries: readonly LedgerEntry[]): boolean {
 	return last?.role === "assistant" && last.stopReason === "stop";
 }
 
+function turnAborted(entries: readonly LedgerEntry[]): boolean {
+	const last = entries.filter((entry) => entry.type === "message").at(-1);
+	return last?.role === "assistant" && last.stopReason === "aborted";
+}
+
 /** The sentence added to a recovery notice for answers the gateway filled in while it was away (exported for tests). */
 export function recoveredNote(count: number): string {
 	if (count <= 0) return "";
 	return count === 1 ? say(HUB_TEXT.recoveredOne) : say(HUB_TEXT.recoveredMany, { count });
 }
 
+/**
+ * 294 C6: a registered agent under managed tool permissions has one authority, the gateway's agent authority, which runs
+ * before every native hook. Its session therefore opens full-access, so an owner-allowed stored call is not asked a second
+ * time by a native preset prompt nobody answers. Main, work and legacy agents keep the gateway preset.
+ */
+export function agentSessionPreset(gatewayPreset: string, agentMode: "legacy" | "managed" | null): string {
+	return agentMode === "managed" ? "full-access" : gatewayPreset;
+}
+
 function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
+
+export const AGENT_TOOL_INTERNAL_ROUTES: Readonly<Record<string, { method: "GET" | "POST"; operation: string }>> = {
+	"/internal/agent-tools/request": { method: "POST", operation: "agent_tool.request" },
+	"/internal/agent-tools/action": { method: "POST", operation: "agent_tool.action" },
+	"/internal/agent-tools/reserve": { method: "POST", operation: "agent_tool.reserve" },
+	"/internal/agent-tools/start": { method: "POST", operation: "agent_tool.start" },
+	"/internal/agent-tools/result": { method: "POST", operation: "agent_tool.result" },
+	"/internal/agent-tools/policy": { method: "GET", operation: "agent_tool.policy" },
+	"/internal/agent-tools/policy-ack": { method: "POST", operation: "agent_tool.policyAck" },
+};
+
+interface AgentToolLive { readonly session: ManagedSession; readonly incarnation: string; readonly secret: KeyObject; readonly live: () => boolean; readonly nonces: Set<string> }
+
+/**
+ * 294 custody of the agent session secrets for /internal/agent-tools/*. Each bind rotates the secret; a call is accepted
+ * only for an agent role, the live incarnation of this gateway generation, and a logical call id tied to its tool call.
+ */
+export class AgentToolBindings {
+	readonly generation = randomUUID();
+	private readonly byConv = new Map<string, AgentToolLive>();
+	bind(session: ManagedSession, live: () => boolean): { secret: string; identity: Omit<ManagedCallIdentity, "inputId" | "toolCallId" | "logicalCallId" | "activationId"> } {
+		const raw = randomBytes(32), incarnation = randomUUID();
+		this.byConv.set(session.convId, { session, incarnation, secret: createSecretKey(raw), live, nonces: new Set() });
+		return { secret: raw.toString("hex"), identity: { ...session, sessionIncarnation: incarnation, gatewayGeneration: this.generation } };
+	}
+	retire(convId: string): void { this.byConv.delete(convId); }
+	readonly resolver: ManagedCallBindingResolver = (identity): ManagedCallBinding | null => {
+		const record = this.byConv.get(identity.convId);
+		if (!record || !record.live() || record.session.role !== "agent" || record.session.agentId === null ||
+			identity.logicalCallId !== `agent-tool:${identity.toolCallId}`) return null;
+		return {
+			identity: { ...record.session, sessionIncarnation: record.incarnation, gatewayGeneration: this.generation,
+				inputId: identity.inputId, toolCallId: identity.toolCallId, logicalCallId: identity.logicalCallId, activationId: identity.activationId },
+			secret: record.secret,
+			claimNonce: (nonce) => {
+				if (record.nonces.has(nonce) || record.nonces.size >= 65_536) return false;
+				record.nonces.add(nonce);
+				return true;
+			},
+		};
+	};
+}
+
+const agentToolRefuse = (error: string, status: number) => Response.json({ error }, { status, headers: { "Cache-Control": "no-store" } });
+const agentToolText = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const agentToolInt = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+const agentToolRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const agentToolLabel = (value: unknown): value is string => typeof value === "string" && value.length <= 200;
+export type AgentToolActionScope = { operation: "click" | "fill"; args: Record<string, unknown>; scope: Record<string, string> };
+
+/**
+ * C8: the card scope of a click/fill the session prepared on a granted target. The owner sees the element and the exact
+ * value; the target handle stays opaque. Anything malformed is refused, never shown partly. The scope kind follows the session's
+ * own target: a work tab the session opened is `owned_target` (delivery never looks it up in the gateway registry, which holds
+ * only borrowed tabs); a tab the owner designated is `browser_target` and still needs its gateway-bound handle.
+ */
+export function agentToolActionScope(input: Record<string, unknown>): AgentToolActionScope {
+	const { operation, args, target, element } = input;
+	if ((operation !== "click" && operation !== "fill") || !agentToolRecord(args) || args.operation !== operation || !agentToolText(args.targetHandle) ||
+		!agentToolRecord(target) || !agentToolText(target.origin) || target.origin.length > 2048 || (target.kind !== "owned" && target.kind !== "borrowed") || !agentToolRecord(element) ||
+		!agentToolLabel(element.tag) || !agentToolLabel(element.role) || !agentToolLabel(element.name) || (operation === "fill") !== agentToolText(args.text)) {
+		throw new AgentToolPermissionError("tool_request_invalid");
+	}
+	const label = `${element.tag}${element.role ? ` [${element.role}]` : ""}${element.name ? ` "${element.name}"` : ""}`;
+	return { operation, args, scope: { kind: target.kind === "owned" ? "owned_target" : "browser_target", targetHandle: args.targetHandle, targetLabel: target.origin, element: label, ...(operation === "fill" ? { value: args.text as string } : {}) } };
+}
+
+/**
+ * 294 C3 internal routes. Listener and bearer first, then the signed session identity (shared managed-call verifier).
+ * The agent, conversation and session come from the verified identity only; body agent names are never read.
+ * Policy ACKs are kept per durable session in memory: a gateway restart means the engine must ACK again.
+ */
+export class AgentToolInternalApi {
+	constructor(private readonly d: {
+		readonly store: Store;
+		readonly resolver: ManagedCallBindingResolver;
+		readonly omoToken: string;
+		readonly changed: () => void;
+		readonly policy: (view: AgentAccessView, grants: readonly AgentToolGrantRow[]) => unknown;
+	}) {}
+
+	static route(pathname: string): boolean { return Object.hasOwn(AGENT_TOOL_INTERNAL_ROUTES, pathname); }
+
+
+	async handle(req: Request, trusted: boolean): Promise<Response> {
+		const denied = maintenanceAuth(req, trusted, this.d.omoToken);
+		if (denied) return denied;
+		const route = new URL(req.url).pathname;
+		const spec = AGENT_TOOL_INTERNAL_ROUTES[route];
+		if (!spec) return agentToolRefuse("not_found", 404);
+		if (req.method !== spec.method) return agentToolRefuse("method_not_allowed", 405);
+		const body = new Uint8Array(await req.arrayBuffer());
+		if (body.byteLength > 64 * 1024) return agentToolRefuse("tool_request_too_large", 413);
+		let call: VerifiedManagedCall;
+		try {
+			let proof: unknown;
+			try { proof = JSON.parse(Buffer.from(req.headers.get("x-zigmini-managed-call") ?? "", "base64").toString("utf8")); }
+			catch { throw new ManagedCallError("invalid_proof"); }
+			call = verifyManagedCall({ method: spec.method, route, operation: spec.operation, body, proof }, this.d.resolver);
+		} catch (error) {
+			if (error instanceof ManagedCallError) return agentToolRefuse(error.code, error.code === "invalid_proof" ? 401 : 403);
+			throw error;
+		}
+		if (call.role !== "agent" || call.agentId === null) return agentToolRefuse("agent_role_required", 403);
+		let input: Record<string, unknown> = {};
+		if (spec.method === "POST") {
+			const parsed: unknown = (() => { try { return JSON.parse(new TextDecoder().decode(body)); } catch { return null; } })();
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return agentToolRefuse("tool_request_invalid", 400);
+			input = parsed as Record<string, unknown>;
+		}
+		try {
+			return Response.json(this.run(route, call, call.agentId, input), { headers: { "Cache-Control": "no-store" } });
+		} catch (error) {
+			if (error instanceof AgentToolPermissionError) return agentToolRefuse(error.code, error.status);
+			if (error instanceof CollaborationStoreError) return agentToolRefuse(error.code, error.status);
+			throw error;
+		}
+	}
+
+	private owned(agentId: string, invocationId: unknown): string {
+		if (!agentToolText(invocationId)) throw new AgentToolPermissionError("tool_request_invalid");
+		const invocation = this.d.store.toolPermissions.invocation(invocationId);
+		if (!invocation || invocation.agentId !== agentId) throw new AgentToolPermissionError("invocation_not_found");
+		return invocationId;
+	}
+
+	private policyOf(agentId: string): { revision: number; policy: unknown } {
+		const { view, grants } = this.d.store.toolPermissions.policyGrants(agentId);
+		// The engine requires revision >= 1, so an agent with no permission change yet is revision 1 on both sides.
+		return { revision: Math.max(view.policyRevision, 1), policy: this.d.policy(view, grants) };
+	}
+
+	private run(route: string, call: VerifiedManagedCall, agentId: string, input: Record<string, unknown>): unknown {
+		const ledger = this.d.store.toolPermissions;
+		switch (route) {
+			case "/internal/agent-tools/request": {
+				if (!agentToolText(input.operation) || typeof input.toolKey !== "object" || input.toolKey === null) {
+					throw new AgentToolPermissionError("tool_request_invalid");
+				}
+				// Q-07: a call signed with a collaboration activation must name its request (and only such a call may).
+				const activationId = call.activationId, collaborationRequestId = input.collaborationRequestId;
+				if ((activationId !== null) !== agentToolText(collaborationRequestId)) throw new AgentToolPermissionError("tool_request_invalid");
+				const card = {
+					agentId, convId: call.convId,
+					// The engine held this call under agent-op:<toolCallId>; delivery executes exactly that operation.
+					durableSessionId: call.durableSessionId, logicalCallId: agentToolOperationId(call.toolCallId), sourceToolCallId: call.toolCallId,
+					toolKey: input.toolKey as AgentToolRequestInput["toolKey"], operation: input.operation, args: input.args ?? null, scope: input.scope ?? null,
+				};
+				let request: AgentToolRequestRecord;
+				// A collaboration card's original input is its execution's input (the Store reads it from the bound activation) and the
+				// card is linked to that request in the same transaction (the request then waits for the owner).
+				if (activationId !== null && agentToolText(collaborationRequestId)) request = this.d.store.createCollaborationToolRequest({ ...card, originKind: "agent_collaboration", collaborationRequestId, activationId });
+				else {
+					// C3: an owner card's original input comes from the trusted conversation, never from the body: its latest accepted user message.
+					const originInputSeq = this.d.store.lastSeq(call.convId, "message.user");
+					if (!agentToolInt(originInputSeq)) throw new AgentToolPermissionError("tool_request_invalid");
+					request = this.d.store.createAgentToolRequest({ ...card, originInputSeq, originKind: "user", collaborationRequestId: null, activationId: null });
+				}
+				this.d.changed();
+				return { state: "permission_pending", requestId: request.id, decisionId: request.decisionId };
+			}
+			case "/internal/agent-tools/action": {
+				// C8: one agent_tool_action card per click/fill call; the session recorded the call as agent-action:<toolCallId>.
+				const { operation, args, scope } = agentToolActionScope(input);
+				if (typeof input.toolKey !== "object" || input.toolKey === null) throw new AgentToolPermissionError("tool_request_invalid");
+				const originInputSeq = this.d.store.lastSeq(call.convId, "message.user");
+				if (!agentToolInt(originInputSeq)) throw new AgentToolPermissionError("tool_request_invalid");
+				const request = this.d.store.createAgentToolAction({
+					agentId, convId: call.convId, originInputSeq, originKind: "user", durableSessionId: call.durableSessionId,
+					logicalCallId: agentToolActionId(call.toolCallId), sourceToolCallId: call.toolCallId,
+					toolKey: input.toolKey as AgentToolRequestInput["toolKey"], operation: ASIDE_OPERATIONS[operation]!, args, scope,
+				});
+				this.d.changed();
+				return { state: "action_confirmation_pending", requestId: request.id, decisionId: request.decisionId };
+			}
+			case "/internal/agent-tools/reserve":
+				if (!agentToolInt(input.executorGeneration)) throw new AgentToolPermissionError("tool_request_invalid");
+				return ledger.reserve(this.owned(agentId, input.invocationId), input.executorGeneration);
+			case "/internal/agent-tools/start": {
+				if (!agentToolInt(input.executorGeneration)) throw new AgentToolPermissionError("tool_request_invalid");
+				// The ledger checks the persisted ACK of the current revision in the start transaction (C5).
+				return ledger.start(this.owned(agentId, input.invocationId), input.executorGeneration, { durableSessionId: call.durableSessionId });
+			}
+			case "/internal/agent-tools/result": {
+				const state = input.state;
+				if (!agentToolInt(input.executorGeneration) || !agentToolText(input.resultRef) ||
+					(state !== "succeeded" && state !== "failed" && state !== "outcome_unknown")) throw new AgentToolPermissionError("tool_request_invalid");
+				return ledger.result(this.owned(agentId, input.invocationId), input.executorGeneration, { state, resultRef: input.resultRef });
+			}
+			case "/internal/agent-tools/policy": {
+				// The engine matches by name; `operations` lets an adapter (zgw_aside) refuse an operation the grant does not name.
+				const { view, grants } = ledger.policyGrants(agentId);
+				return { ...(this.policyOf(agentId).policy as object), operations: grantedOperations(view, grants) };
+			}
+			case "/internal/agent-tools/policy-ack": {
+				if (!agentToolInt(input.revision)) throw new AgentToolPermissionError("tool_request_invalid");
+				return ledger.ackPolicy(call.durableSessionId, agentId, input.revision);
+			}
+		}
+		throw new AgentToolPermissionError("tool_request_invalid");
+	}
+}