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

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

@@ -1,41 +1,61 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { registerAgentCollaboration, COLLABORATION_TOOLS, CollaborationExtensionError } from "./agent-collaboration.ts";
+import { CollaborationSnapshots, type NativeFileSdk } from "./agent-collaboration-files.ts";
 import { INSTALL_RULES_FILE, INSTALL_RULES_HEADING, packageRulesDrop, PACKAGE_RULES_FILE, PACKAGE_RULES_HEADING, readRulesFile } from "../../src/agent-rules.ts";
 import { applyRequestRules, loadRequestRules, type ProviderRequestEvent } from "../../src/agent-request-rules.ts";
 import { loadEngineSdk } from "../../src/engine/index.ts";
 import { validateAgentFields } from "../../src/agent/definition.ts";
 import { runtimeHome, runtimePaths } from "../../src/runtime/paths.ts";
-import { agentNamePrompt, nicknamePrompt, readAgentPromptName, readPromptProfile, type PromptProfile } from "../../src/profile-prompt.ts";
+import { ATTACHMENT_READ_TOOL, installAttachmentRead, type AttachmentExtension } from "./attachment-read.ts";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { agentToolGatewayClient, installAgentToolBinding, type AgentToolBindExtension, type AgentToolRoute } from "./agent-tool-permissions.ts";
+import { AsideAdapter, asideBin } from "./agent-aside.ts";
+import { ActionTickets, AsideTargetRegistry, actionDigest } from "../../src/agent/aside-targets.ts";
+import { agentToolActionId, agentToolOperationId } from "../../src/agent/tool-delivery.ts";
+import { heldToolRequest } from "../../src/agent/tool-catalog.ts";
+import type { ToolSourceKind } from "../../src/agent/tool-permission-types.ts";
+import { ASIDE_DESCRIPTION, ASIDE_PARAMETERS, ASIDE_TOOL, asideAccount, asideCallDecision, asideGrantedOperations, asidePermits, heldAsideScope, carriedAsideTarget, heldOperation, withCarriedTarget } from "./agent-aside-tool.ts";
+import { canonicalJson } from "../../src/agent/tool-permissions.ts";
+import type { SessionAsideTarget } from "../../src/agent/aside-target-routes.ts";
+import { agentNamePrompt, agentNicknamePrompt, readAgentPromptName, readPromptProfile, type PromptProfile } from "../../src/profile-prompt.ts";
 
-type Context = { readonly cwd: string; readonly sessionManager: { getSessionId(): string }; readonly ui: { notify(message: string, level: "warning"): void } };
+type Entry = { readonly type: string; readonly customType?: string; readonly data?: Record<string, unknown> };
+type Context = { readonly cwd: string; readonly sessionManager: { getSessionId(): string; getEntries?(): readonly Entry[] }; readonly model?: unknown; readonly thinkingLevel?: string; readonly ui: {
+	notify(message: string, level: "warning"): void;
+	select(title: string, options: string[], opts?: { toolCallId?: string }): Promise<string | undefined>;
+} };
 type ToolCall = { readonly toolName: string; readonly toolCallId: string; readonly input: Record<string, unknown> };
 type Block = { readonly block: true; readonly reason: string };
 type Skill = { readonly name: string; readonly filePath: string };
 type Start = { readonly systemPrompt: string; readonly systemPromptOptions: { readonly skills?: readonly Skill[] } };
 type Events = {
 	session_start: unknown; session_shutdown: unknown; before_agent_start: Start;
-	before_provider_request: ProviderRequestEvent; tool_call: ToolCall; tool_result: { readonly toolCallId: string };
-	input: { readonly text: string }; agent_end: unknown; session_abort: unknown;
+	before_provider_request: ProviderRequestEvent; tool_call: ToolCall; tool_result: { readonly toolCallId: string; readonly isError: boolean };
+	input: { readonly text: string; readonly inputId?: string }; agent_end: unknown; agent_settled: unknown; session_abort: unknown;
+	tool_execution_end: { readonly toolCallId: string; readonly toolName: string; readonly result: unknown; readonly isError: boolean };
 };
 interface ExtensionApi {
 	readonly sessionKind: string;
 	readonly sessionContext: Readonly<Record<string, string>>;
-	readonly rpc: { emit(name: string, data: unknown): void; handle(name: string, handler: () => unknown): void };
+	readonly rpc: { emit(name: string, data: unknown): void; handle(name: string, handler: (data: unknown) => unknown): void };
 	on<K extends keyof Events>(event: K, handler: (event: Events[K], ctx: Context) => unknown, options?: { previewSafe: boolean }): void;
 	setActiveTools(names: string[]): void;
 	getCommands(): readonly { readonly name: string; readonly source: string }[];
 	appendEntry(name: string, data: unknown): void;
 	registerTool(tool: HistoryTool): void;
+	getAllTools?(): readonly { readonly name: string; readonly parameters?: unknown; readonly sourceInfo?: { readonly source?: string } }[];
 	registerFilesystemPolicy(policy: { check(request: { operation: string; canonicalPath: string }): { allow: true } | { allow: false; reason: string } }): void;
 }
 type HistoryTool = {
 	name: string; label: string; description: string; parameters: unknown;
-	execute(id: string, params: Record<string, unknown>, signal: AbortSignal | undefined): Promise<unknown>;
+	execute(id: string, params: Record<string, unknown>, signal: AbortSignal | undefined, update?: unknown, ctx?: unknown): Promise<unknown>;
 };
 type Edit = { readonly oldText: string; readonly newText: string };
 /** The runtime supplies this public SDK. Tests use the same native editor, not a replacement algorithm. */
