dsh-ntr 0.1.5 → 0.2.0

package/lib/bridge.js

@@ -12,7 +12,7 @@ import { delimiter, dirname, join } from 'node:path';
 import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
-import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, } from "./impl.js";
+import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, permissionRequestFrame, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
 import { DEFAULT_TAG_HALO } from "./protocol.js";
 const STDERR_TAIL_LINES = 40;
 /** Single fs/read_text_file answer cap — agents reading huge files must page via `line`/`limit`. */
@@ -73,9 +73,8 @@ function toAcpMcpServers(defs) {
 }
 const DEFAULT_TUNING = {
     startupTimeoutMs: 60_000,
-    permissionTimeoutMs: 0,
-    permissionFallbackTimeoutMs: 300_000,
-    nativeApprovalTimeoutMs: 300_000,
+    permissionTimeoutMs: 300_000,
+    permissionTimeoutMode: 'wait',
     cancelFallbackMs: 15_000,
     staleCancelRetryDelayMs: 600,
     staleCancelMaxRetries: 2,
@@ -90,7 +89,6 @@ export class AgentBridge {
     onConnectionLost;
     onCatalog;
     onCommands;
-    approvalRequester;
     sessionWorkspace;
     state = 'stopped';
     initResult;
@@ -106,29 +104,18 @@ export class AgentBridge {
     /** Inflight `session/load` resumes, shared so concurrent prompts don't double-resume. */
     resuming = new Map();
     permissions = new PermissionLedger();
-    /**
-     * Why each outstanding ledger ask is on the ledger, keyed by request id and
-     * recorded before the `permission/request` broadcast (the hub is
-     * synchronous, so a subscriber can read it the moment the frame goes out).
-     * Entries live exactly as long as the ask: the ledger's resolve callback
-     * deletes them, and every terminal path (answer, timeout, session close,
-     * process death) resolves through it.
-     */
-    ledgerFallbacks = new Map;
     startupTimeoutMs;
-    permissionTimeoutMs;
     /**
-     * The two approval deadlines are NOT readonly, unlike their neighbors: the
-     * settings page rewrites them on a running bridge
-     * ({@link AgentBridge.applyApprovalDeadlines}), so a user editing the window
-     * does not have to kill every live session to see it take effect. Both are
-     * read per ask — `nativeApprovalTimeoutMs` when the native ask is armed,
-     * `permissionFallbackTimeoutMs` when the ledger ask's deadline is chosen — so
-     * a reassignment reaches every ask from that moment on. An ask already
-     * holding an armed timer keeps the window it was started with.
+     * The ONE approval deadline, and the mode it settles with. Neither is
+     * readonly, unlike their neighbors: the settings page rewrites them on a
+     * running bridge ({@link AgentBridge.applyApprovalDeadlines}), so a user
+     * editing the card does not have to kill every live session to see it take
+     * effect. Both are read per ask, so a reassignment reaches every ask from
+     * that moment on. An ask already holding an armed timer keeps the window it
+     * was started with.
      */
-    permissionFallbackTimeoutMs;
-    nativeApprovalTimeoutMs;
+    permissionTimeoutMs;
+    permissionTimeoutMode;
     cancelFallbackMs;
     staleCancelRetryDelayMs;
     staleCancelMaxRetries;
@@ -176,13 +163,8 @@ export class AgentBridge {
     /** Observes `availableCommands` from any real session so the agent's slash menu survives its sessions. */
     onCommands, tuning, 
     /**
-     * Resolved per ask (not captured) so a requester wired after this bridge
-     * was built still applies. Absent → every ask rides the ledger.
-     */
-    approvalRequester, 
-    /**
-     * Resolved per turn, like {@link approvalRequester}: the host entry may
-     * wire the access-mode mapping after this bridge was built.
+     * Resolved per turn: the host entry may wire the workspace reader after
+     * this bridge was built.
      */
     sessionWorkspace) {
         this.def = def;
@@ -191,13 +173,13 @@ export class AgentBridge {
         this.onConnectionLost = onConnectionLost;
         this.onCatalog = onCatalog;
         this.onCommands = onCommands;
-        this.approvalRequester = approvalRequester;
         this.sessionWorkspace = sessionWorkspace;
         const merged = { ...DEFAULT_TUNING, ...tuning };
         this.startupTimeoutMs = merged.startupTimeoutMs;
-        this.permissionTimeoutMs = merged.permissionTimeoutMs;
-        this.permissionFallbackTimeoutMs = merged.permissionFallbackTimeoutMs;
-        this.nativeApprovalTimeoutMs = merged.nativeApprovalTimeoutMs;
+        this.permissionTimeoutMode = merged.permissionTimeoutMode;
+        // 不等待 (0) is the `auto` mode's business; under `abort` it would refuse
+        // every ask on arrival, so the window is floored to the shortest real wait.
+        this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, merged.permissionTimeoutMs);
         this.cancelFallbackMs = merged.cancelFallbackMs;
         this.staleCancelRetryDelayMs = merged.staleCancelRetryDelayMs;
         this.staleCancelMaxRetries = merged.staleCancelMaxRetries;
@@ -206,20 +188,24 @@ export class AgentBridge {
         this.probeIdleTimeoutMs = merged.probeIdleTimeoutMs;
     }
     /**
-     * Adopt a rewritten approval deadline (the settings page's write). Only the
-     * two degraded-route windows live here; every other tuning value is fixed at
-     * construction, because a live bridge cannot meaningfully adopt a new startup
-     * or cancel window mid-flight.
+     * Adopt a rewritten approval deadline or mode (the settings page's write).
+     * Only the window and the mode live here; every other tuning value is
+     * fixed at construction, because a live bridge cannot meaningfully adopt a
+     * new startup or cancel window mid-flight.
      *
      * Deliberately does NOT re-arm anything: an ask that already holds a timer
      * keeps the window it was started with, and the next ask reads the new value.
      * Re-arming would move the goalposts under a human who is already deciding.
      */
     applyApprovalDeadlines(patch) {
-        if (patch.nativeApprovalTimeoutMs !== undefined)
-            this.nativeApprovalTimeoutMs = patch.nativeApprovalTimeoutMs;
-        if (patch.permissionFallbackTimeoutMs !== undefined)
-            this.permissionFallbackTimeoutMs = patch.permissionFallbackTimeoutMs;
+        if (patch.permissionTimeoutMs !== undefined)
+            this.permissionTimeoutMs = patch.permissionTimeoutMs;
+        if (patch.mode !== undefined)
+            this.permissionTimeoutMode = patch.mode;
+        // A mode switch can leave a window behind that the new mode cannot run
+        // (不等待 under `abort`): floor it, so the ask waits instead of refusing
+        // on arrival.
+        this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, this.permissionTimeoutMs);
     }
     /**
      * The idle-release window this agent honors for its CHAT process: its own
@@ -968,12 +954,15 @@ export class AgentBridge {
         // Closing a session is activity of its own: restart the idle window here
         // rather than at the prompt that opened it.
         this.touch();
+        // Answer every outstanding ask BEFORE `session/close` is awaited: an agent
+        // blocked on an unanswered `session/request_permission` would otherwise be
+        // able to hold the close open indefinitely.
+        this.settlePermissions(session);
         const conn = this.conn;
         if (conn !== undefined && this.state === 'ready') {
             // `session/close` is an optional capability; the local teardown stands regardless.
             await conn.agent.request(methods.agent.session.close, { sessionId: session.acpSessionId }).catch(() => { });
         }
-        this.settlePermissions(session);
         this.sessions.delete(session.sessionId);
         this.acpIndex.delete(session.acpSessionId);
         this.hub.broadcast({ type: 'session/closed', sessionId: session.sessionId, reason });
@@ -1038,26 +1027,57 @@ export class AgentBridge {
         }, 3000).unref();
     }
     /**
-     * Answer one ACP permission ask. Every ask reaches a human: the native
-     * approval chain first (answered in the chat composer), the settings-panel
-     * ledger otherwise.
+     * Answer one ACP permission ask.
+     *
+     * EVERY ask is answered by a human through the plugin's own ledger. The
+     * host's approval chain is deliberately not involved: it could accept an ask
+     * and render nothing, leaving the turn hanging behind something invisible
+     * with no deadline (issue #2). The ledger broadcasts `permission/request`,
+     * the browser renders the answerable card, and `permission/respond` settles
+     * it.
+     *
+     * The host answers on its own only when a deadline expires: `abort` refuses,
+     * `auto` picks the option the agent's own kinds imply, `wait` never expires.
+     * The ACP request's own `signal` (the agent withdrawing the ask, or the
+     * connection dying) settles the same entry cancelled, so a withdrawn ask can
+     * never leave a stale card behind.
      */
     async handlePermissionRequest(acpSessionId, toolCall, options, signal) {
         const session = this.acpIndex.get(acpSessionId);
         if (session === undefined || session.closed)
             return { outcome: { outcome: 'cancelled' } };
-        // Native approval first (answered in the chat composer); a `reason` means
-        // no route is available and the settings-panel ledger takes over.
-        const native = await this.askNativeApproval(session, toolCall, options, signal);
-        if ('response' in native) {
-            this.touch();
-            return native.response;
-        }
+        // The deadline and the mode are read ONCE, here: an ask that started under
+        // one pair keeps it, even if the settings page rewrites them mid-flight.
+        const mode = this.permissionTimeoutMode;
+        const timeoutMs = this.permissionTimeoutMs;
+        // 不等待（0）只属自动推进：请求到达即按那一档收场，不建 ledger 条目、不发卡
+        // ——问都来不及问。超时中止没有这一档（它会立刻拒绝每一问，agent 在每个门口
+        // 都停住），它的窗口最短是真实等待。
+        if (mode === 'auto' && timeoutMs === 0) {
+            return this.settleExpiredAsk(session, mode, toolCall, options, 0);
+        }
+        const optionViews = options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind }));
+        const reason = permissionAskReason(toolCall);
+        // Computed once, at ask creation: the frame, the chat line and the timer
+        // all describe the same instant, and a slow reader cannot stretch it.
+        const deadlineAt = timeoutMs > 0 && mode !== 'wait' ? Date.now() + timeoutMs : undefined;
+        const view = {
+            ...(session.dshSessionId === undefined ? {} : { dshSessionId: session.dshSessionId }),
+            // Kept whole for the reconnect replay: a client that connects after the
+            // ask was broadcast must be re-shown the very card it has to answer.
+            toolCall,
+            toolName: permissionToolName(toolCall),
+            ...(reason === '' ? {} : { reason }),
+            options: optionViews,
+            timeoutMode: mode,
+            ...(deadlineAt === undefined ? {} : { deadlineAt }),
+        };
         return new Promise(resolve => {
             let timer;
+            let detachSignal;
             const requestId = this.permissions.create(session.sessionId, (outcome) => {
                 clearTimeout(timer);
-                this.ledgerFallbacks.delete(requestId);
+                detachSignal?.();
                 this.touch();
                 this.hub.broadcast({
                     type: 'permission/resolved',
@@ -1068,161 +1088,91 @@ export class AgentBridge {
                 resolve(outcome.outcome === 'selected'
                     ? { outcome: { outcome: 'selected', optionId: outcome.optionId } }
                     : { outcome: { outcome: 'cancelled' } });
-            }, {
-                // Kept for the reconnect replay: a client that connects after the ask
-                // was broadcast must be re-shown the very card it has to answer.
-                toolCall,
-                options: options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })),
-            });
-            // Deadline (`permissionTimeoutMs`): an approval left unanswered is
-            // answered `cancelled` on the human's behalf instead of hanging the turn
-            // forever. Off by default — approvals belong to a person. The one
-            // exception is a DEGRADED native route: the conversation just failed to
-            // show the question, so waiting forever would hang the turn behind an
-            // ask nobody can see there, and the fallback deadline applies instead
-            // (see `BridgeTuning.permissionFallbackTimeoutMs`). `native-timeout` is
-            // the same degradation reached from the other side: the host took the
-            // ask and never answered it.
-            const timeoutMs = this.permissionTimeoutMs > 0
-                ? this.permissionTimeoutMs
-                : native.reason === 'unavailable' || native.reason === 'native-timeout'
-                    ? this.permissionFallbackTimeoutMs
-                    : 0;
-            // Recorded before the broadcast: the hub is synchronous, and the chat
-            // line `streamPrompt` folds from this frame words itself by the path
-            // this ask actually took.
-            this.ledgerFallbacks.set(requestId, {
-                reason: native.reason,
-                timeoutMs,
-                ...(native.reason === 'native-timeout' ? { waitedMs: this.nativeApprovalTimeoutMs } : {}),
-            });
-            if (timeoutMs > 0) {
+            }, view);
+            // The live frame and the replay frame come from ONE builder, so a
+            // reconnecting client receives exactly what a live one did.
+            this.hub.broadcast(permissionRequestFrame({ requestId, sessionId: session.sessionId, ...view }));
+            if (deadlineAt !== undefined) {
                 timer = setTimeout(() => {
                     if (!this.permissions.has(requestId))
                         return;
-                    this.hub.broadcast({
-                        type: 'agent/notice',
-                        agentId: this.def.id,
-                        level: 'info',
-                        // Name what was missed, the way a human needs it: which operation
-                        // sat unanswered, and for how long (OmniTerm's reaper writes the
-                        // same "you missed this" notice before it acts).
-                        text: `acp: permission request for "${permissionToolName(toolCall)}" timed out after ${String(Math.round(timeoutMs / 1000))}s; answered "cancelled"`,
-                    });
-                    this.permissions.respond(requestId, { outcome: 'cancelled' });
-                }, timeoutMs);
+                    // Settle IN PLACE: exactly one notice, one `permission/expired` (the
+                    // conversation's trace of the expiry) and the ledger answer.
+                    const outcome = this.announceExpiredAsk(session, mode, toolCall, options, timeoutMs);
+                    this.permissions.respond(requestId, outcome);
+                }, Math.max(0, deadlineAt - Date.now()));
                 timer.unref?.();
             }
