@openacp/cli 2026.406.1 → 2026.406.3

package/dist/cli.js

@@ -1104,7 +1104,7 @@ Declare in \`permissions\` array. Only request what you need.
 
 Calling a method without the required permission throws \`PluginPermissionError\`.
 
-## Middleware Hooks (20 total)
+## Middleware Hooks (19 total)
 
 Register with \`ctx.registerMiddleware(hook, { priority?, handler })\`. Return \`null\` to block the flow, call \`next()\` to continue.
 
@@ -1757,6 +1757,104 @@ var init_security_guard = __esm({
   }
 });
 
+// src/core/events.ts
+var Hook, BusEvent, SessionEv;
+var init_events = __esm({
+  "src/core/events.ts"() {
+    "use strict";
+    Hook = {
+      // --- Message flow ---
+      /** Incoming message from any adapter — modifiable, can block. */
+      MESSAGE_INCOMING: "message:incoming",
+      /** Outgoing message before it reaches the adapter — modifiable, can block. */
+      MESSAGE_OUTGOING: "message:outgoing",
+      // --- Agent / turn lifecycle ---
+      /** Before a user prompt is sent to the agent — modifiable, can block. */
+      AGENT_BEFORE_PROMPT: "agent:beforePrompt",
+      /** Before an agent event is dispatched — modifiable, can block. */
+      AGENT_BEFORE_EVENT: "agent:beforeEvent",
+      /** After an agent event is dispatched — read-only, fire-and-forget. */
+      AGENT_AFTER_EVENT: "agent:afterEvent",
+      /** Before the current prompt is cancelled — modifiable, can block. */
+      AGENT_BEFORE_CANCEL: "agent:beforeCancel",
+      /** Before the agent is switched — modifiable, can block. */
+      AGENT_BEFORE_SWITCH: "agent:beforeSwitch",
+      /** After the agent has been switched — read-only, fire-and-forget. */
+      AGENT_AFTER_SWITCH: "agent:afterSwitch",
+      // --- Turn boundaries ---
+      /** Turn started — read-only, fire-and-forget. */
+      TURN_START: "turn:start",
+      /** Turn ended (always fires, even on error) — read-only, fire-and-forget. */
+      TURN_END: "turn:end",
+      // --- Session lifecycle ---
+      /** Before a new session is created — modifiable, can block. */
+      SESSION_BEFORE_CREATE: "session:beforeCreate",
+      /** After a session is destroyed — read-only, fire-and-forget. */
+      SESSION_AFTER_DESTROY: "session:afterDestroy",
+      // --- Permissions ---
+      /** Before a permission request is shown to the user — modifiable, can block. */
+      PERMISSION_BEFORE_REQUEST: "permission:beforeRequest",
+      /** After a permission request is resolved — read-only, fire-and-forget. */
+      PERMISSION_AFTER_RESOLVE: "permission:afterResolve",
+      // --- Config ---
+      /** Before config options change — modifiable, can block. */
+      CONFIG_BEFORE_CHANGE: "config:beforeChange",
+      // --- Filesystem (agent-level) ---
+      /** Before a file read operation — modifiable. */
+      FS_BEFORE_READ: "fs:beforeRead",
+      /** Before a file write operation — modifiable. */
+      FS_BEFORE_WRITE: "fs:beforeWrite",
+      // --- Terminal ---
+      /** Before a terminal session is created — modifiable, can block. */
+      TERMINAL_BEFORE_CREATE: "terminal:beforeCreate",
+      /** After a terminal session exits — read-only, fire-and-forget. */
+      TERMINAL_AFTER_EXIT: "terminal:afterExit"
+    };
+    BusEvent = {
+      // --- Session lifecycle ---
+      SESSION_CREATED: "session:created",
+      SESSION_UPDATED: "session:updated",
+      SESSION_DELETED: "session:deleted",
+      SESSION_ENDED: "session:ended",
+      SESSION_NAMED: "session:named",
+      SESSION_THREAD_READY: "session:threadReady",
+      SESSION_CONFIG_CHANGED: "session:configChanged",
+      SESSION_AGENT_SWITCH: "session:agentSwitch",
+      // --- Agent ---
+      AGENT_EVENT: "agent:event",
+      AGENT_PROMPT: "agent:prompt",
+      // --- Permissions ---
+      PERMISSION_REQUEST: "permission:request",
+      PERMISSION_RESOLVED: "permission:resolved",
+      // --- Message visibility ---
+      MESSAGE_QUEUED: "message:queued",
+      MESSAGE_PROCESSING: "message:processing",
+      // --- System lifecycle ---
+      KERNEL_BOOTED: "kernel:booted",
+      SYSTEM_READY: "system:ready",
+      SYSTEM_SHUTDOWN: "system:shutdown",
+      SYSTEM_COMMANDS_READY: "system:commands-ready",
+      // --- Plugin lifecycle ---
+      PLUGIN_LOADED: "plugin:loaded",
+      PLUGIN_FAILED: "plugin:failed",
+      PLUGIN_DISABLED: "plugin:disabled",
+      PLUGIN_UNLOADED: "plugin:unloaded",
+      // --- Usage ---
+      USAGE_RECORDED: "usage:recorded"
+    };
+    SessionEv = {
+      AGENT_EVENT: "agent_event",
+      PERMISSION_REQUEST: "permission_request",
+      SESSION_END: "session_end",
+      STATUS_CHANGE: "status_change",
+      NAMED: "named",
+      ERROR: "error",
+      PROMPT_COUNT_CHANGED: "prompt_count_changed",
+      TURN_STARTED: "turn_started"
+    };
+  }
+});
+
 // src/plugins/security/index.ts
 var security_exports = {};
 __export(security_exports, {
@@ -1855,7 +1953,7 @@ function createSecurityPlugin() {
         };
       };
       const guard = new SecurityGuard(getSecurityConfig, core.sessionManager);
-      ctx.registerMiddleware("message:incoming", {
+      ctx.registerMiddleware(Hook.MESSAGE_INCOMING, {
         handler: async (payload, next) => {
           const access2 = await guard.checkAccess(payload);
           if (!access2.allowed) {
@@ -1875,6 +1973,7 @@ var init_security = __esm({
   "src/plugins/security/index.ts"() {
     "use strict";
     init_security_guard();
+    init_events();
     security_default = createSecurityPlugin();
   }
 });
@@ -3427,7 +3526,7 @@ var init_history_recorder = __esm({
       }
       states = /* @__PURE__ */ new Map();
       debounceTimers = /* @__PURE__ */ new Map();
-      onBeforePrompt(sessionId, text6, attachments) {
+      onBeforePrompt(sessionId, text6, attachments, sourceAdapterId) {
         let state = this.states.get(sessionId);
         if (!state) {
           state = {
@@ -3445,6 +3544,9 @@ var init_history_recorder = __esm({
         if (attachments && attachments.length > 0) {
           userTurn.attachments = attachments.map(toHistoryAttachment);
         }
+        if (sourceAdapterId) {
+          userTurn.sourceAdapterId = sourceAdapterId;
+        }
         state.history.turns.push(userTurn);
         const assistantTurn = {
           index: state.history.turns.length,
@@ -3729,6 +3831,7 @@ var init_context = __esm({
     init_history_provider();
     init_history_recorder();
     init_history_store();
+    init_events();
     contextPlugin = {
       name: "@openacp/context",
       version: "1.0.0",
@@ -3772,35 +3875,35 @@ var init_context = __esm({
         manager.setHistoryStore(store);
         manager.registerFlusher((sessionId) => recorder.flush(sessionId));
         ctx.registerService("context", manager);
-        ctx.registerMiddleware("agent:beforePrompt", {
+        ctx.registerMiddleware(Hook.AGENT_BEFORE_PROMPT, {
           priority: 200,
           handler: async (payload, next) => {
-            recorder.onBeforePrompt(payload.sessionId, payload.text, payload.attachments);
+            recorder.onBeforePrompt(payload.sessionId, payload.text, payload.attachments, payload.sourceAdapterId);
             return next();
           }
         });
-        ctx.registerMiddleware("agent:afterEvent", {
+        ctx.registerMiddleware(Hook.AGENT_AFTER_EVENT, {
           priority: 200,
           handler: async (payload, next) => {
             recorder.onAfterEvent(payload.sessionId, payload.event);
             return next();
           }
         });
-        ctx.registerMiddleware("turn:end", {
+        ctx.registerMiddleware(Hook.TURN_END, {
           priority: 200,
           handler: async (payload, next) => {
             await recorder.onTurnEnd(payload.sessionId, payload.stopReason);
             return next();
           }
         });
-        ctx.registerMiddleware("permission:afterResolve", {
+        ctx.registerMiddleware(Hook.PERMISSION_AFTER_RESOLVE, {
           priority: 200,
           handler: async (payload, next) => {
             recorder.onPermissionResolved(payload.sessionId, payload.requestId, payload.decision);
             return next();
           }
         });
-        ctx.registerMiddleware("session:afterDestroy", {
+        ctx.registerMiddleware(Hook.SESSION_AFTER_DESTROY, {
           priority: 200,
           handler: async (payload, next) => {
             await recorder.onSessionDestroy(payload.sessionId);
@@ -7886,6 +7989,7 @@ var MAX_SSE_CONNECTIONS, SSEManager;
 var init_sse_manager = __esm({
   "src/plugins/api-server/sse-manager.ts"() {
     "use strict";
+    init_events();
     MAX_SSE_CONNECTIONS = 50;
     SSEManager = class {
       constructor(eventBus, getSessionStats, startedAt) {
@@ -7900,14 +8004,14 @@ var init_sse_manager = __esm({
       setup() {
         if (!this.eventBus) return;
         const events = [
-          "session:created",
-          "session:updated",
-          "session:deleted",
-          "agent:event",
-          "permission:request",
-          "permission:resolved",
-          "message:queued",
-          "message:processing"
+          BusEvent.SESSION_CREATED,
+          BusEvent.SESSION_UPDATED,
+          BusEvent.SESSION_DELETED,
+          BusEvent.AGENT_EVENT,
+          BusEvent.PERMISSION_REQUEST,
+          BusEvent.PERMISSION_RESOLVED,
+          BusEvent.MESSAGE_QUEUED,
+          BusEvent.MESSAGE_PROCESSING
         ];
         for (const eventName of events) {
           const handler = (data) => {
@@ -7970,12 +8074,12 @@ data: ${JSON.stringify(data)}
 
 `;
         const sessionEvents = [
-          "agent:event",
-          "permission:request",
-          "permission:resolved",
-          "session:updated",
-          "message:queued",
-          "message:processing"
+          BusEvent.AGENT_EVENT,
+          BusEvent.PERMISSION_REQUEST,
+          BusEvent.PERMISSION_RESOLVED,
+          BusEvent.SESSION_UPDATED,
+          BusEvent.MESSAGE_QUEUED,
+          BusEvent.MESSAGE_PROCESSING
         ];
         for (const res of this.sseConnections) {
           const filter = res.sessionFilter;
@@ -8167,10 +8271,7 @@ var init_sessions = __esm({
       limit: z.coerce.number().int().min(1).max(100).default(50),
       offset: z.coerce.number().int().min(0).default(0)
     });
-    WorkspaceNameSchema = z.string().optional().refine(
-      (v) => v === void 0 || !v.startsWith("/") && !v.startsWith("~"),
-      { message: "workspace must be a relative name, not an absolute path" }
-    );
+    WorkspaceNameSchema = z.string().optional();
     CreateSessionBodySchema = z.object({
       agent: z.string().max(200).optional(),
       workspace: WorkspaceNameSchema,
@@ -8185,7 +8286,7 @@ var init_sessions = __esm({
       channel: z.string().max(200).optional()
     });
     AttachmentInputSchema = z.object({
-      fileName: z.string().regex(/^[a-zA-Z0-9._-]+$/, "fileName must contain only alphanumeric, dot, dash, or underscore characters").max(255),
+      fileName: z.string().min(1).max(255),
       mimeType: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-^_.+]*$/, "mimeType must be a valid MIME type").max(200),
       data: z.string().max(15e6)
       // ~10 MB base64 ≈ 13.3 MB string
@@ -8317,15 +8418,22 @@ async function sessionRoutes(app, deps) {
     const channelId = adapterId ?? "api";
     const resolvedAgent = body.agent || deps.core.configManager.get().defaultAgent;
     const agentDef = deps.core.agentCatalog.resolve(resolvedAgent);
-    const resolvedWorkspace = deps.core.configManager.resolveWorkspace(
-      body.workspace || agentDef?.workingDirectory
-    );
+    let resolvedWorkspace;
+    try {
+      resolvedWorkspace = deps.core.configManager.resolveWorkspace(
+        body.workspace || agentDef?.workingDirectory
+      );
+    } catch (err) {
+      throw new BadRequestError(
+        "INVALID_WORKSPACE",
+        err instanceof Error ? err.message : "Invalid workspace path"
+      );
+    }
     const session = await deps.core.createSession({
       channelId,
       agentName: resolvedAgent,
       workingDirectory: resolvedWorkspace,
-      createThread: !!adapter,
-      initialName: `\u{1F504} ${resolvedAgent} \u2014 New Session`
+      createThread: !!adapter
     });
     return {
       sessionId: session.id,
@@ -8833,6 +8941,7 @@ var init_config2 = __esm({
       defaultAgent: z4.string(),
       workspace: z4.object({
         baseDir: z4.string().default("~/openacp-workspace"),
+        allowExternalWorkspaces: z4.boolean().default(true),
         security: z4.object({
           allowedPaths: z4.array(z4.string()).default([]),
           envWhitelist: z4.array(z4.string()).default([])
@@ -8953,13 +9062,22 @@ var init_config2 = __esm({
         if (input2.startsWith("/") || input2.startsWith("~")) {
           const resolved2 = expandHome3(input2);
           const base = expandHome3(this.config.workspace.baseDir);
-          if (resolved2 === base || resolved2.startsWith(base + path26.sep)) {
-            fs22.mkdirSync(resolved2, { recursive: true });
+          const isInternal = resolved2 === base || resolved2.startsWith(base + path26.sep);
+          if (!isInternal) {
+            if (!this.config.workspace.allowExternalWorkspaces) {
+              throw new Error(
+                `Workspace path "${input2}" is outside base directory "${this.config.workspace.baseDir}". Set allowExternalWorkspaces: true to allow this.`
+              );
+            }
+            if (!fs22.existsSync(resolved2)) {
+              throw new Error(
+                `Workspace path "${input2}" does not exist.`
+              );
+            }
             return resolved2;
           }
-          throw new Error(
-            `Workspace path "${input2}" is outside base directory "${this.config.workspace.baseDir}".`
-          );
+          fs22.mkdirSync(resolved2, { recursive: true });
+          return resolved2;
         }
         const name = input2.replace(/[^a-zA-Z0-9_-]/g, "");
         if (name !== input2) {
@@ -10183,7 +10301,7 @@ function createApiServerPlugin() {
       );
       ctx.registerService("api-server", apiService);
       cleanupInterval = setInterval(() => tokenStore.cleanup(), 60 * 60 * 1e3);
-      ctx.on("system:ready", async () => {
+      ctx.on(BusEvent.SYSTEM_READY, async () => {
         log15.info(
           { configPort: apiConfig.port, configHost: apiConfig.host },
           "API server starting..."
@@ -10235,6 +10353,7 @@ var log15, cachedVersion, api_server_default;
 var init_api_server = __esm({
   "src/plugins/api-server/index.ts"() {
     "use strict";
+    init_events();
     init_log();
     log15 = createChildLogger({ module: "api-server" });
     api_server_default = createApiServerPlugin();
@@ -10679,6 +10798,7 @@ var init_sse_adapter = __esm({
     init_event_buffer();
     init_adapter();
     init_routes();
+    init_events();
     _adapter = null;
     _connectionManager = null;
     plugin = {
@@ -10705,11 +10825,11 @@ var init_sse_adapter = __esm({
         _connectionManager = connectionManager;
         ctx.registerService("adapter:sse", adapter);
         const commandRegistry = ctx.getService("command-registry");
-        ctx.on("session:deleted", (data) => {
+        ctx.on(BusEvent.SESSION_DELETED, (data) => {
           const { sessionId } = data;
           eventBuffer.cleanup(sessionId);
         });
-        ctx.on("session:ended", (data) => {
+        ctx.on(BusEvent.SESSION_ENDED, (data) => {
           const { sessionId } = data;
           eventBuffer.cleanup(sessionId);
         });
@@ -12968,7 +13088,6 @@ var menu_exports = {};
 __export(menu_exports, {
   buildMenuKeyboard: () => buildMenuKeyboard,
   buildSkillMessages: () => buildSkillMessages,
-  handleClear: () => handleClear,
   handleHelp: () => handleHelp,
   handleMenu: () => handleMenu
 });
@@ -13029,31 +13148,11 @@ Each session gets its own topic \u2014 chat there to work with the agent.
 /bypass_permissions \u2014 Toggle bypass permissions
 /handoff \u2014 Continue session in terminal
 /archive \u2014 Archive session topic
-/clear \u2014 Clear assistant history
 
 \u{1F4AC} Need help? Just ask me in this topic!`,
     { parse_mode: "HTML" }
   );
 }
-async function handleClear(ctx, assistant) {
-  if (!assistant) {
-    await ctx.reply("\u26A0\uFE0F Assistant is not available.", { parse_mode: "HTML" });
-    return;
-  }
-  const threadId = ctx.message?.message_thread_id;
-  if (threadId !== assistant.topicId) {
-    await ctx.reply("\u2139\uFE0F /clear only works in the Assistant topic.", { parse_mode: "HTML" });
-    return;
-  }
-  await ctx.reply("\u{1F504} Clearing assistant history...", { parse_mode: "HTML" });
-  try {
-    await assistant.respawn();
-    await ctx.reply("\u2705 Assistant history cleared.", { parse_mode: "HTML" });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    await ctx.reply(`\u274C Failed to clear: <code>${message}</code>`, { parse_mode: "HTML" });
-  }
-}
 function buildSkillMessages(commands) {
   const sorted = [...commands].sort((a, b) => a.name.localeCompare(b.name));
   const header2 = "\u{1F6E0} <b>Available Skills</b>\n";
@@ -14703,7 +14802,6 @@ var init_commands3 = __esm({
       { command: "menu", description: "Show menu" },
       { command: "integrate", description: "Manage agent integrations" },
       { command: "handoff", description: "Continue this session in your terminal" },
-      { command: "clear", description: "Clear assistant history" },
       { command: "restart", description: "Restart OpenACP" },
       { command: "update", description: "Update to latest version and restart" },
       { command: "doctor", description: "Run system diagnostics" },
@@ -16467,6 +16565,7 @@ var log29, TelegramAdapter;
 var init_adapter2 = __esm({
   "src/plugins/telegram/adapter.ts"() {
     "use strict";
+    init_events();
     init_log();
     init_topics2();
     init_commands3();
@@ -16936,7 +17035,7 @@ ${p2}` : p2;
             log29.warn({ err, sessionId }, "Failed to send initial messages for new session");
           });
         };
-        this.core.eventBus.on("session:threadReady", this._threadReadyHandler);
+        this.core.eventBus.on(BusEvent.SESSION_THREAD_READY, this._threadReadyHandler);
         this._configChangedHandler = ({ sessionId }) => {
           this.updateControlMessage(sessionId).catch(() => {
           });
@@ -16969,7 +17068,7 @@ ${p2}` : p2;
           log29.warn({ err }, "Failed to send welcome message");
         }
         try {
-          await this.core.assistantManager.spawn("telegram", String(this.assistantTopicId));
+          await this.core.assistantManager.getOrSpawn("telegram", String(this.assistantTopicId));
         } catch (err) {
           log29.error({ err }, "Failed to spawn assistant");
         }
@@ -17028,7 +17127,7 @@ OpenACP will automatically retry until this is resolved.`;
         }
         this.sessionTrackers.clear();
         if (this._threadReadyHandler) {
-          this.core.eventBus.off("session:threadReady", this._threadReadyHandler);
+          this.core.eventBus.off(BusEvent.SESSION_THREAD_READY, this._threadReadyHandler);
           this._threadReadyHandler = void 0;
         }
         if (this._configChangedHandler) {
@@ -18832,6 +18931,47 @@ var init_typed_emitter = __esm({
   }
 });
 
+// src/core/agents/attachment-blocks.ts
+function buildAttachmentNote(att, capabilities) {
+  const tooLarge = att.size > MAX_ATTACHMENT_SIZE;
+  if (tooLarge) {
+    const sizeMB = Math.round(att.size / 1024 / 1024);
+    return `[Attachment skipped: "${att.fileName}" is too large (${sizeMB}MB > 10MB limit)]`;
+  }
+  if (att.type === "image") {
+    if (!capabilities.image) {
+      return null;
+    }
+    if (!SUPPORTED_IMAGE_MIMES.has(att.mimeType)) {
+      return `[Attachment skipped: image format not supported (${att.mimeType})]`;
+    }
+    return null;
+  }
+  if (att.type === "audio") {
+    if (!capabilities.audio) {
+      return null;
+    }
+    return null;
+  }
+  return null;
+}
+var SUPPORTED_IMAGE_MIMES, MAX_ATTACHMENT_SIZE;
+var init_attachment_blocks = __esm({
+  "src/core/agents/attachment-blocks.ts"() {
+    "use strict";
+    SUPPORTED_IMAGE_MIMES = /* @__PURE__ */ new Set([
+      "image/jpeg",
+      "image/png",
+      "image/gif",
+      "image/webp",
+      "image/avif",
+      "image/heic",
+      "image/heif"
+    ]);
+    MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024;
+  }
+});
+
 // src/core/sessions/terminal-manager.ts
 import { spawn as spawn7 } from "child_process";
 import { randomUUID } from "crypto";
@@ -18840,6 +18980,7 @@ var init_terminal_manager = __esm({
   "src/core/sessions/terminal-manager.ts"() {
     "use strict";
     init_env_filter();
+    init_events();
     TerminalManager = class {
       terminals = /* @__PURE__ */ new Map();
       maxOutputBytes;
@@ -18856,7 +18997,7 @@ var init_terminal_manager = __esm({
           for (const ev of termEnvArr) {
             envRecord[ev.name] = ev.value;
           }
-          const result = await middlewareChain.execute("terminal:beforeCreate", {
+          const result = await middlewareChain.execute(Hook.TERMINAL_BEFORE_CREATE, {
             sessionId,
             command: termCommand,
             args: termArgs,
@@ -18910,7 +19051,7 @@ var init_terminal_manager = __esm({
         childProcess.on("exit", (code, signal) => {
           state.exitStatus = { exitCode: code, signal };
           if (middlewareChain) {
-            middlewareChain.execute("terminal:afterExit", {
+            middlewareChain.execute(Hook.TERMINAL_AFTER_EXIT, {
               sessionId,
               terminalId,
               command: state.command,
@@ -19124,10 +19265,12 @@ var init_agent_instance = __esm({
     init_stderr_capture();
     init_typed_emitter();
     init_read_text_file();
+    init_attachment_blocks();
     init_terminal_manager();
     init_mcp_manager();
     init_debug_tracer();
     init_log();
+    init_events();
     log31 = createChildLogger({ module: "agent-instance" });
     AgentInstance = class _AgentInstance extends TypedEmitter {
       connection;
@@ -19155,7 +19298,7 @@ var init_agent_instance = __esm({
         super();
         this.agentName = agentName;
       }
-      static async spawnSubprocess(agentDef, workingDirectory) {
+      static async spawnSubprocess(agentDef, workingDirectory, allowedPaths = []) {
         const instance = new _AgentInstance(agentDef.name);
         const resolved = resolveAgentCommand(agentDef.command);
         log31.debug(
@@ -19169,10 +19312,7 @@ var init_agent_instance = __esm({
         const ignorePatterns = PathGuard.loadIgnoreFile(workingDirectory);
         instance.pathGuard = new PathGuard({
           cwd: workingDirectory,
-          // allowedPaths is wired from workspace.security.allowedPaths config;
-          // spawnSubprocess would need to receive a SecurityConfig param to use it.
-          // Tracked as follow-up: pass workspace security config through spawn/resume call chain.
-          allowedPaths: [],
+          allowedPaths,
           ignorePatterns
         });
         instance.child = spawn8(
@@ -19266,7 +19406,7 @@ var init_agent_instance = __esm({
           if (signal === "SIGINT" || signal === "SIGTERM") return;
           if (code !== 0 && code !== null || signal) {
             const stderr = this.stderrCapture.getLastLines();
-            this.emit("agent_event", {
+            this.emit(SessionEv.AGENT_EVENT, {
               type: "error",
               message: signal ? `Agent killed by signal ${signal}
 ${stderr}` : `Agent crashed (exit code ${code})
@@ -19278,7 +19418,7 @@ ${stderr}`
           log31.debug({ sessionId: this.sessionId }, "ACP connection closed");
         });
       }
-      static async spawn(agentDef, workingDirectory, mcpServers) {
+      static async spawn(agentDef, workingDirectory, mcpServers, allowedPaths) {
         log31.debug(
           { agentName: agentDef.name, command: agentDef.command },
           "Spawning agent"
@@ -19286,7 +19426,8 @@ ${stderr}`
         const spawnStart = Date.now();
         const instance = await _AgentInstance.spawnSubprocess(
           agentDef,
-          workingDirectory
+          workingDirectory,
+          allowedPaths
         );
         const resolvedMcp = _AgentInstance.mcpManager.resolve(mcpServers);
         const response = await instance.connection.newSession({
@@ -19309,12 +19450,13 @@ ${stderr}`
         );
         return instance;
       }
-      static async resume(agentDef, workingDirectory, agentSessionId, mcpServers) {
+      static async resume(agentDef, workingDirectory, agentSessionId, mcpServers, allowedPaths) {
         log31.debug({ agentName: agentDef.name, agentSessionId }, "Resuming agent");
         const spawnStart = Date.now();
         const instance = await _AgentInstance.spawnSubprocess(
           agentDef,
-          workingDirectory
+          workingDirectory,
+          allowedPaths
         );
         const resolvedMcp = _AgentInstance.mcpManager.resolve(mcpServers);
         try {
@@ -19502,7 +19644,7 @@ ${stderr}`
                 return;
             }
             if (event !== null) {
-              self.emit("agent_event", event);
+              self.emit(SessionEv.AGENT_EVENT, event);
             }
           },
           // ── Permission requests ──────────────────────────────────────────────
@@ -19529,7 +19671,7 @@ ${stderr}`
               throw new Error(`[Access denied] ${pathCheck.reason}`);
             }
             if (self.middlewareChain) {
-              const result = await self.middlewareChain.execute("fs:beforeRead", { sessionId: self.sessionId, path: p2.path, line: p2.line, limit: p2.limit }, async (r) => r);
+              const result = await self.middlewareChain.execute(Hook.FS_BEFORE_READ, { sessionId: self.sessionId, path: p2.path, line: p2.line, limit: p2.limit }, async (r) => r);
               if (!result) return { content: "" };
               p2.path = result.path;
             }
@@ -19547,7 +19689,7 @@ ${stderr}`
               throw new Error(`[Access denied] ${pathCheck.reason}`);
             }
             if (self.middlewareChain) {
-              const result = await self.middlewareChain.execute("fs:beforeWrite", { sessionId: self.sessionId, path: writePath, content: writeContent }, async (r) => r);
+              const result = await self.middlewareChain.execute(Hook.FS_BEFORE_WRITE, { sessionId: self.sessionId, path: writePath, content: writeContent }, async (r) => r);
               if (!result) return {};
               writePath = result.path;
               writeContent = result.content;
@@ -19644,10 +19786,16 @@ ${stderr}`
       // ── Prompt & lifecycle ──────────────────────────────────────────────
       async prompt(text6, attachments) {
         const contentBlocks = [{ type: "text", text: text6 }];
-        const SUPPORTED_IMAGE_MIMES = /* @__PURE__ */ new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+        const capabilities = this.promptCapabilities ?? {};
         for (const att of attachments ?? []) {
-          const tooLarge = att.size > 10 * 1024 * 1024;
-          if (att.type === "image" && this.promptCapabilities?.image && !tooLarge && SUPPORTED_IMAGE_MIMES.has(att.mimeType)) {
+          const skipNote = buildAttachmentNote(att, capabilities);
+          if (skipNote !== null) {
+            contentBlocks[0].text += `
+
+${skipNote}`;
+            continue;
+          }
+          if (att.type === "image" && capabilities.image && SUPPORTED_IMAGE_MIMES.has(att.mimeType)) {
             const attCheck = this.pathGuard.validatePath(att.filePath, "read");
             if (!attCheck.allowed) {
               contentBlocks[0].text += `
@@ -19657,7 +19805,7 @@ ${stderr}`
             }
             const data = await fs40.promises.readFile(att.filePath);
             contentBlocks.push({ type: "image", data: data.toString("base64"), mimeType: att.mimeType });
-          } else if (att.type === "audio" && this.promptCapabilities?.audio && !tooLarge) {
+          } else if (att.type === "audio" && capabilities.audio) {
             const attCheck = this.pathGuard.validatePath(att.filePath, "read");
             if (!attCheck.allowed) {
               contentBlocks[0].text += `
@@ -19668,9 +19816,9 @@ ${stderr}`
             const data = await fs40.promises.readFile(att.filePath);
             contentBlocks.push({ type: "audio", data: data.toString("base64"), mimeType: att.mimeType });
           } else {
-            if ((att.type === "image" || att.type === "audio") && !tooLarge) {
+            if (att.type === "image" || att.type === "audio") {
               log31.debug(
-                { type: att.type, capabilities: this.promptCapabilities ?? {} },
+                { type: att.type, capabilities },
                 "Agent does not support %s content, falling back to file path",
                 att.type
               );
@@ -19733,15 +19881,15 @@ var init_agent_manager = __esm({
       getAgent(name) {
         return this.catalog.resolve(name);
       }
-      async spawn(agentName, workingDirectory) {
+      async spawn(agentName, workingDirectory, allowedPaths) {
         const agentDef = this.getAgent(agentName);
         if (!agentDef) throw new Error(`Agent "${agentName}" is not installed. Run "openacp agents install ${agentName}" to add it.`);
-        return AgentInstance.spawn(agentDef, workingDirectory);
+        return AgentInstance.spawn(agentDef, workingDirectory, void 0, allowedPaths);
       }
-      async resume(agentName, workingDirectory, agentSessionId) {
+      async resume(agentName, workingDirectory, agentSessionId, allowedPaths) {
         const agentDef = this.getAgent(agentName);
         if (!agentDef) throw new Error(`Agent "${agentName}" is not installed. Run "openacp agents install ${agentName}" to add it.`);
-        return AgentInstance.resume(agentDef, workingDirectory, agentSessionId);
+        return AgentInstance.resume(agentDef, workingDirectory, agentSessionId, void 0, allowedPaths);
       }
     };
   }
@@ -19938,6 +20086,7 @@ var init_session2 = __esm({
     init_permission_gate();
     init_log();
     init_turn_context();
+    init_events();
     moduleLog = createChildLogger({ module: "session" });
     TTS_PROMPT_INSTRUCTION = `
 
@@ -19966,7 +20115,15 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       }
       agentName;
       workingDirectory;
-      agentInstance;
+      _agentInstance;
+      get agentInstance() {
+        return this._agentInstance;
+      }
+      set agentInstance(agent) {
+        this._agentInstance = agent;
+        this.wireAgentRelay();
+        this.wireCommandsBuffer();
+      }
       agentSessionId = "";
       _status = "initializing";
       name;
@@ -19990,9 +20147,6 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       threadIds = /* @__PURE__ */ new Map();
       /** Active turn context — sealed on prompt dequeue, cleared on turn end */
       activeTurnContext = null;
-      /** The agentInstance for which the agent→session event relay is wired (prevents duplicate relays from multiple bridges).
-       *  When the agent is swapped, the relay must be re-wired to the new instance. */
-      agentRelaySource = null;
       permissionGate = new PermissionGate();
       queue;
       speechService;
@@ -20016,23 +20170,37 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
             this.log.error({ err }, "Prompt execution failed");
             const message = err instanceof Error ? err.message : String(err);
             this.fail(message);
-            this.emit("agent_event", { type: "error", message: `Prompt execution failed: ${message}` });
+            this.emit(SessionEv.AGENT_EVENT, { type: "error", message: `Prompt execution failed: ${message}` });
           }
         );
-        this.wireCommandsBuffer();
+      }
+      /** Wire the agent→session event relay on the current agentInstance.
+       *  Removes any previous relay first to avoid duplicates on agent switch.
+       *  This relay ensures session.emit("agent_event") fires for ALL sessions,
+       *  including headless API sessions that have no SessionBridge attached. */
+      agentRelayCleanup;
+      wireAgentRelay() {
+        this.agentRelayCleanup?.();
+        const instance = this._agentInstance;
+        const handler = (event) => {
+          this.emit(SessionEv.AGENT_EVENT, event);
+        };
+        instance.on(SessionEv.AGENT_EVENT, handler);
+        this.agentRelayCleanup = () => instance.off(SessionEv.AGENT_EVENT, handler);
       }
       /** Wire a listener on the current agentInstance to buffer commands_update events.
        *  Must be called after every agentInstance replacement (constructor + switchAgent). */
       commandsBufferCleanup;
       wireCommandsBuffer() {
         this.commandsBufferCleanup?.();
+        const instance = this._agentInstance;
         const handler = (event) => {
           if (event.type === "commands_update") {
             this.latestCommands = event.commands;
           }
         };
-        this.agentInstance.on("agent_event", handler);
-        this.commandsBufferCleanup = () => this.agentInstance.off("agent_event", handler);
+        instance.on(SessionEv.AGENT_EVENT, handler);
+        this.commandsBufferCleanup = () => instance.off(SessionEv.AGENT_EVENT, handler);
       }
       // --- State Machine ---
       get status() {
@@ -20046,12 +20214,12 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       fail(reason) {
         if (this._status === "error") return;
         this.transition("error");
-        this.emit("error", new Error(reason));
+        this.emit(SessionEv.ERROR, new Error(reason));
       }
       /** Transition to finished — from active only. Emits session_end for backward compat. */
       finish(reason) {
         this.transition("finished");
-        this.emit("session_end", reason ?? "completed");
+        this.emit(SessionEv.SESSION_END, reason ?? "completed");
       }
       /** Transition to cancelled — from active only (terminal session cancel) */
       markCancelled() {
@@ -20067,7 +20235,7 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
         }
         this._status = to;
         this.log.debug({ from, to }, "Session status transition");
-        this.emit("status_change", from, to);
+        this.emit(SessionEv.STATUS_CHANGE, from, to);
       }
       /** Number of prompts waiting in queue */
       get queueDepth() {
@@ -20089,8 +20257,8 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       async enqueuePrompt(text6, attachments, routing, externalTurnId) {
         const turnId = externalTurnId ?? nanoid4(8);
         if (this.middlewareChain) {
-          const payload = { text: text6, attachments, sessionId: this.id };
-          const result = await this.middlewareChain.execute("agent:beforePrompt", payload, async (p2) => p2);
+          const payload = { text: text6, attachments, sessionId: this.id, sourceAdapterId: routing?.sourceAdapterId };
+          const result = await this.middlewareChain.execute(Hook.AGENT_BEFORE_PROMPT, payload, async (p2) => p2);
           if (!result) return turnId;
           text6 = result.text;
           attachments = result.attachments;
@@ -20105,9 +20273,9 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
           routing?.responseAdapterId,
           turnId
         );
-        this.emit("turn_started", this.activeTurnContext);
+        this.emit(SessionEv.TURN_STARTED, this.activeTurnContext);
         this.promptCount++;
-        this.emit("prompt_count_changed", this.promptCount);
+        this.emit(SessionEv.PROMPT_COUNT_CHANGED, this.promptCount);
         if (this._status === "initializing" || this._status === "cancelled" || this._status === "error") {
           this.activate();
         }
@@ -20136,10 +20304,18 @@ ${text6}`;
           }
         } : null;
         if (accumulatorListener) {
-          this.on("agent_event", accumulatorListener);
+          this.on(SessionEv.AGENT_EVENT, accumulatorListener);
+        }
+        const mw = this.middlewareChain;
+        const afterEventListener = mw ? (event) => {
+          mw.execute(Hook.AGENT_AFTER_EVENT, { sessionId: this.id, event, outgoingMessage: { type: "text", text: "" } }, async (e) => e).catch(() => {
+          });
+        } : null;
+        if (afterEventListener) {
+          this.agentInstance.on(SessionEv.AGENT_EVENT, afterEventListener);
         }
         if (this.middlewareChain) {
-          this.middlewareChain.execute("turn:start", { sessionId: this.id, promptText: processed.text, promptNumber: this.promptCount }, async (p2) => p2).catch(() => {
+          this.middlewareChain.execute(Hook.TURN_START, { sessionId: this.id, promptText: processed.text, promptNumber: this.promptCount }, async (p2) => p2).catch(() => {
           });
         }
         let stopReason = "end_turn";
@@ -20160,10 +20336,13 @@ ${text6}`;
           promptError = err;
         } finally {
           if (accumulatorListener) {
-            this.off("agent_event", accumulatorListener);
+            this.off(SessionEv.AGENT_EVENT, accumulatorListener);
+          }
+          if (afterEventListener) {
+            this.agentInstance.off(SessionEv.AGENT_EVENT, afterEventListener);
           }
           if (this.middlewareChain) {
-            this.middlewareChain.execute("turn:end", { sessionId: this.id, stopReason, durationMs: Date.now() - promptStart }, async (p2) => p2).catch(() => {
+            this.middlewareChain.execute(Hook.TURN_END, { sessionId: this.id, stopReason, durationMs: Date.now() - promptStart }, async (p2) => p2).catch(() => {
             });
           }
           this.activeTurnContext = null;
@@ -20208,7 +20387,7 @@ ${text6}`;
             const audioBuffer = await fs41.promises.readFile(audioPath);
             const result = await this.speechService.transcribe(audioBuffer, audioMime);
             this.log.info({ provider: "stt", duration: result.duration }, "Voice transcribed");
-            this.emit("agent_event", {
+            this.emit(SessionEv.AGENT_EVENT, {
               type: "system_message",
               message: `\u{1F3A4} You said: ${result.text}`
             });
@@ -20217,7 +20396,7 @@ ${text6}`;
 ${result.text}` : result.text;
           } catch (err) {
             this.log.warn({ err }, "STT transcription failed, keeping audio attachment");
-            this.emit("agent_event", {
+            this.emit(SessionEv.AGENT_EVENT, {
               type: "error",
               message: `Voice transcription failed: ${err.message}`
             });
@@ -20251,12 +20430,12 @@ ${result.text}` : result.text;
               timeoutPromise
             ]);
             const base64 = result.audioBuffer.toString("base64");
-            this.emit("agent_event", {
+            this.emit(SessionEv.AGENT_EVENT, {
               type: "audio_content",
               data: base64,
               mimeType: result.mimeType
             });
-            this.emit("agent_event", { type: "tts_strip" });
+            this.emit(SessionEv.AGENT_EVENT, { type: "tts_strip" });
             this.log.info("TTS synthesis completed");
           } finally {
             clearTimeout(ttsTimer);
@@ -20271,19 +20450,19 @@ ${result.text}` : result.text;
         const captureHandler = (event) => {
           if (event.type === "text") title += event.content;
         };
-        this.pause((event) => event !== "agent_event");
-        this.agentInstance.on("agent_event", captureHandler);
+        this.pause((event) => event !== SessionEv.AGENT_EVENT);
+        this.agentInstance.on(SessionEv.AGENT_EVENT, captureHandler);
         try {
           await this.agentInstance.prompt(
             "Summarize this conversation in max 5 words for a topic title. Reply ONLY with the title, nothing else."
           );
           this.name = title.trim().slice(0, 50) || `Session ${this.id.slice(0, 6)}`;
           this.log.info({ name: this.name }, "Session auto-named");
-          this.emit("named", this.name);
+          this.emit(SessionEv.NAMED, this.name);
         } catch {
           this.name = `Session ${this.id.slice(0, 6)}`;
         } finally {
-          this.agentInstance.off("agent_event", captureHandler);
+          this.agentInstance.off(SessionEv.AGENT_EVENT, captureHandler);
           this.clearBuffer();
           this.resume();
         }
@@ -20345,7 +20524,7 @@ ${result.text}` : result.text;
       /** Set session name explicitly and emit 'named' event */
       setName(name) {
         this.name = name;
-        this.emit("named", name);
+        this.emit(SessionEv.NAMED, name);
       }
       /** Send a config option change to the agent and update local state from the response. */
       async setConfigOption(configId, value) {
@@ -20361,7 +20540,7 @@ ${result.text}` : result.text;
       }
       async updateConfigOptions(options) {
         if (this.middlewareChain) {
-          const result = await this.middlewareChain.execute("config:beforeChange", { sessionId: this.id, configId: "options", oldValue: this.configOptions, newValue: options }, async (p2) => p2);
+          const result = await this.middlewareChain.execute(Hook.CONFIG_BEFORE_CHANGE, { sessionId: this.id, configId: "options", oldValue: this.configOptions, newValue: options }, async (p2) => p2);
           if (!result) return;
         }
         this.configOptions = options;
@@ -20381,7 +20560,7 @@ ${result.text}` : result.text;
       /** Cancel the current prompt and clear the queue. Stays in active state. */
       async abortPrompt() {
         if (this.middlewareChain) {
-          const result = await this.middlewareChain.execute("agent:beforeCancel", { sessionId: this.id }, async (p2) => p2);
+          const result = await this.middlewareChain.execute(Hook.AGENT_BEFORE_CANCEL, { sessionId: this.id }, async (p2) => p2);
           if (!result) return;
         }
         this.queue.clear();
@@ -20422,7 +20601,6 @@ ${result.text}` : result.text;
         this.configOptions = [];
         this.latestCommands = null;
         this.applySpawnResponse(newAgent.initialSessionResponse, newAgent.agentCapabilities);
-        this.wireCommandsBuffer();
         this.log.info({ from: this.agentSwitchHistory.at(-1).agentName, to: agentName }, "Agent switched");
       }
       async destroy() {
@@ -20444,6 +20622,7 @@ var init_session_manager = __esm({
   "src/core/sessions/session-manager.ts"() {
     "use strict";
     init_session2();
+    init_events();
     SessionManager = class {
       sessions = /* @__PURE__ */ new Map();
       store;
@@ -20548,18 +20727,18 @@ var init_session_manager = __esm({
           }
         }
         if (this.middlewareChain) {
-          this.middlewareChain.execute("session:afterDestroy", { sessionId }, async (p2) => p2).catch(() => {
+          this.middlewareChain.execute(Hook.SESSION_AFTER_DESTROY, { sessionId }, async (p2) => p2).catch(() => {
           });
         }
       }
       listSessions(channelId) {
-        const all = Array.from(this.sessions.values());
+        const all = Array.from(this.sessions.values()).filter((s) => !s.isAssistant);
         if (channelId) return all.filter((s) => s.channelId === channelId);
         return all;
       }
       listAllSessions(channelId) {
         if (this.store) {
-          let records = this.store.list();
+          let records = this.store.list().filter((r) => !r.isAssistant);
           if (channelId) records = records.filter((r) => r.channelId === channelId);
           return records.map((record) => {
             const live2 = this.sessions.get(record.sessionId);
@@ -20599,7 +20778,7 @@ var init_session_manager = __esm({
             };
           });
         }
-        let live = Array.from(this.sessions.values());
+        let live = Array.from(this.sessions.values()).filter((s) => !s.isAssistant);
         if (channelId) live = live.filter((s) => s.channelId === channelId);
         return live.map((s) => ({
           id: s.id,
@@ -20620,7 +20799,7 @@ var init_session_manager = __esm({
       }
       listRecords(filter) {
         if (!this.store) return [];
-        let records = this.store.list();
+        let records = this.store.list().filter((r) => !r.isAssistant);
         if (filter?.statuses?.length) {
           records = records.filter((r) => filter.statuses.includes(r.status));
         }
@@ -20629,7 +20808,7 @@ var init_session_manager = __esm({
       async removeRecord(sessionId) {
         if (!this.store) return;
         await this.store.remove(sessionId);
-        this.eventBus?.emit("session:deleted", { sessionId });
+        this.eventBus?.emit(BusEvent.SESSION_DELETED, { sessionId });
       }
       /**
        * Graceful shutdown: persist session state without killing agent subprocesses.
@@ -20677,7 +20856,7 @@ var init_session_manager = __esm({
         this.sessions.clear();
         if (this.middlewareChain) {
           for (const sessionId of sessionIds) {
-            this.middlewareChain.execute("session:afterDestroy", { sessionId }, async (p2) => p2).catch(() => {
+            this.middlewareChain.execute(Hook.SESSION_AFTER_DESTROY, { sessionId }, async (p2) => p2).catch(() => {
             });
           }
         }
@@ -20694,6 +20873,7 @@ var init_session_bridge = __esm({
     init_log();
     init_bypass_detection();
     init_turn_context();
+    init_events();
     log32 = createChildLogger({ module: "session-bridge" });
     SessionBridge = class {
       constructor(session, adapter, deps, adapterId) {
@@ -20718,7 +20898,7 @@ var init_session_bridge = __esm({
         try {
           const mw = this.deps.middlewareChain;
           if (mw) {
-            const result = await mw.execute("message:outgoing", { sessionId, message }, async (m) => m);
+            const result = await mw.execute(Hook.MESSAGE_OUTGOING, { sessionId, message }, async (m) => m);
             this.tracer?.log("core", { step: "middleware:outgoing", sessionId, hook: "message:outgoing", blocked: !result });
             if (!result) return;
             this.tracer?.log("core", { step: "dispatch", sessionId, message: result.message });
@@ -20747,17 +20927,11 @@ var init_session_bridge = __esm({
       connect() {
         if (this.connected) return;
         this.connected = true;
-        if (this.session.agentRelaySource !== this.session.agentInstance) {
-          this.listen(this.session.agentInstance, "agent_event", (event) => {
-            this.session.emit("agent_event", event);
-          });
-          this.session.agentRelaySource = this.session.agentInstance;
-        }
-        this.listen(this.session, "agent_event", (event) => {
+        this.listen(this.session, SessionEv.AGENT_EVENT, (event) => {
           if (this.shouldForward(event)) {
             this.dispatchAgentEvent(event);
           } else {
-            this.deps.eventBus?.emit("agent:event", { sessionId: this.session.id, event });
+            this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, { sessionId: this.session.id, event });
           }
         });
         if (!this.session.agentInstance.onPermissionRequest || this.session.agentInstance.onPermissionRequest.__bridgeId === void 0) {
@@ -20767,7 +20941,7 @@ var init_session_bridge = __esm({
           handler.__bridgeId = this.adapterId;
           this.session.agentInstance.onPermissionRequest = handler;
         }
-        this.listen(this.session, "permission_request", async (request) => {
+        this.listen(this.session, SessionEv.PERMISSION_REQUEST, async (request) => {
           const current = this.session.agentInstance.onPermissionRequest;
           if (current?.__bridgeId === this.adapterId) return;
           if (!this.session.permissionGate.isPending) return;
@@ -20777,37 +20951,41 @@ var init_session_bridge = __esm({
             log32.error({ err, sessionId: this.session.id, adapterId: this.adapterId }, "Failed to send permission request to adapter");
           }
         });
-        this.listen(this.session, "status_change", (from, to) => {
+        this.listen(this.session, SessionEv.STATUS_CHANGE, (from, to) => {
           this.deps.sessionManager.patchRecord(this.session.id, {
             status: to,
             lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
           });
-          this.deps.eventBus?.emit("session:updated", {
-            sessionId: this.session.id,
-            status: to
-          });
+          if (!this.session.isAssistant) {
+            this.deps.eventBus?.emit(BusEvent.SESSION_UPDATED, {
+              sessionId: this.session.id,
+              status: to
+            });
+          }
           if (to === "finished") {
             queueMicrotask(() => this.disconnect());
           }
         });
-        this.listen(this.session, "named", async (name) => {
+        this.listen(this.session, SessionEv.NAMED, async (name) => {
           const record = this.deps.sessionManager.getSessionRecord(this.session.id);
           const alreadyNamed = !!record?.name;
           await this.deps.sessionManager.patchRecord(this.session.id, { name });
-          this.deps.eventBus?.emit("session:updated", {
-            sessionId: this.session.id,
-            name
-          });
+          if (!this.session.isAssistant) {
+            this.deps.eventBus?.emit(BusEvent.SESSION_UPDATED, {
+              sessionId: this.session.id,
+              name
+            });
+          }
           if (!alreadyNamed) {
             await this.adapter.renameSessionThread(this.session.id, name);
           }
         });
-        this.listen(this.session, "prompt_count_changed", (count) => {
+        this.listen(this.session, SessionEv.PROMPT_COUNT_CHANGED, (count) => {
           this.deps.sessionManager.patchRecord(this.session.id, { currentPromptCount: count });
         });
-        this.listen(this.session, "turn_started", (ctx) => {
+        this.listen(this.session, SessionEv.TURN_STARTED, (ctx) => {
           if (ctx.sourceAdapterId !== "sse" && ctx.sourceAdapterId !== "api") {
-            this.deps.eventBus?.emit("message:processing", {
+            this.deps.eventBus?.emit(BusEvent.MESSAGE_PROCESSING, {
               sessionId: this.session.id,
               turnId: ctx.turnId,
               sourceAdapterId: ctx.sourceAdapterId,
@@ -20816,10 +20994,10 @@ var init_session_bridge = __esm({
           }
         });
         if (this.session.latestCommands !== null) {
-          this.session.emit("agent_event", { type: "commands_update", commands: this.session.latestCommands });
+          this.session.emit(SessionEv.AGENT_EVENT, { type: "commands_update", commands: this.session.latestCommands });
         }
         if (this.session.configOptions.length > 0) {
-          this.session.emit("agent_event", { type: "config_option_update", options: this.session.configOptions });
+          this.session.emit(SessionEv.AGENT_EVENT, { type: "config_option_update", options: this.session.configOptions });
         }
       }
       disconnect() {
@@ -20839,17 +21017,11 @@ var init_session_bridge = __esm({
         const mw = this.deps.middlewareChain;
         if (mw) {
           try {
-            const result = await mw.execute("agent:beforeEvent", { sessionId: this.session.id, event }, async (e) => e);
+            const result = await mw.execute(Hook.AGENT_BEFORE_EVENT, { sessionId: this.session.id, event }, async (e) => e);
             this.tracer?.log("core", { step: "middleware:before", sessionId: this.session.id, hook: "agent:beforeEvent", blocked: !result });
             if (!result) return;
             const transformedEvent = result.event;
-            const outgoing = this.handleAgentEvent(transformedEvent);
-            mw.execute("agent:afterEvent", {
-              sessionId: this.session.id,
-              event: transformedEvent,
-              outgoingMessage: outgoing ?? { type: "text", text: "" }
-            }, async (e) => e).catch(() => {
-            });
+            this.handleAgentEvent(transformedEvent);
           } catch {
             try {
               this.handleAgentEvent(event);
@@ -20982,7 +21154,7 @@ var init_session_bridge = __esm({
             this.adapter.stripTTSBlock?.(this.session.id);
             break;
         }
-        this.deps.eventBus?.emit("agent:event", {
+        this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, {
           sessionId: this.session.id,
           event
         });
@@ -21001,7 +21173,7 @@ var init_session_bridge = __esm({
         let permReq = request;
         if (mw) {
           const payload = { sessionId: this.session.id, request, autoResolve: void 0 };
-          const result = await mw.execute("permission:beforeRequest", payload, async (r) => r);
+          const result = await mw.execute(Hook.PERMISSION_BEFORE_REQUEST, payload, async (r) => r);
           if (!result) return "";
           permReq = result.request;
           if (result.autoResolve) {
@@ -21009,21 +21181,21 @@ var init_session_bridge = __esm({
             return result.autoResolve;
           }
         }
-        this.deps.eventBus?.emit("permission:request", {
+        this.deps.eventBus?.emit(BusEvent.PERMISSION_REQUEST, {
           sessionId: this.session.id,
           permission: permReq
         });
         const autoDecision = this.checkAutoApprove(permReq);
         if (autoDecision) {
-          this.session.emit("permission_request", permReq);
+          this.session.emit(SessionEv.PERMISSION_REQUEST, permReq);
           this.emitAfterResolve(mw, permReq.id, autoDecision, "system", startTime);
           return autoDecision;
         }
         const promise = this.session.permissionGate.setPending(permReq);
-        this.session.emit("permission_request", permReq);
+        this.session.emit(SessionEv.PERMISSION_REQUEST, permReq);
         await this.adapter.sendPermissionRequest(this.session.id, permReq);
         const optionId = await promise;
-        this.deps.eventBus?.emit("permission:resolved", {
+        this.deps.eventBus?.emit(BusEvent.PERMISSION_RESOLVED, {
           sessionId: this.session.id,
           requestId: permReq.id,
           decision: optionId,
@@ -21055,7 +21227,7 @@ var init_session_bridge = __esm({
       /** Emit permission:afterResolve middleware hook (fire-and-forget) */
       emitAfterResolve(mw, requestId, decision, userId, startTime) {
         if (mw) {
-          mw.execute("permission:afterResolve", {
+          mw.execute(Hook.PERMISSION_AFTER_RESOLVE, {
             sessionId: this.session.id,
             requestId,
             decision,
@@ -21563,6 +21735,14 @@ var init_session_store = __esm({
         }
         return void 0;
       }
+      findAssistant(channelId) {
+        for (const record of this.records.values()) {
+          if (record.isAssistant === true && record.channelId === channelId) {
+            return record;
+          }
+        }
+        return void 0;
+      }
       list(channelId) {
         const all = [...this.records.values()];
         if (channelId) return all.filter((r) => r.channelId === channelId);
@@ -21642,6 +21822,8 @@ var init_session_store = __esm({
         for (const [id, record] of this.records) {
           if (record.status === "active" || record.status === "initializing")
             continue;
+          if (record.isAssistant === true)
+            continue;
           const raw = record.lastActiveAt;
           if (!raw) continue;
           const lastActive = new Date(raw).getTime();
@@ -21673,6 +21855,7 @@ var init_session_factory = __esm({
     "use strict";
     init_session2();
     init_log();
+    init_events();
     log35 = createChildLogger({ module: "session-factory" });
     SessionFactory = class {
       constructor(agentManager, sessionManager, speechServiceAccessor, eventBus, instanceRoot) {
@@ -21715,7 +21898,7 @@ var init_session_factory = __esm({
             threadId: ""
             // threadId is assigned after session creation
           };
-          const result = await this.middlewareChain.execute("session:beforeCreate", payload, async (p2) => p2);
+          const result = await this.middlewareChain.execute(Hook.SESSION_BEFORE_CREATE, payload, async (p2) => p2);
           if (!result) throw new Error("Session creation blocked by middleware");
           createParams = {
             ...params,
@@ -21724,6 +21907,7 @@ var init_session_factory = __esm({
             channelId: result.channelId
           };
         }
+        const configAllowedPaths = this.configManager?.get().workspace?.security?.allowedPaths ?? [];
         let agentInstance;
         try {
           if (createParams.resumeAgentSessionId) {
@@ -21731,7 +21915,8 @@ var init_session_factory = __esm({
               agentInstance = await this.agentManager.resume(
                 createParams.agentName,
                 createParams.workingDirectory,
-                createParams.resumeAgentSessionId
+                createParams.resumeAgentSessionId,
+                configAllowedPaths
               );
             } catch (resumeErr) {
               log35.warn(
@@ -21740,13 +21925,15 @@ var init_session_factory = __esm({
               );
               agentInstance = await this.agentManager.spawn(
                 createParams.agentName,
-                createParams.workingDirectory
+                createParams.workingDirectory,
+                configAllowedPaths
               );
             }
           } else {
             agentInstance = await this.agentManager.spawn(
               createParams.agentName,
-              createParams.workingDirectory
+              createParams.workingDirectory,
+              configAllowedPaths
             );
           }
         } catch (err) {
@@ -21778,7 +21965,7 @@ var init_session_factory = __esm({
             message: guidanceLines.join("\n")
           };
           const failedSessionId = createParams.existingSessionId ?? `failed-${Date.now()}`;
-          this.eventBus.emit("agent:event", {
+          this.eventBus.emit(BusEvent.AGENT_EVENT, {
             sessionId: failedSessionId,
             event: guidance
           });
@@ -21804,11 +21991,13 @@ var init_session_factory = __esm({
         }
         session.applySpawnResponse(agentInstance.initialSessionResponse, agentInstance.agentCapabilities);
         this.sessionManager.registerSession(session);
-        this.eventBus.emit("session:created", {
-          sessionId: session.id,
-          agent: session.agentName,
-          status: session.status
-        });
+        if (!session.isAssistant) {
+          this.eventBus.emit(BusEvent.SESSION_CREATED, {
+            sessionId: session.id,
+            agent: session.agentName,
+            status: session.status
+          });
+        }
         return session;
       }
       /**
@@ -21826,6 +22015,7 @@ var init_session_factory = __esm({
         if (!this.sessionStore || !this.createFullSession) return null;
         const record = this.sessionStore.get(sessionId);
         if (!record) return null;
+        if (record.isAssistant) return null;
         if (record.status === "error" || record.status === "cancelled") return null;
         const existing = this.resumeLocks.get(sessionId);
         if (existing) return existing;
@@ -21893,6 +22083,7 @@ var init_session_factory = __esm({
           log35.debug({ threadId, channelId }, "No session record found for thread");
           return null;
         }
+        if (record.isAssistant) return null;
         if (record.status === "error" || record.status === "cancelled") {
           log35.warn(
             { threadId, sessionId: record.sessionId, status: record.status },
@@ -22052,9 +22243,9 @@ var init_session_factory = __esm({
         return { session, contextResult };
       }
       wireSideEffects(session, deps) {
-        session.on("agent_event", (event) => {
+        session.on(SessionEv.AGENT_EVENT, (event) => {
           if (event.type !== "usage") return;
-          deps.eventBus.emit("usage:recorded", {
+          deps.eventBus.emit(BusEvent.USAGE_RECORDED, {
             sessionId: session.id,
             agentName: session.agentName,
             timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -22063,7 +22254,7 @@ var init_session_factory = __esm({
             cost: event.cost
           });
         });
-        session.on("status_change", (_from, to) => {
+        session.on(SessionEv.STATUS_CHANGE, (_from, to) => {
           if ((to === "finished" || to === "cancelled") && deps.tunnelService) {
             deps.tunnelService.stopBySession(session.id).then((stopped) => {
               for (const entry of stopped) {
@@ -22091,6 +22282,7 @@ var init_agent_switch_handler = __esm({
     "use strict";
     init_agent_registry();
     init_log();
+    init_events();
     log36 = createChildLogger({ module: "agent-switch" });
     AgentSwitchHandler = class {
       constructor(deps) {
@@ -22116,7 +22308,7 @@ var init_agent_switch_handler = __esm({
         if (!agentDef) throw new Error(`Agent "${toAgent}" is not installed`);
         const fromAgent = session.agentName;
         const middlewareChain = this.deps.getMiddlewareChain();
-        const result = await middlewareChain?.execute("agent:beforeSwitch", {
+        const result = await middlewareChain?.execute(Hook.AGENT_BEFORE_SWITCH, {
           sessionId,
           fromAgent,
           toAgent
@@ -22130,9 +22322,9 @@ var init_agent_switch_handler = __esm({
           type: "system_message",
           message: `Switching from ${fromAgent} to ${toAgent}...`
         };
-        session.emit("agent_event", startEvent);
-        eventBus.emit("agent:event", { sessionId, event: startEvent });
-        eventBus.emit("session:agentSwitch", {
+        session.emit(SessionEv.AGENT_EVENT, startEvent);
+        eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: startEvent });
+        eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
           sessionId,
           fromAgent,
           toAgent,
@@ -22156,11 +22348,12 @@ var init_agent_switch_handler = __esm({
         }
         const fromAgentSessionId = session.agentSessionId;
         const fileService = this.deps.getService("file-service");
+        const configAllowedPaths = configManager.get().workspace?.security?.allowedPaths ?? [];
         try {
           await session.switchAgent(toAgent, async () => {
             if (canResume) {
               try {
-                const instance2 = await agentManager.resume(toAgent, session.workingDirectory, lastEntry.agentSessionId);
+                const instance2 = await agentManager.resume(toAgent, session.workingDirectory, lastEntry.agentSessionId, configAllowedPaths);
                 if (fileService) instance2.addAllowedPath(fileService.baseDir);
                 resumed = true;
                 return instance2;
@@ -22168,7 +22361,7 @@ var init_agent_switch_handler = __esm({
                 log36.warn({ sessionId, toAgent }, "Resume failed, falling back to new agent with context injection");
               }
             }
-            const instance = await agentManager.spawn(toAgent, session.workingDirectory);
+            const instance = await agentManager.spawn(toAgent, session.workingDirectory, configAllowedPaths);
             if (fileService) instance.addAllowedPath(fileService.baseDir);
             try {
               const contextService = this.deps.getService("context");
@@ -22192,9 +22385,9 @@ var init_agent_switch_handler = __esm({
             type: "system_message",
             message: resumed ? `Switched to ${toAgent} (resumed previous session).` : `Switched to ${toAgent} (new session).`
           };
-          session.emit("agent_event", successEvent);
-          eventBus.emit("agent:event", { sessionId, event: successEvent });
-          eventBus.emit("session:agentSwitch", {
+          session.emit(SessionEv.AGENT_EVENT, successEvent);
+          eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: successEvent });
+          eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
             sessionId,
             fromAgent,
             toAgent,
@@ -22207,9 +22400,9 @@ var init_agent_switch_handler = __esm({
             type: "system_message",
             message: `Failed to switch to ${toAgent}: ${errorMessage}`
           };
-          session.emit("agent_event", failedEvent);
-          eventBus.emit("agent:event", { sessionId, event: failedEvent });
-          eventBus.emit("session:agentSwitch", {
+          session.emit(SessionEv.AGENT_EVENT, failedEvent);
+          eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: failedEvent });
+          eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
             sessionId,
             fromAgent,
             toAgent,
@@ -22258,7 +22451,7 @@ var init_agent_switch_handler = __esm({
           currentPromptCount: 0,
           agentSwitchHistory: session.agentSwitchHistory
         });
-        middlewareChain?.execute("agent:afterSwitch", {
+        middlewareChain?.execute(Hook.AGENT_AFTER_SWITCH, {
           sessionId,
           fromAgent,
           toAgent,
@@ -23209,6 +23402,7 @@ var init_lifecycle_manager = __esm({
     init_middleware_chain();
     init_error_tracker();
     init_plugin_context();
+    init_events();
     SETUP_TIMEOUT_MS = 3e4;
     TEARDOWN_TIMEOUT_MS = 1e4;
     LifecycleManager = class {
@@ -23315,7 +23509,7 @@ var init_lifecycle_manager = __esm({
           }
           const registryEntry = this.pluginRegistry?.get(plugin2.name);
           if (registryEntry && registryEntry.enabled === false) {
-            this.eventBus?.emit("plugin:disabled", { name: plugin2.name });
+            this.eventBus?.emit(BusEvent.PLUGIN_DISABLED, { name: plugin2.name });
             continue;
           }
           if (registryEntry && plugin2.migrate && registryEntry.version !== plugin2.version && this.settingsManager) {
@@ -23358,7 +23552,7 @@ var init_lifecycle_manager = __esm({
             if (!validation.valid) {
               this._failed.add(plugin2.name);
               this.getPluginLogger(plugin2.name).error(`Settings validation failed: ${validation.errors?.join("; ")}`);
-              this.eventBus?.emit("plugin:failed", { name: plugin2.name, error: `Settings validation failed: ${validation.errors?.join("; ")}` });
+              this.eventBus?.emit(BusEvent.PLUGIN_FAILED, { name: plugin2.name, error: `Settings validation failed: ${validation.errors?.join("; ")}` });
               continue;
             }
           }
@@ -23381,13 +23575,13 @@ var init_lifecycle_manager = __esm({
             await withTimeout(plugin2.setup(ctx), SETUP_TIMEOUT_MS, `${plugin2.name}.setup()`);
             this.contexts.set(plugin2.name, ctx);
             this._loaded.add(plugin2.name);
-            this.eventBus?.emit("plugin:loaded", { name: plugin2.name, version: plugin2.version });
+            this.eventBus?.emit(BusEvent.PLUGIN_LOADED, { name: plugin2.name, version: plugin2.version });
           } catch (err) {
             this._failed.add(plugin2.name);
             ctx.cleanup();
             console.error(`[lifecycle] Plugin ${plugin2.name} setup() FAILED:`, err);
             this.getPluginLogger(plugin2.name).error(`setup() failed: ${err}`);
-            this.eventBus?.emit("plugin:failed", { name: plugin2.name, error: String(err) });
+            this.eventBus?.emit(BusEvent.PLUGIN_FAILED, { name: plugin2.name, error: String(err) });
           }
         }
       }
@@ -23408,7 +23602,7 @@ var init_lifecycle_manager = __esm({
         this._loaded.delete(name);
         this._failed.delete(name);
         this.loadOrder = this.loadOrder.filter((p2) => p2.name !== name);
-        this.eventBus?.emit("plugin:unloaded", { name });
+        this.eventBus?.emit(BusEvent.PLUGIN_UNLOADED, { name });
       }
       async shutdown() {
         const reversed = [...this.loadOrder].reverse();
@@ -23425,7 +23619,7 @@ var init_lifecycle_manager = __esm({
             ctx.cleanup();
             this.contexts.delete(plugin2.name);
           }
-          this.eventBus?.emit("plugin:unloaded", { name: plugin2.name });
+          this.eventBus?.emit(BusEvent.PLUGIN_UNLOADED, { name: plugin2.name });
         }
         this._loaded.clear();
         this.loadOrder = [];
@@ -23596,21 +23790,25 @@ var init_assistant_manager = __esm({
         this.registry = registry;
       }
       sessions = /* @__PURE__ */ new Map();
-      respawning = /* @__PURE__ */ new Set();
       pendingSystemPrompts = /* @__PURE__ */ new Map();
-      async spawn(channelId, threadId) {
+      async getOrSpawn(channelId, threadId) {
+        const existing = this.core.sessionStore?.findAssistant(channelId);
         const session = await this.core.createSession({
           channelId,
           agentName: this.core.configManager.get().defaultAgent,
           workingDirectory: this.core.configManager.resolveWorkspace(),
           initialName: "Assistant",
           isAssistant: true,
-          threadId
+          threadId,
+          existingSessionId: existing?.sessionId
         });
         this.sessions.set(channelId, session);
         const systemPrompt = this.registry.buildSystemPrompt(channelId);
         this.pendingSystemPrompts.set(channelId, systemPrompt);
-        log41.info({ sessionId: session.id, channelId }, "Assistant spawned (system prompt deferred)");
+        log41.info(
+          { sessionId: session.id, channelId, reused: !!existing },
+          existing ? "Assistant session reused (system prompt deferred)" : "Assistant spawned (system prompt deferred)"
+        );
         return session;
       }
       get(channelId) {
@@ -23631,19 +23829,6 @@ var init_assistant_manager = __esm({
         }
         return false;
       }
-      async respawn(channelId, threadId) {
-        if (this.respawning.has(channelId)) {
-          return this.sessions.get(channelId);
-        }
-        this.respawning.add(channelId);
-        try {
-          const old = this.sessions.get(channelId);
-          if (old) await old.destroy();
-          return await this.spawn(channelId, threadId);
-        } finally {
-          this.respawning.delete(channelId);
-        }
-      }
     };
   }
 });
@@ -23759,6 +23944,39 @@ var init_system = __esm({
   }
 });
 
+// src/core/assistant/sections/remote.ts
+function createRemoteSection() {
+  return {
+    id: "core:remote",
+    title: "Remote Access",
+    priority: 35,
+    buildContext: () => {
+      return `Generate a one-time remote access link so the user can connect to this OpenACP instance from the app or a browser.
+
+The link contains a short-lived code (expires in 30 minutes, single-use) that exchanges for a long-lived token.
+
+Roles:
+  admin   \u2014 full control (default)
+  viewer  \u2014 read-only access
+
+The command automatically includes the tunnel URL if a tunnel is active. Without a tunnel, the local link only works on the same machine.
+
+Always show both the link and QR code when available so the user can choose how to open it.`;
+    },
+    commands: [
+      { command: "openacp remote", description: "Generate remote access link (admin role, 24h expiry)" },
+      { command: "openacp remote --role viewer", description: "Generate read-only access link" },
+      { command: "openacp remote --expire 48h", description: "Generate link with custom expiry" },
+      { command: "openacp remote --no-qr", description: "Skip QR code output" }
+    ]
+  };
+}
+var init_remote = __esm({
+  "src/core/assistant/sections/remote.ts"() {
+    "use strict";
+  }
+});
+
 // src/core/assistant/index.ts
 var init_assistant2 = __esm({
   "src/core/assistant/index.ts"() {
@@ -23770,6 +23988,7 @@ var init_assistant2 = __esm({
     init_agents4();
     init_config5();
     init_system();
+    init_remote();
   }
 });
 
@@ -23880,6 +24099,7 @@ var init_core = __esm({
     init_middleware_chain();
     init_error_tracker();
     init_log();
+    init_events();
     log42 = createChildLogger({ module: "core" });
     OpenACPCore = class {
       configManager;
@@ -24033,6 +24253,7 @@ var init_core = __esm({
         this.assistantRegistry.register(createAgentsSection(this));
         this.assistantRegistry.register(createConfigSection(this));
         this.assistantRegistry.register(createSystemSection());
+        this.assistantRegistry.register(createRemoteSection());
         this.assistantManager = new AssistantManager(this, this.assistantRegistry);
         this.lifecycleManager.serviceRegistry.register("menu-registry", this.menuRegistry, "core");
         this.lifecycleManager.serviceRegistry.register("assistant-registry", this.assistantRegistry, "core");
@@ -24114,7 +24335,7 @@ var init_core = __esm({
         );
         if (this.lifecycleManager?.middlewareChain) {
           const result = await this.lifecycleManager.middlewareChain.execute(
-            "message:incoming",
+            Hook.MESSAGE_INCOMING,
             message,
             async (msg) => msg
           );
@@ -24166,9 +24387,10 @@ ${text6}`;
           }
         }
         const sourceAdapterId = message.routing?.sourceAdapterId ?? message.channelId;
+        const routing = sourceAdapterId !== message.routing?.sourceAdapterId ? { ...message.routing, sourceAdapterId } : message.routing;
         if (sourceAdapterId && sourceAdapterId !== "sse" && sourceAdapterId !== "api") {
           const turnId = nanoid5(8);
-          this.eventBus.emit("message:queued", {
+          this.eventBus.emit(BusEvent.MESSAGE_QUEUED, {
             sessionId: session.id,
             turnId,
             text: text6,
@@ -24177,9 +24399,9 @@ ${text6}`;
             timestamp: (/* @__PURE__ */ new Date()).toISOString(),
             queueDepth: session.queueDepth
           });
-          await session.enqueuePrompt(text6, message.attachments, message.routing, turnId);
+          await session.enqueuePrompt(text6, message.attachments, routing, turnId);
         } else {
-          await session.enqueuePrompt(text6, message.attachments, message.routing);
+          await session.enqueuePrompt(text6, message.attachments, routing);
         }
       }
       // --- Unified Session Creation Pipeline ---
@@ -24223,6 +24445,7 @@ ${text6}`;
           createdAt: session.createdAt.toISOString(),
           lastActiveAt: (/* @__PURE__ */ new Date()).toISOString(),
           name: session.name,
+          isAssistant: params.isAssistant,
           platform: platform2,
           platforms,
           firstAgent: session.firstAgent,
@@ -24238,7 +24461,7 @@ ${text6}`;
             log42.warn({ err, sessionId: session.id }, "Failed to flush pending skill commands");
           });
           if (params.createThread && session.threadId) {
-            this.eventBus.emit("session:threadReady", {
+            this.eventBus.emit(BusEvent.SESSION_THREAD_READY, {
               sessionId: session.id,
               channelId: params.channelId,
               threadId: session.threadId
@@ -24262,6 +24485,36 @@ ${text6}`;
             );
             return allowOption.id;
           };
+          session.on(SessionEv.NAMED, async (name) => {
+            await this.sessionManager.patchRecord(session.id, { name });
+            this.eventBus.emit(BusEvent.SESSION_UPDATED, { sessionId: session.id, name });
+          });
+          const mw = () => this.lifecycleManager?.middlewareChain;
+          session.on(SessionEv.AGENT_EVENT, async (event) => {
+            let processedEvent = event;
+            const chain = mw();
+            if (chain) {
+              const result = await chain.execute(Hook.AGENT_BEFORE_EVENT, { sessionId: session.id, event }, async (e) => e);
+              if (!result) return;
+              processedEvent = result.event;
+            }
+            if (processedEvent.type === "session_end") {
+              session.finish(processedEvent.reason);
+            } else if (processedEvent.type === "error") {
+              session.fail(processedEvent.message);
+            }
+            this.eventBus.emit(BusEvent.AGENT_EVENT, { sessionId: session.id, event: processedEvent });
+          });
+          session.on(SessionEv.STATUS_CHANGE, (_from, to) => {
+            this.sessionManager.patchRecord(session.id, {
+              status: to,
+              lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            this.eventBus.emit(BusEvent.SESSION_UPDATED, { sessionId: session.id, status: to });
+          });
+          session.on(SessionEv.PROMPT_COUNT_CHANGED, (count) => {
+            this.sessionManager.patchRecord(session.id, { currentPromptCount: count });
+          });
         }
         this.sessionFactory.wireSideEffects(session, {
           eventBus: this.eventBus,
@@ -24718,18 +24971,6 @@ Prompts: ${session.promptCount}` };
       return { type: "list", title: "\u{1F4CB} Sessions", items };
     }
   });
-  registry.register({
-    name: "clear",
-    description: "Clear session history",
-    category: "system",
-    handler: async (args2) => {
-      if (!core.assistantManager) return { type: "error", message: "Assistant not available" };
-      const assistant = core.assistantManager.get(args2.channelId);
-      if (!assistant) return { type: "error", message: "No assistant session for this channel." };
-      await core.assistantManager.respawn(args2.channelId, assistant.threadId);
-      return { type: "text", text: "\u2705 Assistant history cleared." };
-    }
-  });
   registry.register({
     name: "newchat",
     description: "New chat, same agent & workspace",
@@ -25256,7 +25497,7 @@ function registerCategoryCommand(registry, core, category, commandName) {
       }
       try {
         await session.setConfigOption(configOption.id, { type: "select", value: raw });
-        core.eventBus.emit("session:configChanged", { sessionId: session.id });
+        core.eventBus.emit(BusEvent.SESSION_CONFIG_CHANGED, { sessionId: session.id });
         return { type: "text", text: labels.successMsg(match.name, configOption.name) };
       } catch (err) {
         log43.error({ err, commandName, configId: configOption.id }, "setConfigOption failed");
@@ -25318,7 +25559,7 @@ function registerDangerousCommand(registry, core) {
         try {
           const targetValue = wantOn ? bypassValue : nonBypassDefault;
           await session.setConfigOption(modeConfig.id, { type: "select", value: targetValue });
-          core.eventBus.emit("session:configChanged", { sessionId: session.id });
+          core.eventBus.emit(BusEvent.SESSION_CONFIG_CHANGED, { sessionId: session.id });
           return {
             type: "text",
             text: wantOn ? "\u2620\uFE0F **Bypass Permissions enabled** \u2014 all permission requests will be auto-approved. The agent can run any action without asking." : "\u{1F510} **Bypass Permissions disabled** \u2014 you will be asked to approve risky actions."
@@ -25333,7 +25574,7 @@ function registerDangerousCommand(registry, core) {
       await core.sessionManager.patchRecord(session.id, {
         clientOverrides: { ...session.clientOverrides }
       });
-      core.eventBus.emit("session:configChanged", { sessionId: session.id });
+      core.eventBus.emit(BusEvent.SESSION_CONFIG_CHANGED, { sessionId: session.id });
       return {
         type: "text",
         text: wantOn ? "\u2620\uFE0F **Bypass Permissions enabled** (client-side) \u2014 all permission requests will be auto-approved.\n\n_Note: This agent doesn't natively support bypass mode, so OpenACP will auto-approve on your behalf._" : "\u{1F510} **Bypass Permissions disabled** \u2014 you will be asked to approve risky actions."
@@ -25353,6 +25594,7 @@ var init_config6 = __esm({
   "src/core/commands/config.ts"() {
     "use strict";
     init_log();
+    init_events();
     init_bypass_detection();
     init_bypass_detection();
     log43 = createChildLogger({ module: "commands/config" });
@@ -26632,7 +26874,7 @@ async function runSetup(configManager, opts) {
     const config = {
       instanceName,
       defaultAgent,
-      workspace: { ...workspace, security: { allowedPaths: [], envWhitelist: [] } },
+      workspace: { ...workspace, allowExternalWorkspaces: true, security: { allowedPaths: [], envWhitelist: [] } },
       logging: {
         level: "info",
         logDir: path56.join(instanceRoot, "logs"),
@@ -27081,7 +27323,7 @@ async function startServer(opts) {
   serviceRegistry.register("field-registry", fieldRegistry, "core");
   registerSystemCommands(commandRegistry, core);
   try {
-    core.eventBus.emit("kernel:booted");
+    core.eventBus.emit(BusEvent.KERNEL_BOOTED);
     core.lifecycleManager.settingsManager = settingsManager;
     core.lifecycleManager.pluginRegistry = pluginRegistry;
     await core.lifecycleManager.boot(corePlugins);
@@ -27194,8 +27436,8 @@ async function startServer(opts) {
     if (tunnelSvc) {
       core.tunnelService = tunnelSvc;
     }
-    core.eventBus.emit("system:commands-ready", { commands: commandRegistry.getAll() });
-    core.eventBus.emit("system:ready");
+    core.eventBus.emit(BusEvent.SYSTEM_COMMANDS_READY, { commands: commandRegistry.getAll() });
+    core.eventBus.emit(BusEvent.SYSTEM_READY);
   } catch (err) {
     if (spinner4) {
       spinner4.fail("Plugin boot failed");
@@ -27431,6 +27673,7 @@ var init_main = __esm({
     init_commands4();
     init_instance_registry();
     init_plugin_field_registry();
+    init_events();
     RESTART_EXIT_CODE = 75;
     shuttingDown = false;
     isDirectExecution = process.argv[1]?.endsWith("main.js");
@@ -28636,6 +28879,14 @@ Connect messaging platforms (Telegram, Discord) to 28+ AI coding agents via ACP
   openacp integrate <agent> --uninstall
   openacp adopt <agent> <id>           Adopt an external session  \x1B[2m[--json]\x1B[0m
 
+\x1B[1mRemote Access:\x1B[0m
+  openacp remote                            Generate one-time remote access link  \x1B[2m[--json]\x1B[0m
+  openacp remote --role admin               Specify role: admin (default) or viewer
+  openacp remote --expire 48h              Set expiry duration (default: 24h)
+  openacp remote --no-tunnel               Local link only (skip tunnel URL)
+  openacp remote --no-qr                   Skip QR code output
+  openacp remote --name <label>            Custom token name
+
 \x1B[1mTunnels:\x1B[0m
   openacp tunnel add <port> [--label name]  Create tunnel to local port  \x1B[2m[--json]\x1B[0m
   openacp tunnel list                       List active tunnels           \x1B[2m[--json]\x1B[0m
@@ -29177,6 +29428,15 @@ async function uninstallPlugin(name, purge, instanceRoot, json = false) {
 init_api_client();
 init_helpers();
 init_output();
+function extractApiError(data, fallback = "API request failed") {
+  const err = data.error;
+  if (!err) return fallback;
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null && "message" in err) {
+    return String(err.message);
+  }
+  return fallback;
+}
 function printApiHelp() {
   console.log(`
 \x1B[1mopenacp api\x1B[0m \u2014 Interact with the running OpenACP daemon
@@ -29470,8 +29730,8 @@ Shows the version of the currently running daemon process.
       });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29494,8 +29754,8 @@ Shows the version of the currently running daemon process.
       });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess({ cancelled: true, sessionId });
@@ -29559,8 +29819,8 @@ Shows the version of the currently running daemon process.
         process.exit(1);
       }
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29606,8 +29866,8 @@ Shows the version of the currently running daemon process.
       });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29622,8 +29882,8 @@ Shows the version of the currently running daemon process.
       const res = await call(`/api/sessions/${encodeURIComponent(sessionId)}`);
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29660,8 +29920,8 @@ Shows the version of the currently running daemon process.
       });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29671,8 +29931,8 @@ Shows the version of the currently running daemon process.
       const res = await call("/api/health");
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29697,8 +29957,8 @@ Shows the version of the currently running daemon process.
       const res = await call("/api/restart", { method: "POST" });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess({ restarted: true });
@@ -29710,8 +29970,8 @@ Shows the version of the currently running daemon process.
         const res = await call("/api/config");
         const data = await res.json();
         if (!res.ok) {
-          if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-          console.error(`Error: ${data.error}`);
+          if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+          console.error(`Error: ${extractApiError(data)}`);
           process.exit(1);
         }
         if (json) jsonSuccess(data);
@@ -29736,8 +29996,8 @@ Shows the version of the currently running daemon process.
         });
         const data = await res.json();
         if (!res.ok) {
-          if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-          console.error(`Error: ${data.error}`);
+          if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+          console.error(`Error: ${extractApiError(data)}`);
           process.exit(1);
         }
         if (json) jsonSuccess(data);
@@ -29769,8 +30029,8 @@ Shows the version of the currently running daemon process.
       const res = await call("/api/tunnel");
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29794,8 +30054,8 @@ Shows the version of the currently running daemon process.
       });
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess({ sent: true });
@@ -29804,8 +30064,8 @@ Shows the version of the currently running daemon process.
       const res = await call("/api/version");
       const data = await res.json();
       if (!res.ok) {
-        if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-        console.error(`Error: ${data.error}`);
+        if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+        console.error(`Error: ${extractApiError(data)}`);
         process.exit(1);
       }
       if (json) jsonSuccess(data);
@@ -29822,8 +30082,8 @@ Shows the version of the currently running daemon process.
         const res = await call(`/api/sessions/${encodeURIComponent(sessionId)}/config`);
         const data = await res.json();
         if (!res.ok) {
-          if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-          console.error(`Error: ${data.error}`);
+          if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+          console.error(`Error: ${extractApiError(data)}`);
           process.exit(1);
         }
         if (json) jsonSuccess(data);
@@ -29871,8 +30131,8 @@ Client overrides: ${JSON.stringify(clientOverrides)}`);
         });
         const data = await res.json();
         if (!res.ok) {
-          if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-          console.error(`Error: ${data.error}`);
+          if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+          console.error(`Error: ${extractApiError(data)}`);
           process.exit(1);
         }
         if (json) jsonSuccess(data);
@@ -29886,8 +30146,8 @@ Client overrides: ${JSON.stringify(clientOverrides)}`);
         const res = await call(`/api/sessions/${encodeURIComponent(sessionId)}/config/overrides`);
         const data = await res.json();
         if (!res.ok) {
-          if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-          console.error(`Error: ${data.error}`);
+          if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+          console.error(`Error: ${extractApiError(data)}`);
           process.exit(1);
         }
         if (json) jsonSuccess(data);
@@ -29915,8 +30175,8 @@ Client overrides: ${JSON.stringify(clientOverrides)}`);
           });
           const data = await res.json();
           if (!res.ok) {
-            if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-            console.error(`Error: ${data.error}`);
+            if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+            console.error(`Error: ${extractApiError(data)}`);
             process.exit(1);
           }
           if (json) jsonSuccess(data);
@@ -29926,8 +30186,8 @@ Client overrides: ${JSON.stringify(clientOverrides)}`);
           const res = await call(`/api/sessions/${encodeURIComponent(sessionId)}/config/overrides`);
           const data = await res.json();
           if (!res.ok) {
-            if (json) jsonError(ErrorCodes.API_ERROR, String(data.error ?? "API request failed"));
-            console.error(`Error: ${data.error}`);
+            if (json) jsonError(ErrorCodes.API_ERROR, extractApiError(data));
+            console.error(`Error: ${extractApiError(data)}`);
             process.exit(1);
           }
           if (json) jsonSuccess(data);