-export interface AgentSdk {
+export interface AgentSdk extends NativeFileSdk {
 	createEditTool(cwd: string, options: { operations: {
 		readFile(path: string): Promise<Buffer>; writeFile(path: string, content: string): Promise<void>; access(path: string): Promise<void>;
 	} }): { execute(id: string, input: { path: string; edits: Edit[] }): Promise<unknown> };
@@ -44,9 +64,38 @@ const BASE_TOOLS = ["read", "write", "edit", "ask_user_question", "zgw_agent_his
 export const MEMORY_CAP_MESSAGE = "MEMORY.md를 요약해 줄인 뒤 다시 쓰세요.";
 const DAILY_RULES = "Record each day's facts, results and decisions chronologically in notes/daily/YYYY-MM-DD.md (KST). " +
 	"Keep only long-lived preferences, established facts and ongoing goals summarized in MEMORY.md; do not copy daily logs into it.";
-export const RESEARCH_RULES = "When you research on the web, write the results to knowledge/notes/companies/<company>.md " +
-	"(other topics knowledge/notes/research/<topic>.md) and put each source URL on the line of the fact it supports.";
+// The session cwd is knowledge/, so these paths are relative to it.
+export const RESEARCH_RULES = "When you research on the web, write the results to notes/companies/<company>.md " +
+	"(other topics notes/research/<topic>.md) and put each source URL on the line of the fact it supports.";
+export const WRITE_SCOPE_REASON = "agent_write_outside_outputs: Write result files under outputs/ and notes under notes/.";
+/**
+ * C1: daily-note and research write instructions (and the daily reminder) ask for writes. A managed agent (the Hub pushed a
+ * policy) gets them only while write or edit is granted; a legacy agent keeps them.
+ */
+export function writeInstructionsAllowed(granted: { readonly revision: number; readonly names: readonly string[] }): boolean {
+	return granted.revision < 1 || granted.names.includes("write") || granted.names.includes("edit");
+}
+export const OUTSIDE_KNOWLEDGE_REASON = "agent_path_outside_knowledge";
+/**
+ * 294 C6: a managed agent session opens full-access (the agent authority is its single gate), so the native preset no longer
+ * asks external_directory before a file tool leaves knowledge/. The adapter asks the owner in the same native form instead,
+ * and the call stays refused whatever the answer: no file outside knowledge/ is ever read or written, and nothing reaches the
+ * model while the prompt is open (293 J01). Only "Deny" is offered because no answer can let the call run.
+ */
+export function outsideKnowledgePrompt(lexical: string, canonical: string): string {
+	const patterns = [...new Set([lexical, canonical])].map((path) => `  - ${path}`).join("\n");
+	return `Permission required: external_directory\n\nDirectory: ${dirname(lexical)}\n\nPatterns:\n${patterns}`;
+}
+export const WRITE_DOTDOT_REASON = "agent_path_dotdot: A write path must not contain a .. segment; name the file under outputs/ or notes/ directly.";
+/** The KST calendar date (YYYY-MM-DD) of a time; daily notes are named by it. */
+export function kstDate(ms: number): string { return new Date(ms + 9 * 60 * 60 * 1000).toISOString().slice(0, 10); }
+export function dailyReminder(date: string): string {
+	return `Reminder: today's notes/daily/${date}.md has no entry yet. Add today's facts, results and decisions before you finish this turn.`;
+}
+function dailyPath(root: string, date: string): string { return join(root, "notes", "daily", `${date}.md`); }
 const HISTORY_LIMIT = 50;
+/** Each listed area keeps this many files and this many folder levels; the model reads contents itself. */
+const LIST_LIMIT = 200, LIST_DEPTH = 3;
 const blocked = (reason: string): Block => ({ block: true, reason });
 function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function missing(error: unknown): boolean { return error instanceof Error && "code" in error && error.code === "ENOENT"; }
@@ -54,6 +103,56 @@ function inside(root: string, path: string): boolean {
 	const part = relative(root, path);
 	return part === "" || (!isAbsolute(part) && part !== ".." && !part.startsWith(`..${sep}`));
 }
+function size(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/**
+ * A path with a control character, a line separator (U+0085, U+2028, U+2029) or an angle bracket is shown as a JSON string
+ * with those characters escaped. Folder names join into one path, so a tag can be made across "/"; escaping the whole
+ * path means no listed line can add a line or hold the block's tags, and JSON.parse gives back the real path.
+ */
+function shown(path: string): string {
+	if (!/[\u0000-\u001f\u007f-\u009f\u2028\u2029<>]/.test(path)) return path;
+	return JSON.stringify(path).replace(/[\u007f-\u009f\u2028\u2029<>]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+/** Regular files of one area, sorted, without hidden names or links. The area itself must be a real folder. */
+function listArea(root: string, area: string): { lines: string[]; more: number } {
+	const top = join(root, area);
+	try { if (!lstatSync(top).isDirectory()) throw new Error("knowledge_listing_failed"); } catch (error) {
+		if (missing(error)) return { lines: [], more: 0 };
+		throw error;
+	}
+	const lines: string[] = [];
+	let more = 0;
+	const walk = (dir: string, parts: readonly string[]) => {
+		for (const name of readdirSync(dir).sort()) {
+			if (name.startsWith(".")) continue;
+			const entry = lstatSync(join(dir, name));
+			if (entry.isSymbolicLink()) continue;
+			if (entry.isDirectory()) { if (parts.length + 1 < LIST_DEPTH) walk(join(dir, name), [...parts, name]); }
+			else if (!entry.isFile()) continue;
+			else if (lines.length < LIST_LIMIT) lines.push(`- ${shown([area, ...parts, name].join("/"))} (${size(entry.size)})`);
+			else more++;
+		}
+	};
+	walk(top, []);
+	return { lines, more };
+}
+/** Read every turn, so an upload reaches an open session at its next turn. */
+function filesBlock(root: string, outputRoot: string | null = root): string {
+	const area = (name: string) => {
+		const { lines, more } = name === "outputs" && outputRoot === null ? { lines: [], more: 0 } : listArea(name === "outputs" ? outputRoot ?? root : root, name);
+		return [...(lines.length > 0 ? lines : ["(none)"]), ...(more > 0 ? [`- and ${more} more`] : [])];
+	};
+	return ["<agent-files>", "Files the user uploaded (source/, read-only):", ...area("source"),
+		"Outputs (outputs/, write result files here):", ...area("outputs"),
+		"When the user mentions uploaded material, read these source/ files with the read tool.", "</agent-files>"].join("\n");
+}
+/** The agent writes results to outputs/, notes to notes/ and its memory to MEMORY.md; nothing else. */
+function writable(root: string, path: string): boolean {
+	return path === join(root, "MEMORY.md") || inside(join(root, "notes"), path) || inside(join(root, "outputs"), path);
+}
 /** Resolve existing links, including a new target's nearest existing parent. Dangling links fail closed. */
 export function agentPath(path: string): string {
 	try { lstatSync(path); } catch (error) {
@@ -93,14 +192,38 @@ function claimLock(root: string, sessionId: string, release = false): boolean {
 	} finally { rmdirSync(claim); }
 }
 
-export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<AgentSdk> = () => loadEngineSdk<AgentSdk>()): void {
+// allow: SIZE_OK - existing single-session lifecycle closure; this bounded integration retains its shared lock, memory and input state.
+/**
+ * Q-07: the collaboration binding a 294 card is signed with, or null for an owner card. A card asked inside a peer request
+ * execution names that activation and its request; a peer without its consumed binding is refused, never sent as an owner
+ * card. The reply run of a request the owner started (an activation with no request to execute, as the request tool's
+ * `request_forbidden` check reads it) continues the owner's own work, so its card is the owner card.
+ */
+export function collaborationToolCard(control: { isPeer(): boolean; observeClientInput(): void;
+	capture(): { readonly identity: { readonly activationId: string | null }; readonly requestId: string | null } } | undefined): { activationId: string; requestId: string } | null {
+	if (!control?.isPeer()) return null;
+	// An engine-held call never reached the tool_call hook, so its consumed input is proven here.
+	control.observeClientInput();
+	const { identity, requestId } = control.capture();
+	if (identity.activationId !== null && requestId === null) return null;
+	if (identity.activationId === null || requestId === null) throw new CollaborationExtensionError("binding_missing");
+	return { activationId: identity.activationId, requestId };
+}
+
+export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<AgentSdk> = () => loadEngineSdk<AgentSdk>(), now: () => number = Date.now): void {
+	const attachmentRead = installAttachmentRead(pi as unknown as AttachmentExtension);
 	const id = pi.sessionContext.zgw_agent;
 	if (pi.sessionContext.zgw_role !== "agent" || pi.sessionKind !== "interactive" || !id) return;
+	const collaboration = registerAgentCollaboration(pi);
+	let sdkPromise: Promise<AgentSdk> | undefined;
+	const sdkForSession = () => sdkPromise ??= loadSdk();
+	let fileBoundary: CollaborationSnapshots | undefined;
 	pi.registerTool({
 		name: "zgw_agent_history_search", label: "Agent history search",
 		description: "Search this agent's own past conversation messages for a text. Returns the newest matches first (at most 50). Other conversations are never searched.",
 		parameters: { type: "object", properties: { query: { type: "string", minLength: 1, maxLength: 200 }, limit: { type: "integer", minimum: 1, maximum: HISTORY_LIMIT } }, required: ["query"], additionalProperties: false },
 		async execute(_toolCallId, params, signal) {
+			collaboration?.assertGeneralTool();
 			if (typeof params.query !== "string" || params.query === "") throw new Error("agent_history_query_required");
 			const limit = typeof params.limit === "number" && Number.isInteger(params.limit) ? Math.min(Math.max(params.limit, 1), HISTORY_LIMIT) : 20;
 			const token = readFileSync(runtimePaths().omoTokenFile, "utf8").trim();
@@ -117,15 +240,189 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 			return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
 		},
 	});
-	let root = "", sessionId = "", prompt = "", ready = false, agentName = "";
+	let root = "", sessionId = "", ready = false, agentName = "";
+	// The role prompt sections of this session; the write-instruction sections are filtered per turn (C1).
+	let promptParts: string[] = [];
 	let maxBytes = 0;
 	let tools: string[] = [], skills: string[] = [];
+	// The narrow reader is offered only once the gateway bound this session; it never widens the file policy below.
+	// 294 C5: a tool granted by the owner is exposed only after the engine ACKed that policy revision (zgw.agent_tool_tools).
+	let grantedTools: { revision: number; names: string[] } = { revision: 0, names: [] };
+	// The Hub rotates this session's /internal/agent-tools secret on every open (zgw.agent_tool_bind).
+	const toolBinding = installAgentToolBinding(pi as unknown as AgentToolBindExtension);
+	const gatewayBase = () => process.env.ZGW_WORK_URL ?? `http://127.0.0.1:${process.env.ZGW_PORT ?? "8700"}`;
+	// Signed /internal/agent-tools call for one tool call; the identity comes from the Hub bind, never from the model.
+	const gateway = (route: AgentToolRoute, toolCallId: string, body: unknown): Promise<unknown> => {
+		const peer = route === "request" ? collaborationToolCard(collaboration) : null;
+		const context = toolBinding.context(toolCallId, `agent-tool-input:${toolCallId}`, peer?.activationId ?? null);
+		if (!context) throw new Error("agent_tool_unbound");
+		return agentToolGatewayClient({ context: () => context, base: gatewayBase(),
+			token: () => readFileSync(runtimePaths().omoTokenFile, "utf8").trim() })
+			.send(route, toolCallId, peer ? { ...(body as Record<string, unknown>), collaborationRequestId: peer.requestId } : body);
+	};
+	// 294 D1/C7: one adapter per session (it owns the persistent `aside repl` process and the tabs it opened).
+	let aside: AsideAdapter | null = null;
+	let asideRegistry = new AsideTargetRegistry();
+	// D4: owner-bound tabs the gateway carried for granted calls, by the call's stored args; consumed by that execution.
+	const carried = new Map<string, SessionAsideTarget>();
+	(pi.rpc as unknown as { handle(name: string, handler: (data: unknown) => unknown): void }).handle("zgw.aside_target", (data) => {
+		const { key, target } = carriedAsideTarget(data, id);
+		if (target === null) carried.delete(key);
+		else carried.set(key, target);
+		return { ok: true };
+	});
+	// C8: the one-shot confirmation the gateway carries for an action execution, by the call's stored args (zgw.aside_action).
+	// The gateway sends it only after its start transaction consumed the ledger ticket; the execution consumes it once.
+	const asideTickets = new ActionTickets();
+	const carriedActions = new Map<string, string>();
+	(pi.rpc as unknown as { handle(name: string, handler: (data: unknown) => unknown): void }).handle("zgw.aside_action", (data) => {
+		const value = data as { args?: unknown; ticket?: unknown } | null;
+		if (!value || typeof value !== "object" || !("args" in value) || (value.ticket !== null && (typeof value.ticket !== "string" || value.ticket === ""))) {
+			throw new Error("aside_action_invalid");
+		}
+		const key = canonicalJson(value.args);
+		if (value.ticket === null) carriedActions.delete(key);
+		else carriedActions.set(key, value.ticket as string);
+		return { ok: true };
+	});
+	// Click/fill calls of this session already sent to the gateway as a confirmation card, by engine operation id.
+	const actionRequested = new Set<string>();
+	const asideScope = new AsyncLocalStorage<readonly string[]>();
+	const asideAdapter = () => aside ??= new AsideAdapter({
+		registry: asideRegistry, tickets: asideTickets, host: "local", gatewayOrigins: [new URL(gatewayBase()).origin],
+		confirmedAccount: () => asideAccount(asideBin()),
+		// The adapter asks per permission class; the call's scope is the grant read for this exact call.
+		authorize: (permission) => asidePermits(asideScope.getStore() ?? [], permission),
+	});
+	pi.registerTool({
+		name: ASIDE_TOOL, label: "Aside browser", description: ASIDE_DESCRIPTION, parameters: ASIDE_PARAMETERS,
+		async execute(toolCallId, params) {
+			// The engine authority already allowed the tool; the operation must also be one the current grant names.
+			const policy = await gateway("policy", toolCallId, null);
+			const granted = asideGrantedOperations(policy);
+			const decision = asideCallDecision(policy, params.operation);
+			const key = canonicalJson(params);
+			const bound = carried.get(key);
+			carried.delete(key);
+			const adapter = asideAdapter();
+			if (bound) asideRegistry.adopt(bound);
+			const input = bound ? withCarriedTarget(params, bound) : params;
+			const ctx = { agentId: id, incarnation: toolBinding.lifecycleEpoch() ?? 0 };
+			const carriedTicket = carriedActions.get(canonicalJson(input));
+			carriedActions.delete(canonicalJson(input));
+			let result: unknown;
+			if (decision === "refuse") {
+				result = { ok: false, refused: "permission_denied" };
+			} else if (decision === "hold") {
+				result = await holdOperation(toolCallId, ctx, input);
+			} else if ((input.operation === "click" || input.operation === "fill") && carriedTicket === undefined) {
+				result = await asideScope.run(granted, () => requestAction(toolCallId, ctx, adapter, input));
+			} else {
+				const actionTicket = carriedTicket === undefined ? undefined : asideTickets.issue(actionDigest(String(input.targetHandle), input.operation as "click" | "fill",
+					String(input.ref), String(input.snapshotRevision), input.operation === "fill" ? String(input.text) : null));
+				result = await asideScope.run(granted, () => adapter.invoke({ ...ctx, ...(actionTicket ? { actionTicket } : {}) }, input));
+			}
+			return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+		},
+	});
+	// Operations of this session already sent to the gateway as a grant card, by engine operation id.
+	const heldRequested = new Set<string>();
+	/**
+	 * C1/C7: an operation the current zgw_aside grant does not name. The engine allows zgw_aside by name, so the session holds
+	 * the call the way the engine holds an ungranted one: recorded once as agent-op:<toolCallId> with its exact input and sent
+	 * to the gateway as one new grant card. After the owner allows, the gateway executes that operation once and continues.
+	 */
+	async function holdOperation(toolCallId: string, ctx: { agentId: string; incarnation: number }, input: Record<string, unknown>): Promise<unknown> {
+		const operationId = agentToolOperationId(toolCallId);
+		if (!heldRequested.has(operationId)) {
+			heldRequested.add(operationId);
+			pi.appendEntry("agent_tool_operation", { operationId, requestId: `agent-tool-request:${operationId}`, toolName: ASIDE_TOOL, toolCallId, input, path: "direct" });
+		}
+		const known = typeof input.targetHandle === "string" ? asideRegistry.resolve(input.targetHandle, ctx.agentId, ctx.incarnation) : null;
+		const scope = heldAsideScope(known && !("refused" in known) ? known : null);
+		const info = pi.getAllTools?.().find((tool) => tool.name === ASIDE_TOOL);
+		const source = info?.sourceInfo?.source;
+		const sourceKind = source === "builtin" || source === "extension" || source === "mcp" ? source as ToolSourceKind : undefined;
+		const { toolKey, operation } = heldToolRequest({ name: ASIDE_TOOL, parameters: info?.parameters ?? null, ...(sourceKind ? { sourceKind } : {}) }, input);
+		try {
+			const card = await gateway("request", toolCallId, { operation, toolKey, args: input, scope }) as { requestId?: unknown };
+			return { ok: false, state: "permission_pending", requestId: card.requestId, operationId };
+		} catch (error) {
+			heldRequested.delete(operationId);
+			return { ok: false, refused: "permission_denied", reason: error instanceof Error ? error.message : "unknown" };
+		}
+	}
+	/**
+	 * C8: a click/fill without its confirmation. The call is checked and described (never run), recorded once as the engine
+	 * operation agent-action:<toolCallId> with its exact input, and sent to the gateway as one agent_tool_action card. After
+	 * the owner allows, the gateway executes that operation once with the consumed ticket and continues the original work.
+	 */
+	async function requestAction(toolCallId: string, ctx: { agentId: string; incarnation: number }, adapter: AsideAdapter, input: Record<string, unknown>): Promise<unknown> {
+		const prepared = adapter.prepareAction(ctx, input);
+		if (!prepared.ok) return prepared;
+		const operationId = agentToolActionId(toolCallId);
+		if (!actionRequested.has(operationId)) {
+			actionRequested.add(operationId);
+			pi.appendEntry("agent_tool_operation", { operationId, requestId: `agent-tool-request:${operationId}`, toolName: ASIDE_TOOL, toolCallId, input, path: "operation" });
+		}
+		const info = pi.getAllTools?.().find((tool) => tool.name === ASIDE_TOOL);
+		const source = info?.sourceInfo?.source;
+		const sourceKind = source === "builtin" || source === "extension" || source === "mcp" ? source as ToolSourceKind : undefined;
+		const { toolKey } = heldToolRequest({ name: ASIDE_TOOL, parameters: info?.parameters ?? null, ...(sourceKind ? { sourceKind } : {}) }, input);
+		try {
+			const card = await gateway("action", toolCallId, { operation: input.operation, toolKey, args: input, target: { origin: prepared.target.origin, kind: prepared.target.kind }, element: prepared.element }) as
+				{ requestId?: unknown; decisionId?: unknown };
+			return { ok: false, state: "action_confirmation_pending", targetHandle: prepared.target.handle, requestId: card.requestId, operationId };
+		} catch (error) {
+			return { ok: false, refused: "action_ticket_required", targetHandle: prepared.target.handle, reason: error instanceof Error ? error.message : "unknown" };
+		}
+	}
+	// zgw_aside is offered once the Hub pushed a policy (a managed agent): the engine authority then holds or allows it.
+	const activeTools = () => [...new Set([...(attachmentRead.bound() ? [...tools, ATTACHMENT_READ_TOOL] : tools), ...grantedTools.names,
+		...(grantedTools.revision >= 1 ? [ASIDE_TOOL] : [])])];
+	// D2: a call the engine authority held becomes one gateway request card; the stored operation runs after the allow.
+	const requested = new Set<string>();
+	pi.on("tool_execution_end", async (event, ctx) => {
+		const held = heldOperation(event);
+		if (!held || requested.has(held.operationId)) return;
+		const entry = ctx.sessionManager.getEntries?.().find((e) => e.type === "custom" && e.customType === "agent_tool_operation" && e.data?.operationId === held.operationId);
+		if (!entry?.data || typeof entry.data.toolName !== "string") return;
+		requested.add(held.operationId);
+		const toolName = entry.data.toolName;
+		const info = pi.getAllTools?.().find((tool) => tool.name === toolName);
+		const source = info?.sourceInfo?.source;
+		const sourceKind = source === "builtin" || source === "extension" || source === "mcp" ? source as ToolSourceKind : undefined;
+		const { toolKey, operation } = heldToolRequest({ name: toolName, parameters: info?.parameters ?? null, ...(sourceKind ? { sourceKind } : {}) }, entry.data.input);
+		try {
+			await gateway("request", event.toolCallId, { operation, toolKey, args: entry.data.input ?? null, scope: null });
+		} catch (error) {
+			requested.delete(held.operationId);
+			warn(`agent_tool_request_failed:${error instanceof Error ? error.message : "unknown"}`);
+		}
+	});
 	const skillSnapshots = new Map<string, string>();
 	let memoryCall: string | undefined;
 	let ui: Context["ui"] | undefined;
 	let startupWarnings: { code: string; message: string }[] = [];
+	let appliedSha: string | null = null;
+	// Daily-note reminder: the dates this session wrote, whether the current turn has user input, and a pending reminder date.
+	const dailyWritten = new Set<string>();
+	// Admitted writes of today's note, by tool call id, until the tool reports the outcome.
+	const dailyCalls = new Map<string, string>();
+	let userInput = false;
+	let remind: string | undefined;
 	// session_start precedes the gateway's open_session attachment. Read this snapshot after binding the owner.
-	pi.rpc.handle("zgw.agent_warnings", () => ({ warnings: startupWarnings }));
+	pi.rpc.handle("zgw.agent_warnings", () => ({ warnings: startupWarnings, appliedSha }));
+	// The runtime passes the request data; the declared zero-argument shape predates data handlers (292 widens it).
+	(pi.rpc as unknown as { handle(name: string, handler: (data: unknown) => unknown): void }).handle("zgw.agent_tool_tools", (data) => {
+		if (!record(data) || !Number.isSafeInteger(data.revision) || (data.revision as number) < 1 || !Array.isArray(data.names) ||
+			!data.names.every((name): name is string => typeof name === "string" && name !== "")) throw new Error("agent_tool_tools_invalid");
+		// An older revision never replaces a newer one, so a delayed push cannot re-expose a revoked tool.
+		if ((data.revision as number) < grantedTools.revision) return { revision: grantedTools.revision, applied: false };
+		grantedTools = { revision: data.revision as number, names: [...data.names] };
+		if (ready) pi.setActiveTools(activeTools());
+		return { revision: grantedTools.revision, applied: true };
+	});
 	const warn = (code: string) => {
 		const data = { agentId: id, code };
 		const message = code === "memory_over_cap" ? `MEMORY.md가 크기 상한을 넘어 이번 세션에서 생략되었습니다. ${MEMORY_CAP_MESSAGE}` : `에이전트 요청이 제한되었습니다: ${code}`;
@@ -134,12 +431,14 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 		pi.rpc.emit("zgw.agent_warning", data);
 		ui?.notify(message, "warning");
 	};
-	const pathDenial = (path: string, write: boolean): string | undefined => {
+	// scope=false checks a lexical path: the write area is judged on the canonical target, so a link to MEMORY.md still works.
+	const pathDenial = (path: string, write: boolean, scope = true): string | undefined => {
 		if (!ready) return "agent_not_ready";
-		if (!inside(root, path)) return "agent_path_outside_knowledge";
+		if (!inside(root, path)) return OUTSIDE_KNOWLEDGE_REASON;
 		if (!write) return undefined;
 		if (inside(join(root, "source"), path)) return "agent_source_read_only";
 		if (path === root || inside(join(root, ".lock"), path) || inside(join(root, ".lock.claim"), path)) return "agent_lock_protected";
+		if (scope && !writable(root, path)) return WRITE_SCOPE_REASON;
 		if (!claimLock(root, sessionId)) return "agent_knowledge_locked";
 		return undefined;
 	};
@@ -150,8 +449,14 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 		} catch { return { allow: false, reason: "agent_path_unavailable" }; }
 	} });
 	pi.on("session_start", async (_event, ctx) => {
+		collaboration?.start(ctx);
 		ready = false;
+		appliedSha = null;
 		startupWarnings = [];
+		dailyWritten.clear();
+		dailyCalls.clear();
+		userInput = false;
+		remind = undefined;
 		ui = ctx.ui;
 		pi.setActiveTools([]);
 		const token = readFileSync(runtimePaths().omoTokenFile, "utf8").trim();
@@ -175,7 +480,7 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 		sessionId = ctx.sessionManager.getSessionId();
 		maxBytes = memory.maxBytes;
 		skills = allowedSkills;
-		tools = [...BASE_TOOLS, ...(toolSettings.web === true ? ["web_search", "webfetch"] : [])];
+		tools = [...BASE_TOOLS, ...COLLABORATION_TOOLS, ...(toolSettings.web === true ? ["web_search", "webfetch"] : [])];
 		const sections: string[] = [];
 		for (const [enabled, path, heading] of [
 			[rules.gateway, PACKAGE_RULES_FILE, PACKAGE_RULES_HEADING],
@@ -196,19 +501,46 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 				else sections.push(`<agent-memory>\n${snapshot.toString("utf8")}\n</agent-memory>`);
 			}
 		}
-		prompt = sections.join("\n\n");
+		promptParts = sections;
 		if (!claimLock(root, sessionId)) warn("knowledge_locked");
+		// Agents made before outputs/ existed get the folder from the lock owner.
+		else {
+			try { mkdirSync(join(root, "outputs"), { recursive: true }); } catch { warn("outputs_unavailable"); }
+		}
 		ready = true;
+		if (collaboration) {
+			const sdk = await sdkForSession();
+			fileBoundary = new CollaborationSnapshots({ root: realpathSync(join(runtimeHome(), "agents")), control: collaboration,
+				queue: sdk.withFileMutationQueue, assertKnowledgeLock() {
+					if (!ready || collaboration.capture().binding.agentId !== id || !claimLock(root, sessionId)) throw new CollaborationExtensionError("agent_knowledge_locked");
+				} });
+			fileBoundary.install(pi, { sdk, cwd: root, policy: async ({ operation, canonicalPath }) => {
+				const reason = pathDenial(canonicalPath, operation === "write");
+				return reason ? { allow: false, reason } : { allow: true };
+			} });
+		}
+		appliedSha = typeof definition.sha === "string" ? definition.sha : null;
+		collaboration?.applied({ definitionSha: appliedSha ?? "", fingerprint: createHash("sha256").update(JSON.stringify({ prompt, model: ctx.model, thinking: ctx.thinkingLevel, appliedSha })).digest("hex") });
 		pi.setActiveTools(tools);
 	});
-	pi.on("session_shutdown", () => { if (root && sessionId) claimLock(root, sessionId, true); ready = false; });
+	pi.on("session_shutdown", () => {
+		collaboration?.revoke();
+		if (root && sessionId) claimLock(root, sessionId, true);
+		ready = false;
+		void aside?.shutdown("session_shutdown");
+		aside = null;
+		asideRegistry = new AsideTargetRegistry();
+		carried.clear();
+	});
+	pi.on("agent_settled", () => { collaboration?.settle(); });
 	const requestRules = loadRequestRules();
 	pi.on("before_provider_request", (event) => applyRequestRules(event, requestRules));
 	let profile: PromptProfile = { nickname: undefined, agentName: "" };
 	pi.on("before_agent_start", async (event) => {
 		if (!ready) throw new Error("agent_not_ready");
+		if (collaboration?.isPeer()) userInput = false;
 		[profile, agentName] = await Promise.all([readPromptProfile(profile), readAgentPromptName(id, agentName)]);
-		pi.setActiveTools(tools);
+		pi.setActiveTools(activeTools());
 		// File tools remain confined to knowledge. Approved skill bodies are loaded here, not through a read exception.
 		for (const skill of event.systemPromptOptions.skills ?? []) {
 			if (skills.includes(skill.name) && !skillSnapshots.has(skill.name)) skillSnapshots.set(skill.name, readFileSync(skill.filePath, "utf8"));
@@ -216,31 +548,57 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 		const base = event.systemPrompt.replace(/<available_skills>[\s\S]*?<\/available_skills>/g, "")
 			.replace(/<skill_roots>[\s\S]*?<\/skill_roots>/g, "");
 		const selected = [...skillSnapshots].map(([name, text]) => `<agent-skill name="${name}">\n${text}\n</agent-skill>`).join("\n\n");
-		return { systemPrompt: [base, prompt, selected, agentNamePrompt(agentName), nicknamePrompt(profile.nickname)].filter(Boolean).join("\n\n") };
+		let files = "";
+		// A broken listing must not stop the turn; the warning names the cause and the block is left out.
+		try { files = filesBlock(root, collaboration?.isPeer() ? fileBoundary?.outputRoot() ?? null : root); } catch { warn("knowledge_listing_failed"); }
+		// A reminder raised on an earlier KST day is dropped; it is shown once.
+		// C1: write instructions only when this agent may write (legacy, or a managed agent with write/edit granted).
+		const writes = writeInstructionsAllowed(grantedTools);
+		const prompt = promptParts.filter((part) => writes || (part !== DAILY_RULES && part !== RESEARCH_RULES)).join("\n\n");
+		const reminder = writes && remind === kstDate(now()) ? dailyReminder(remind) : "";
+		remind = undefined;
+		// The nickname line is the agent variant: the role instructions in `prompt` may set another form of address (todo 9).
+		return { systemPrompt: [base, prompt, selected, files, agentNamePrompt(agentName), agentNicknamePrompt(profile.nickname), reminder].filter(Boolean).join("\n\n") };
 	});
 	pi.on("input", (event) => {
 		if (!ready) { warn("agent_not_ready"); return { action: "handled" }; }
+		if (collaboration?.input(event)) { userInput = false; return { action: "continue" }; }
 		const known = new Set(pi.getCommands().filter((command) => command.source === "skill").map((command) => command.name.replace(/^skill:/, "")));
 		for (const match of event.text.matchAll(/(?:^|\s)(\/skill:|\$(?:skill:)?)([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g)) {
 			const name = match[2] ?? "";
 			if (known.has(name) && !skills.includes(name)) { warn("skill_not_allowed"); return { action: "handled" }; }
 		}
+		userInput = true;
 		return { action: "continue" };
 	});
-	pi.on("tool_call", async (event) => {
-		if (!ready || !tools.includes(event.toolName)) return blocked("agent_tool_not_allowed");
+	pi.on("tool_call", async (event, ctx) => {
+		if (!ready || !activeTools().includes(event.toolName)) return blocked("agent_tool_not_allowed");
+		try {
+			if (collaboration?.isPeer()) collaboration.observeClientInput();
+			if (!COLLABORATION_TOOLS.includes(event.toolName)) collaboration?.assertGeneralTool();
+		}
+		catch (error) { if (error instanceof CollaborationExtensionError) return blocked(error.code); throw error; }
 		if (!["read", "write", "edit"].includes(event.toolName)) return;
+		if (collaboration?.isPeer()) return;
 		try {
 			if (typeof event.input.path !== "string" || event.input.path === "") return blocked("agent_path_required");
+			const write = event.toolName !== "read";
+			// Judge the argument as given: resolve() would remove a .. segment before the area checks see it.
+			if (write && event.input.path.split(/[\\/]/).includes("..")) return blocked(WRITE_DOTDOT_REASON);
 			const expanded = event.input.path.replace(/^~(?=\/|$)/, homedir());
 			const lexical = resolve(root, expanded);
 			const path = agentPath(lexical);
-			const write = event.toolName !== "read";
-			const reason = pathDenial(lexical, write) ?? pathDenial(path, write);
+			const reason = pathDenial(lexical, write, false) ?? pathDenial(path, write);
+			// A managed session (the Hub opened it full-access) has no native external_directory prompt; the owner sees this one.
+			if (reason === OUTSIDE_KNOWLEDGE_REASON && pi.sessionContext.zgw_tool_authority === "managed") {
+				await ctx.ui.select(outsideKnowledgePrompt(lexical, path), ["Deny"], { toolCallId: event.toolCallId });
+			}
 			if (reason) return blocked(reason);
 			if (write && existsSync(path) && lstatSync(path).nlink > 1) return blocked("agent_linked_file_read_only");
 			// Canonicalize the actual argument too; do not leave a checked symlink for the native tool to follow.
 			event.input.path = path;
+			const today = kstDate(now());
+			if (write && path === dailyPath(root, today)) dailyCalls.set(event.toolCallId, today);
 			if (!write || path !== agentPath(join(root, "MEMORY.md"))) return;
 			if (memoryCall !== undefined) return blocked("agent_memory_busy");
 			memoryCall = event.toolCallId;
@@ -252,7 +610,7 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 				const edits = event.input.edits;
 				if (!Array.isArray(edits) || !edits.every((e): e is Edit => record(e) && typeof e.oldText === "string" && typeof e.newText === "string")) throw new Error("agent_edit_input_invalid");
 				// Run the pinned native editor against memory-only operations: BOM, CRLF, fuzzy and multi-edit semantics stay exact.
-				const sdk = await loadSdk();
+				const sdk = await sdkForSession();
 				let result: string | undefined;
 				await sdk.createEditTool(root, { operations: {
 					readFile: async () => readFileSync(path), access: async () => {},
@@ -267,8 +625,22 @@ export default function agentControl(pi: ExtensionApi, loadSdk: () => Promise<Ag
 			return blocked(error instanceof Error ? error.message : "agent_path_unavailable");
 		}
 	});
-	pi.on("tool_result", (event) => { if (memoryCall === event.toolCallId) memoryCall = undefined; });
+	pi.on("tool_result", (event) => {
+		if (memoryCall === event.toolCallId) memoryCall = undefined;
+		const date = dailyCalls.get(event.toolCallId);
+		dailyCalls.delete(event.toolCallId);
+		// Only a write the tool reports as done counts as today's note; a failed write keeps the reminder.
+		if (date !== undefined && event.isError === false) { dailyWritten.add(date); remind = undefined; }
+	});
 	// A later hook/permission can refuse a call without a tool_result. Its turn end also releases the reservation.
-	pi.on("agent_end", () => { memoryCall = undefined; });
-	pi.on("session_abort", () => { memoryCall = undefined; });
+	pi.on("agent_end", () => {
+		memoryCall = undefined;
+		// A call refused after admission has no tool_result; it never counts, also not by a late result.
+		dailyCalls.clear();
+		// A user turn that ends without a write to today's note raises the reminder for the next turn.
+		const today = kstDate(now());
+		if (userInput && !dailyWritten.has(today)) remind = today;
+		userInput = false;
+	});
+	pi.on("session_abort", () => { collaboration?.revoke(); memoryCall = undefined; });
 }

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

@@ -0,0 +1,42 @@
+;; 294 item 6: OS profile for a registered agent's bash/powershell/command monitor.
+;; Default deny. Only the interpreter, system libraries and the work root (a copy of approved files) are readable.
+;; Only the work root is writable. Network, sockets, Apple Events and ptrace stay denied.
+;; Parameters: WORK_ROOT (real path of the copy root), INTERPRETER (real path), INTERPRETER_DIR (its folder).
+(version 1)
+(deny default)
+
+(allow process-fork)
+(allow process-exec
+	(literal (param "INTERPRETER"))
+	(subpath "/bin")
+	(subpath "/usr/bin"))
+(allow signal (target same-sandbox))
+(allow sysctl-read)
+
+;; Path lookups (dyld, shells) need stat on parent folders; file contents stay denied below.
+(allow file-read-metadata)
+(allow file-read*
+	(literal "/")
+	(subpath "/usr/lib")
+	(subpath "/usr/share")
+	(subpath "/System")
+	(subpath "/bin")
+	(subpath "/usr/bin")
+	(subpath "/private/var/db/dyld")
+	(subpath "/Library/Apple/System")
+	(literal "/dev/null")
+	(literal "/dev/zero")
+	(literal "/dev/random")
+	(literal "/dev/urandom")
+	(literal "/dev/tty")
+	(subpath (param "INTERPRETER_DIR"))
+	(subpath (param "WORK_ROOT")))
+(allow file-write*
+	(literal "/dev/null")
+	(subpath (param "WORK_ROOT")))
+(allow file-ioctl (literal "/dev/null") (literal "/dev/tty"))
+
+(deny network*)
+(deny appleevent-send)
+(deny process-info* (target others))
+(deny mach-priv-task-port)