-            this.hub.broadcast({
-                type: 'permission/request',
-                requestId,
-                sessionId: session.sessionId,
-                toolCall,
-                options: options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })),
-            });
+            // The agent's own withdrawal settles the entry cancelled; the ledger's
+            // resolve callback broadcasts `permission/resolved`, and drops this
+            // listener, so nothing outlives the ask.
+            if (signal !== undefined) {
+                const onAbort = () => {
+                    if (!this.permissions.has(requestId))
+                        return;
+                    this.permissions.respond(requestId, { outcome: 'cancelled' });
+                };
+                if (signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+                detachSignal = () => { signal.removeEventListener('abort', onAbort); };
+            }
         });
     }
     /**
-     * Why one ledger ask is on the ledger, as recorded by
-     * {@link handlePermissionRequest}. The manager's `streamPrompt` reads it to
-     * word the chat line by the path the ask took; `undefined` once the ask is
-     * answered, timed out, or settled.
-     */
-    ledgerFallbackOf(requestId) {
-        return this.ledgerFallbacks.get(requestId);
-    }
-    /**
-     * Ask the host approval service for this permission (`ctx.approval` → the
-     * browser's composer takeover). Only sessions bound to a DSH chat session
-     * qualify: the service appends its audit pair to that session inside an
-     * open turn, so a session started over `/acp` (no chat turn) cannot be
-     * routed and must stay on the ledger path.
-     *
-     * The ask is raced against {@link BridgeTuning.nativeApprovalTimeoutMs}. A
-     * routed ask has exactly one answer entry — the composer takeover — and no
-     * broadcast at all, so a host that takes the question and never renders it
-     * would leave the turn hanging behind something invisible. Past the deadline
-     * the ask is WITHDRAWN (the signal handed to the host aborts, which settles
-     * its waterfall `cancelled` and drops the composer panel) and reported as
-     * `native-timeout`, sending the question to the ledger where the chat line
-     * and the settings card are both visible. Withdrawing is not answering: a
-     * human mid-decision finds the same question in the settings panel.
-     *
-     * No deadline is armed on the ledger paths (`no-requester`,
-     * `no-chat-session`): those never reach the host, and their answer entry is
-     * the settings panel the chat line already points at.
-     *
-     * @returns the agent-facing response, or the reason the ask must fall back
-     * to the ledger (see {@link LedgerFallbackReason}).
+     * Announce and compute one ask's expiry. Shared by the 不等待 arrival path
+     * and the ledger deadline, so an expiry can never broadcast two notices or
+     * skip the `permission/expired` line: once the card is gone that frame is
+     * the conversation's only trace of what happened to the question.
      */
-    async askNativeApproval(session, toolCall, options, signal) {
-        const requester = this.approvalRequester?.();
-        if (requester === undefined)
-            return { reason: 'no-requester' };
-        if (session.dshSessionId === undefined)
-            return { reason: 'no-chat-session' };
-        // One signal carries both withdrawals: the agent's own cancel (whatever
-        // aborted the ACP request) and the deadline. The host's waterfall races its
-        // answerers against this signal, so aborting is a clean withdrawal rather
-        // than a leak.
-        const withdraw = new AbortController();
-        const askSignal = signal === undefined ? withdraw.signal : AbortSignal.any([signal, withdraw.signal]);
-        let timer;
-        let timedOut = false;
-        const deadline = this.nativeApprovalTimeoutMs > 0
-            ? new Promise(resolve => {
-                timer = setTimeout(() => {
-                    timedOut = true;
-                    withdraw.abort();
-                    resolve({ timedOut: true });
-                }, this.nativeApprovalTimeoutMs);
-                timer.unref?.();
-            })
+    announceExpiredAsk(session, mode, toolCall, options, timeoutMs) {
+        const picked = mode === 'auto'
+            ? pickAutoOption(options.map(option => ({ optionId: option.optionId, name: option.name, kind: option.kind })))
             : undefined;
-        let outcome;
-        try {
-            const asked = requester({
-                dshSessionId: session.dshSessionId,
-                agentId: this.def.id,
-                toolName: permissionToolName(toolCall),
-                signal: askSignal,
-            });
-            // A withdrawn ask settles on the host's own schedule; dropping it here
-            // must not surface as an unhandled rejection later.
-            asked.catch(() => { });
-            const settled = deadline === undefined
-                ? await asked.then(o => ({ outcome: o }))
-                : await Promise.race([asked.then(o => ({ outcome: o })), deadline]);
-            // The flag, not the race winner, decides: the host may settle `cancelled`
-            // from the very abort the deadline caused, and that is still a timeout.
-            if (timedOut || 'timedOut' in settled)
-                return { reason: 'native-timeout' };
-            outcome = settled.outcome;
-        }
-        catch {
-            // Synchronous throw or rejection, either way: the ask falls back to the
-            // ledger. An approval failure must never break the agent's turn.
-            outcome = 'unavailable';
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        if (outcome === 'unavailable')
-            return { reason: 'unavailable' };
-        const response = nativeOutcomeResponse(outcome, options);
-        // Keep the event stream symmetric with the ledger path: a routed decision
-        // is still a resolution, and the browser uses it to drop any card it may
-        // hold for this session. No `permission/request` is broadcast — the
-        // settings panel must never show a card for a composer-routed ask.
+        const outcome = picked === undefined
+            ? { outcome: 'cancelled' }
+            : { outcome: 'selected', optionId: picked.optionId };
+        const tool = permissionToolName(toolCall);
+        // 不等待（0）不是「等了 0 秒」，是没等：两种说法的区别就在这里。
+        const waited = timeoutMs > 0
+            ? `timed out after ${String(Math.round(timeoutMs / 1000))}s`
+            : 'was not waited for';
         this.hub.broadcast({
-            type: 'permission/resolved',
-            requestId: randomUUID(),
+            type: 'agent/notice',
+            agentId: this.def.id,
+            level: 'info',
+            // Name what was missed and what was done about it — the way a human
+            // needs it: which operation sat unanswered, and what the plugin answered
+            // instead. OmniTerm's reaper writes the same "you missed this" notice.
+            text: picked === undefined
+                ? `acp: permission request for "${tool}" ${waited}; refused`
+                : `acp: permission request for "${tool}" ${waited}; answered "${picked.name}"`,
+        });
+        this.hub.broadcast({
+            type: 'permission/expired',
             sessionId: session.sessionId,
-            outcome: response.outcome.outcome === 'selected'
-                ? { outcome: 'selected', optionId: response.outcome.optionId }
-                : { outcome: 'cancelled' },
+            toolCall,
+            timeoutMs,
+            outcome,
+            ...(picked === undefined ? {} : { optionName: picked.name }),
         });
-        return { response };
+        return outcome;
+    }
+    /**
+     * Settle the 不等待 (`auto` + zero window) ask on arrival: no ledger entry
+     * and no card — nothing asks a human, so there is nothing to show. `auto`
+     * answers with the option the agent's own kinds imply ({@link pickAutoOption})
+     * and the agent CONTINUES. A mode that cannot pick an option (no options, or
+     * none with a usable id) degrades to refusing: safer than guessing, and
+     * hanging is worse than either.
+     */
+    settleExpiredAsk(session, mode, toolCall, options, timeoutMs) {
+        const outcome = this.announceExpiredAsk(session, mode, toolCall, options, timeoutMs);
+        return outcome.outcome === 'selected'
+            ? { outcome: { outcome: 'selected', optionId: outcome.optionId } }
+            : { outcome: { outcome: 'cancelled' } };
     }
     settlePermissions(session) {
         this.permissions.settleFor(p => p.sessionId === session.sessionId);
@@ -1259,7 +1209,7 @@ export class AgentBridge {
      * cannot reach into the agent's own process, so a second gate here would only
      * be a fiction in front of a tool that can write without asking us at all.
      * What the agent chooses to ask about goes to the human unchanged
-     * (`askNativeApproval`). See docs/acp-convergence.md §2.3.
+     * (`handlePermissionRequest`). See docs/acp-convergence.md §2.3.
      */
     async handleFsWrite(params) {
         const session = this.acpIndex.get(params.sessionId);
@@ -1361,20 +1311,57 @@ export function permissionToolName(toolCall) {
         return row.kind;
     return 'tool call';
 }
+/** Longest reason line the approval card headline carries. */
+const APPROVAL_REASON_MAX = 240;
+/** Input keys that name the operation in one string, most specific first. */
+const APPROVAL_REASON_INPUT_KEYS = [
+    'command',
+    'cmd',
+    'path',
+    'file_path',
+    'filePath',
+    'pattern',
+    'query',
+    'url',
+    'description',
+];
 /**
- * Translate a native approval outcome into the ACP option the agent must see.
- * `'allowed-once'` is the chain's only grant; a rejection prefers the once-variant.
+ * One line saying WHAT the permission ask is about.
+ *
+ * WHY: without it the human only sees the tool's NAME ("Bash") and cannot
+ * judge the request; the ACP tool call already declares the missing half — its
+ * title and (for execute/edit tools) a short scalar in `rawInput`. Only ONE declared
+ * string is used, never a serialized object or a whole file, and the line is
+ * capped so a pathological input cannot fill the card or the audit log.
  */
-function nativeOutcomeResponse(outcome, options) {
-    if (outcome === 'allowed-once') {
-        const allow = options.find(o => o.kind === 'allow_once') ?? options.find(o => o.kind === 'allow_always');
-        return allow === undefined ? { outcome: { outcome: 'cancelled' } } : { outcome: { outcome: 'selected', optionId: allow.optionId } };
-    }
-    if (outcome === 'rejected') {
-        const reject = options.find(o => o.kind === 'reject_once') ?? options.find(o => o.kind === 'reject_always');
-        return reject === undefined ? { outcome: { outcome: 'cancelled' } } : { outcome: { outcome: 'selected', optionId: reject.optionId } };
-    }
-    return { outcome: { outcome: 'cancelled' } };
+export function permissionAskReason(toolCall) {
+    const row = (typeof toolCall === 'object' && toolCall !== null ? toolCall : {});
+    const title = permissionToolName(toolCall);
+    const raw = row.rawInput;
+    const input = raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : typeof raw === 'string' && raw.length <= APPROVAL_REASON_MAX * 4
+            // Some agents send the arguments as a JSON string; read one scalar out
+            // of it instead of echoing the blob.
+            ? (() => {
+                try {
+                    const parsed = JSON.parse(raw);
+                    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                        ? parsed
+                        : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })()
+            : undefined;
+    const detail = input === undefined
+        ? undefined
+        : APPROVAL_REASON_INPUT_KEYS
+            .map(key => input[key])
+            .find((value) => typeof value === 'string' && value !== '');
+    const line = detail === undefined || detail === title ? title : `${title} · ${detail}`;
+    return line.length > APPROVAL_REASON_MAX ? `${line.slice(0, APPROVAL_REASON_MAX - 1)}…` : line;
 }
 function snapshot(session) {
     return {
@@ -2077,7 +2064,6 @@ export function releaseAllToolOutputWaiters() {
 class TurnStreamController {
     manager;
     hub;
-    bridge;
     session;
     turnId;
     endTurn;
@@ -2092,12 +2078,11 @@ class TurnStreamController {
     pendingProse = [];
     sawVisibleBlock = false;
     cursorSeq;
-    constructor(manager, hub, bridge, session, turnId, 
+    constructor(manager, hub, session, turnId, 
     /** Releases the agent-side turn slot (the `beginTurn` settler; idempotent). */
     endTurn, rollbackFirstTurn) {
         this.manager = manager;
         this.hub = hub;
-        this.bridge = bridge;
         this.session = session;
         this.turnId = turnId;
         this.endTurn = endTurn;
@@ -2319,24 +2304,36 @@ class TurnStreamController {
         }
         else if (row.type === 'permission/request') {
             const typed = event;
-            const seg = this.segment;
-            const line = this.permissionLine(typed);
-            if (seg === undefined || seg.finished) {
-                if (line !== '')
-                    this.pendingProse.push(line);
-                return;
-            }
-            if (seg.hasCard) {
-                // The card must stay the segment's last block: park the line for the
-                // next segment instead of streaming it below the card.
-                this.pendingProse.push(line);
-                this.finishSegment(seg, { kind: 'stop' });
-                return;
-            }
-            if (line !== '')
-                this.emitProse(seg, 'reasoning', line);
+            this.pushProse(this.permissionLine(typed));
+        }
+        else if (row.type === 'permission/expired') {
+            const typed = event;
+            this.pushProse(this.expiredLine(typed));
         }
     }
+    /**
+     * Put one narrative line into the turn's prose stream.
+     *
+     * A card-bearing segment must stay the segment's LAST block, so a line that
+     * arrives while a card is open is parked for the next segment instead of
+     * streaming below the card. A line that arrives between segments waits for
+     * the next one to open.
+     */
+    pushProse(line) {
+        if (line === '')
+            return;
+        const seg = this.segment;
+        if (seg === undefined || seg.finished) {
+            this.pendingProse.push(line);
+            return;
+        }
+        if (seg.hasCard) {
+            this.pendingProse.push(line);
+            this.finishSegment(seg, { kind: 'stop' });
+            return;
+        }
+        this.emitProse(seg, 'reasoning', line);
+    }
     /** Events that arrive between segments: recorded, replayed into the next one. */
     recordWithoutSegment(update) {
         const kind = String(update.sessionUpdate ?? '');
@@ -2471,30 +2468,46 @@ class TurnStreamController {
         });
     }
     permissionLine(event) {
-        const title = typeof event.toolCall?.title === 'string'
-            ? String(event.toolCall.title)
-            : 'permission';
-        // The line must not point at a place with no answer entry, and the bridge
-        // knows which path this ask took (`ledgerFallbackOf`, recorded before the
-        // frame was broadcast). On the DESIGNED ledger paths the settings panel's
-        // card is the answer entry. A DEGRADED native route carries a deadline and
-        // has to say why the conversation is not showing the question — as an
-        // OBSERVED FACT, not a guessed cause: "no answer within Ns" is true whether
-        // the human was slow or the host never rendered the question.
-        const fallback = this.bridge.ledgerFallbackOf(event.requestId);
-        const why = fallback === undefined
-            ? undefined
-            : fallback.reason === 'unavailable'
-                ? 'the approval service is unavailable'
-                : fallback.reason === 'native-timeout'
-                    ? `no answer in the conversation within ${String(Math.round((fallback.waitedMs ?? 0) / 1000))}s`
-                    : undefined;
-        if (fallback === undefined || why === undefined) {
-            return `\n> 🔐 [Permission Required: ${title}] - please approve in Settings\n`;
-        }
-        return fallback.timeoutMs > 0
-            ? `\n> 🔐 [Permission Required: ${title}] - ${why}; approve in Settings within ${String(Math.round(fallback.timeoutMs / 1000))}s or this request is cancelled\n`
-            : `\n> 🔐 [Permission Required: ${title}] - ${why}; please approve in Settings\n`;
+        // `toolName` is host-derived (`permissionToolName`) so agents that omit
+        // `title` and declare it in `_meta` still name the operation here.
+        const title = event.toolName;
+        // The line must point at the place the answer entry actually is: a
+        // chat-bound ask renders its card in the conversation; an `/acp`-RPC ask
+        // has no conversation, so its card lives on the settings page.
+        const lead = event.dshSessionId !== undefined
+            ? 'please answer the permission card above the composer'
+            : 'please approve in Settings';
+        // The last clause says what happens if nobody answers, and it follows the
+        // MODE: refused, answered automatically, or (in `wait`) nothing at all.
+        if (event.timeoutMode === 'wait' || event.deadlineAt === undefined) {
+            return `\n> 🔐 [Permission Required: ${title}] - ${lead}\n`;
+        }
+        const remainingMs = Math.max(0, event.deadlineAt - Date.now());
+        // Floor (+1 ms for the Date.now tick), min 1: rounding up would promise time already spent.
+        const remainingS = Math.max(1, Math.floor((remainingMs + 1) / 1000));
+        const otherwise = event.timeoutMode === 'auto'
+            ? 'this request is answered automatically'
+            : 'this request is cancelled';
+        return `\n> 🔐 [Permission Required: ${title}] - ${lead} within ${String(remainingS)}s or ${otherwise}\n`;
+    }
+    /**
+     * The line for an ask the plugin settled itself when its deadline fired.
+     *
+     * The composer card is disappearing, so the conversation has to say what
+     * happened to the question — otherwise the user is left with a vanished
+     * card and no explanation. The wording follows the outcome: refused, or
+     * answered with the option the agent's own kinds implied.
+     */
+    expiredLine(event) {
+        const title = permissionToolName(event.toolCall);
+        const waited = event.timeoutMs > 0
+            ? `no answer within ${String(Math.round(event.timeoutMs / 1000))}s`
+            : 'not waited for';
+        if (event.outcome.outcome === 'selected') {
+            const picked = event.optionName === undefined ? event.outcome.optionId : event.optionName;
+            return `\n> 🔐 [Permission Required: ${title}] - ${waited}; answered "${picked}" automatically, continuing\n`;
+        }
+        return `\n> 🔐 [Permission Required: ${title}] - ${waited}; refused\n`;
     }
 }
 /** Chunk text shared by the controller's fold (string / object / array forms). */
@@ -2539,17 +2552,23 @@ export class BridgeManager {
     /** The agent tag's halo preference (persisted; see `persistAgents`). */
     tagHaloSetting = { ...DEFAULT_TAG_HALO };
     /**
-     * What `cordis.patch.yml` asked for, by key — ONLY the keys it actually
-     * names. This is the deployment baseline, kept apart from
+     * What `cordis.patch.yml` asked for — ONLY if it actually named the key.
+     * This is the deployment baseline, kept apart from
      * {@link deadlineOverride} so the settings card can tell the user which of
-     * the two is winning. Empty when the file says nothing about either window,
-     * in which case {@link baselineDeadlines} (the built-in default) applies.
+     * the two is winning. Empty when the file says nothing about the window, in
+     * which case {@link baselineDeadline} (the built-in default) applies.
      */
     configuredDeadlines = {};
     /**
-     * The value each deadline had before any override — the tuning this manager
-     * was constructed with, which already carries the validated config file (the
-     * host entry passes `validateConfig`'s output) or the built-in default.
+     * The mode the config file named, if it named one. Kept apart from the
+     * override for the same reason the window is: the card has to be able
+     * to say "the file asks for `abort`, the value set here wins".
+     */
+    configuredMode;
+    /**
+     * The window before any override — the tuning this manager was constructed
+     * with, which already carries the validated config file (the host entry
+     * passes `validateConfig`'s output) or the built-in default.
      *
      * Held separately from {@link configuredDeadlines} because the two answer
      * different questions: this one is what RUNS when nothing is overridden, that
@@ -2557,17 +2576,23 @@ export class BridgeManager {
      * and a bare default does not deserve). A manager built without tuning at all
      * — a direct consumer, a test — gets `DEFAULT_TUNING` here and stays correct.
      */
-    baselineDeadlines;
+    baselineDeadline;
+    /**
+     * The mode before any override — the tuning this manager was constructed
+     * with, which already carries the validated config file (the host entry
+     * passes `validateConfig`'s output) or the built-in default.
+     */
+    baselineMode;
     /**
      * The settings page's own write, persisted with the agent registry. Merged
-     * OVER {@link baselineDeadlines}: once a user picks a window in the UI, that
+     * OVER {@link baselineDeadline}: once a user picks a window in the UI, that
      * pick is what runs, and the config file becomes the value the reset button
      * returns to. Without this split a hand-edited `cordis.patch.yml` and a UI
      * write would fight with no way to tell which one is live.
      */
     deadlineOverride = {};
     /**
-     * Tuning in force, defaults applied. The two approval deadlines are rewritten
+     * Tuning in force, defaults applied. The approval deadline is rewritten
      * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
      * rather than the constructor's parameter: every bridge built afterwards
      * inherits the rewrite instead of the boot-time value.
@@ -2624,13 +2649,11 @@ export class BridgeManager {
         // `applyDeadlineTuning`), and every bridge built afterwards must inherit
         // the rewrite instead of the boot-time value.
         this.tuning = { ...DEFAULT_TUNING, ...tuning };
-        // The pre-override deadline values, snapshotted before anything can rewrite
-        // them. Everything else in `tuning` is fixed for the manager's lifetime, so
-        // only this pair needs a snapshot.
-        this.baselineDeadlines = {
-            nativeApprovalTimeoutMs: this.tuning.nativeApprovalTimeoutMs,
-            permissionFallbackTimeoutMs: this.tuning.permissionFallbackTimeoutMs,
-        };
+        // The pre-override deadline value, snapshotted before anything can rewrite
+        // it. Everything else in `tuning` is fixed for the manager's lifetime, so
+        // only this needs a snapshot.
+        this.baselineDeadline = this.tuning.permissionTimeoutMs;
+        this.baselineMode = this.tuning.permissionTimeoutMode;
         for (const def of defs) {
             this.defsMap.set(def.id, def);
         }
@@ -2651,27 +2674,13 @@ export class BridgeManager {
         routeBindingRegistry().defaultModel = this.defaultAgent();
     }
     makeBridge(def, onConnectionLost, onCatalog, onCommands) {
-        return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.approvalRequester, () => this.sessionWorkspaceResolver);
-    }
-    /**
-     * Route ACP permission asks through the host approval service (answered in
-     * the chat composer). Absent → every ask stays on the settings-panel ledger.
-     * Setting it also flips {@link approvalRouting}, which the browser reads to
-     * stop rendering the settings-panel permission card.
-     */
-    setApprovalRequester(requester) {
-        this.approvalRequester = requester;
-    }
-    /** True when permission asks go to native approval instead of the settings panel. */
-    approvalRouting() {
-        return this.approvalRequester !== undefined;
+        return new AgentBridge(def, this.hub, this.transcriptMax, onConnectionLost, onCatalog, onCommands, this.tuning, () => this.sessionWorkspaceResolver);
     }
     /**
-     * Every outstanding ledger ask, across all agents, with the view the browser
-     * was shown it — the source of the reconnect replay (see
-     * `permissionReplayFrames`). Asks on the native route are deliberately
-     * absent: they broadcast nothing and their answer entry is the composer
-     * takeover the client already holds.
+     * Every outstanding ask, across all agents, with the view the browser was
+     * shown it — the source of the reconnect replay (see
+     * `permissionReplayFrames`). Every ACP ask is a ledger entry, so this is the
+     * whole live set.
      */
     pendingPermissionViews() {
         const views = [];
@@ -3469,7 +3478,31 @@ export class BridgeManager {
                 // validator accepts must be the value that runs (a UI write that did
                 // not survive a restart would read as a broken setting).
                 try {
-                    this.deadlineOverride = validateApprovalDeadlines(parsed.approvalDeadlines ?? {});
+                    const raw = parsed.approvalDeadlines ?? {};
+                    // The OLD card wrote the two legacy windows, and its 「关」 preset
+                    // wrote a zero — which then meant "this window never fires". The only
+                    // way to say that now is the `wait` MODE (a zero means 不等待 today),
+                    // so a legacy zero carries over as the mode instead of silently
+                    // turning "wait forever" into "answer immediately".
+                    const legacy = raw;
+                    const legacyWindow = legacy.nativeApprovalTimeoutMs ?? legacy.permissionFallbackTimeoutMs;
+                    const legacyNever = legacyWindow === 0;
+                    const window = legacyNever
+                        ? undefined
+                        : validateApprovalDeadlines(raw).permissionTimeoutMs;
+                    const mode = legacyNever
+                        ? 'wait'
+                        : (raw.mode === undefined
+                            ? undefined
+                            : validatePermissionTimeoutMode(raw.mode, 'bad_payload'));
+                    // A stored window must be legal for the mode it runs under: 不等待
+                    // (0) belongs to `auto`; under `abort` it would refuse every ask on
+                    // arrival, so it floors to the shortest real wait.
+                    const effectiveMode = mode ?? this.baselineMode;
+                    this.deadlineOverride = {
+                        ...(window === undefined ? {} : { permissionTimeoutMs: normalizeApprovalWindow(effectiveMode, window) }),
+                        ...(mode === undefined ? {} : { mode }),
+                    };
                 }
                 catch {
                     this.deadlineOverride = {};
@@ -4527,7 +4560,7 @@ export class BridgeManager {
         this.persistAgents();
     }
     /**
-     * Declare the deployment baseline for the two approval deadlines — the values
+     * Declare the deployment baseline for the approval deadline — the values
      * `cordis.patch.yml` names, passed RAW (only the keys it actually contains).
      *
      * Kept separate from the validated tuning because "the file says 600000" and
@@ -4537,36 +4570,46 @@ export class BridgeManager {
      * also moves the baseline, so a manager built without tuning (a direct
      * consumer, a test) still runs what the deployment asked for.
      */
-    setConfiguredApprovalDeadlines(values) {
-        this.configuredDeadlines = { ...values };
-        if (values.nativeApprovalTimeoutMs !== undefined)
-            this.baselineDeadlines.nativeApprovalTimeoutMs = values.nativeApprovalTimeoutMs;
-        if (values.permissionFallbackTimeoutMs !== undefined)
-            this.baselineDeadlines.permissionFallbackTimeoutMs = values.permissionFallbackTimeoutMs;
+    setConfiguredApprovalDeadlines(values, mode) {
+        // The baseline must be legal for the mode it runs under, or the card would
+        // advertise a number the deployment cannot actually run (不等待 under
+        // `abort`) and the reset button would restore it.
+        const effectiveMode = mode ?? this.configuredMode ?? this.baselineMode;
+        const raw = values.permissionTimeoutMs;
+        const window = raw === undefined ? undefined : normalizeApprovalWindow(effectiveMode, raw);
+        this.configuredDeadlines = window === undefined ? {} : { permissionTimeoutMs: window };
+        if (window !== undefined)
+            this.baselineDeadline = window;
+        if (mode !== undefined) {
+            this.configuredMode = mode;
+            this.baselineMode = mode;
+        }
         this.applyDeadlineTuning();
     }
     /**
-     * The approval deadlines in force, plus the two facts that explain a value the
-     * user did not pick: the config-file baseline an override is outranking, and a
-     * `permissionTimeoutMs` that overrides BOTH windows when non-zero. Both are
-     * reported only when they are actually in play, so the card can stay silent
-     * about a plain default.
+     * The approval deadline in force, plus the facts that explain a value the
+     * user did not pick: the config-file baseline an override is outranking. The
+     * mode rides along with its own baseline, for the same reason: the card has
+     * to be able to say "the file asks for `abort`, the value set here wins".
+     *
+     * Everything is reported only when it is actually in play, so the card can
+     * stay silent about a plain default.
      */
     approvalDeadlines() {
         const deadlines = {
-            nativeApprovalTimeoutMs: this.tuning.nativeApprovalTimeoutMs,
-            permissionFallbackTimeoutMs: this.tuning.permissionFallbackTimeoutMs,
+            permissionTimeoutMs: this.tuning.permissionTimeoutMs,
+            mode: this.tuning.permissionTimeoutMode,
         };
         if (Object.keys(this.configuredDeadlines).length > 0)
             deadlines.configured = { ...this.configuredDeadlines };
-        if (this.tuning.permissionTimeoutMs > 0)
-            deadlines.permissionTimeoutMs = this.tuning.permissionTimeoutMs;
+        if (this.configuredMode !== undefined)
+            deadlines.configuredMode = this.configuredMode;
         return deadlines;
     }
     /**
-     * Write one or both approval deadlines (omitted keys keep their value), or
-     * drop the persisted override with `reset` so the config-file baseline — or
-     * the built-in default — applies again.
+     * Write the approval deadline, or the mode (omitted keys keep their value),
+     * or drop the persisted override with `reset` so the config-file baseline —
+     * or the built-in default — applies again.
      *
      * HOT: the rewrite reaches every live bridge, so a user changing the window
      * never has to kill a running session to see it take effect (the one thing an
@@ -4577,25 +4620,35 @@ export class BridgeManager {
     async setApprovalDeadlines(patch, reset = false) {
         // Merged BEFORE validating, so the whole resulting override passes the same
         // gate the config file does (an override written by an older build is
-        // re-gated here rather than trusted). `validateApprovalDeadlines` also drops
-        // unknown keys, which is what keeps a stale payload from poisoning state.
+        // re-gated here rather than trusted). The validators also drop unknown
+        // keys, which is what keeps a stale payload from poisoning state.
         const merged = reset ? {} : { ...this.deadlineOverride, ...patch };
-        this.deadlineOverride = validateApprovalDeadlines(merged);
+        const window = validateApprovalDeadlines(merged).permissionTimeoutMs;
+        const mode = merged.mode === undefined
+            ? undefined
+            : validatePermissionTimeoutMode(merged.mode, 'bad_payload');
+        // The stored override must be legal for the mode it runs under, not just
+        // legal on its own: 不等待 (0) belongs to `auto`, and a mode switch can
+        // leave it behind. Flooring it HERE (not only in the running value) keeps
+        // the card's number and the running number the same number.
+        const effectiveMode = mode ?? this.baselineMode;
+        this.deadlineOverride = {
+            ...(window === undefined ? {} : { permissionTimeoutMs: normalizeApprovalWindow(effectiveMode, window) }),
+            ...(mode === undefined ? {} : { mode }),
+        };
         this.applyDeadlineTuning();
         this.persistAgents();
     }
     /**
-     * Recompute the two deadlines from override → deployment baseline, and push
-     * the result to every live bridge.
+     * Recompute the deadline and the mode from override → deployment baseline,
+     * and push the result to every live bridge.
      */
     applyDeadlineTuning() {
-        const nativeApprovalTimeoutMs = this.deadlineOverride.nativeApprovalTimeoutMs
-            ?? this.baselineDeadlines.nativeApprovalTimeoutMs;
-        const permissionFallbackTimeoutMs = this.deadlineOverride.permissionFallbackTimeoutMs
-            ?? this.baselineDeadlines.permissionFallbackTimeoutMs;
-        this.tuning.nativeApprovalTimeoutMs = nativeApprovalTimeoutMs;
-        this.tuning.permissionFallbackTimeoutMs = permissionFallbackTimeoutMs;
-        const patch = { nativeApprovalTimeoutMs, permissionFallbackTimeoutMs };
+        const permissionTimeoutMode = this.deadlineOverride.mode ?? this.baselineMode;
+        const permissionTimeoutMs = normalizeApprovalWindow(permissionTimeoutMode, this.deadlineOverride.permissionTimeoutMs ?? this.baselineDeadline);
+        this.tuning.permissionTimeoutMs = permissionTimeoutMs;
+        this.tuning.permissionTimeoutMode = permissionTimeoutMode;
+        const patch = { permissionTimeoutMs, mode: permissionTimeoutMode };
         for (const bridge of this.bridges.values())
             bridge.applyApprovalDeadlines(patch);
     }
@@ -4615,11 +4668,6 @@ export class BridgeManager {
                 this.dshSessionMap.delete(key);
         }
     }
-    /**
-     * Latest native-approval requester. Held as a field (read through a thunk by
-     * each bridge) so a requester wired after bridges were built still applies.
-     */
-    approvalRequester;
     sessionWorkspaceResolver;
     acpModeResolver;
     /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
@@ -4754,7 +4802,7 @@ export class BridgeManager {
         if (existing !== undefined && existing.released) {
             const resumed = await this.bridge(agentId).resumeSession(existing);
             // Rebind explicitly: a resume keeps the record's identity, but the chat
-            // session id is what native approval routing keys off.
+            // session id is what the conversation's permission card addresses.
             resumed.dshSessionId = dshSessionId;
             // A resume without an explicit pick must keep serving the agent the
             // conversation was ON (its own model string when one was recorded). The
@@ -4792,7 +4840,7 @@ export class BridgeManager {
         // `ensureReady` for why `session/new`'s cwd alone is not enough.
         workspaceRoot);
         // Absent for `/acp`-RPC sessions and for adapter calls without a chat
-        // session; those deliberately keep the ledger path (see askNativeApproval).
+        // session; their permission cards are addressed by the ACP session only.
         session.dshSessionId = dshSessionId;
         this.dshSessionMap.set(key, session);
         // Turn the displayed defaults into this conversation's pick, so the first
@@ -5072,7 +5120,7 @@ export class BridgeManager {
         // loop then executes the card and proposes the continuation step, which
         // resumes the SAME prompt through the branch above.
         const endTurn = bridge.beginTurn(session);
-        const controller = new TurnStreamController(this, this.hub, bridge, session, turnId, endTurn, victim => this.rollbackFirstTurn(victim));
+        const controller = new TurnStreamController(this, this.hub, session, turnId, endTurn, victim => this.rollbackFirstTurn(victim));
         if (session.dshSessionId !== undefined)
             this.rememberTurnStream(session.dshSessionId, controller);
         const segment = controller.startSegment();