aegis-desktop 0.3.0 → 0.4.0

package/lib/local/engine.js

@@ -11,9 +11,20 @@
  * aegiscodex-dev's src/backend.js runProvider): every turn carries a real
  * system prompt (prompt.js) and the builtin tool schemas (tools.js), and when
  * a provider answers with tool calls the loop executes them in-process and
- * feeds the results back until the model answers with text or the round cap is
- * hit. The window stays contextIsolated + sandboxed: this module runs in the
- * MAIN process, so the executor never has to be exposed to the renderer.
+ * feeds the results back for as many rounds as the model keeps calling tools
+ * — there is no round cap; a turn ends when the model answers with text, or
+ * the user cancels it (cancel()/AbortController).
+ *
+ * Because a provider can signal "finished" with no answer attached, the two
+ * exit paths are guarded against the empty turn (see the loop's comment):
+ * a `finish_reason: 'length'` completion with no text is retried once with a
+ * doubled budget, and a turn that ends with neither text nor a tool call is
+ * re-dispatched once with `tools: []` plus a nudge so the model has to write
+ * up what it already gathered. A turn still empty after both throws instead
+ * of returning a blank completion for the renderer to paint "(empty
+ * response)" over. The window stays
+ * contextIsolated + sandboxed: this module runs in the MAIN process, so the
+ * executor never has to be exposed to the renderer.
  *
  * Two turn-scoped resources ride along with the loop, mirroring
  * aegiscodex-dev's runProvider exactly:
@@ -40,9 +51,6 @@ const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
 /** Classes whose transport is a user-supplied endpoint + credential. */
 const CUSTOM_CLASSES = Object.freeze(['openai-compat', 'anthropic']);
 
-/** Hard cap on tool rounds per turn — mirrors the CLI's bounded loop. */
-const MAX_TOOL_ROUNDS = 12;
-
 /**
  * Depth at which the task tool stops being offered. The main chat (depth 0)
  * and subagents down to depth MAX_SUBAGENT_DEPTH - 1 can all delegate, so
@@ -59,6 +67,53 @@ const CLASSES = [
   { class: 'anthropic', label: 'Anthropic-compatible', kind: 'custom' },
 ];
 
+/**
+ * Mirrors aegiscodex-dev's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
+ * EFFORT_TOKEN_BUDGET verbatim. DeepSeek's reasoning models (deepseek-flash,
+ * deepseek-v4-pro, the deprecated deepseek-reasoner, and the legacy
+ * v4-flash/v4.1-flash aliases some configs still carry) spend part of
+ * max_tokens on hidden chain-of-thought before ever emitting visible
+ * content — DeepSeek counts reasoning tokens against the same budget as
+ * content. At the renderer's 4k default (index.html's max-tokens select),
+ * any non-trivial question can burn the whole budget reasoning and finish
+ * with empty content: no error, no tool calls, just a turn that "completes"
+ * with nothing to show for it (the empty-response bug). A user pointing the
+ * Custom OpenAI-compatible class straight at DeepSeek's API hits exactly
+ * this, so the request floors to the same effort budget aegiscodex-dev uses
+ * for its own direct DeepSeek calls instead of shipping whatever the
+ * dropdown happens to have selected.
+ */
+const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro|reasoner)$/;
+const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
+
+/**
+ * Idle-stream budget for a pooled brain call ("work autonomously"). The
+ * generic watchdog in vendor/aegis.js kills a stream that goes 60s without a
+ * byte — right default for one provider call answering, wrong for a worker
+ * fan-out: pool_brain yields a header chunk, then stays silent until the
+ * FIRST worker pass *returns*, and each worker is a full reasoning-model call
+ * at roughly 1/(workers+1) of the effort budget. At high effort, 3 workers,
+ * that is a multi-thousand-token reasoning pass per worker — easily past a
+ * minute. Timing out there aborts a perfectly healthy autonomous turn
+ * mid-flight, after the server has already run and billed every worker.
+ */
+const AUTONOMOUS_IDLE_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * Only ever raises a too-low budget for a DeepSeek reasoning model — never
+ * lowers whatever the caller (renderer dropdown, or "adaptive" ceiling)
+ * already asked for. Everything else (non-DeepSeek models, non-reasoning
+ * DeepSeek ids like deepseek-chat) passes through untouched. Effort defaults
+ * to 'high' since custom endpoints have no effort selector of their own
+ * (that UI is aegis-class/autonomous-only) — matching aegiscodex-dev's own
+ * default effort.
+ */
+function deepseekReasoningFloor(model, maxTokens, effort) {
+  if (!DEEPSEEK_REASONING_MODEL_RE.test(String(model || ''))) return maxTokens;
+  const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
+  return Math.max(Number(maxTokens) || 0, EFFORT_TOKEN_BUDGET[eff]);
+}
+
 /** Relay model entries arrive as ids or objects; keep only real model ids. */
 function normalizeCatalog(models) {
   if (!Array.isArray(models)) return [];
@@ -131,11 +186,229 @@ function assistantText(res) {
   return (msg && typeof msg.content === 'string' && msg.content) || '';
 }
 
-function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBuilder, env }) {
+/**
+ * The provider's stop reason for a completion ('' when it sent none). The two
+ * wire formats report it in different places and both have to be read: the
+ * OpenAI shape carries `choices[0].finish_reason` (this is what providers.js
+ * and vendor/aegis.js emit), while providers.js's Anthropic parser puts
+ * `stop_reason` on the result and never sets a finish_reason on the choice.
+ */
+function finishReasonOf(res) {
+  const choice = res && res.choices && res.choices[0];
+  return (choice && choice.finish_reason) || (res && res.stop_reason) || '';
+}
+
+/**
+ * True when the provider cut the answer off at the token budget instead of
+ * the model choosing to stop. This is the diagnosis for the most common
+ * flavour of the empty turn: DeepSeek (and other reasoning models that bill
+ * hidden chain-of-thought against max_tokens) can spend the entire budget
+ * before emitting a single visible token, and the completion still arrives
+ * as a clean `finish_reason: 'length'` — no error, empty content. A tool
+ * call whose JSON was truncated mid-argument lands here too, where
+ * parseArgs() would otherwise silently yield `{}` and run the tool with no
+ * arguments, which is worse than retrying.
+ */
+function isTruncated(res) {
+  const reason = finishReasonOf(res);
+  // 'length' is OpenAI's wording, 'max_tokens' is Anthropic's — same event.
+  return reason === 'length' || reason === 'max_tokens';
+}
+
+/**
+ * Double a budget for the one-shot truncation retry. A budget the caller set
+ * on purpose (the flow lane's deliberate 1024-token cap, say) is merely
+ * doubled — the floor only applies when nothing was set at all, so a retry
+ * can never silently override a small cap by an order of magnitude.
+ */
+function doubledBudget(maxTokens) {
+  const n = Number(maxTokens) || 0;
+  return n > 0 ? n * 2 : 8192;
+}
+
+/**
+ * The follow-up shown to a model that ended its turn with neither text nor a
+ * tool call. Sent as a plain user message (never as a tool result — there is
+ * no pending tool call to answer) so every provider accepts it verbatim.
+ */
+const EMPTY_TURN_NUDGE =
+  'Your previous reply came back empty — it contained no answer and no tool call. ' +
+  'Write your answer now, using only the information already gathered above. ' +
+  'No tools are available in this reply, so do not call any: respond in plain ' +
+  'prose or markdown.';
+
+/**
+ * Last resort for a turn that is still empty after the synthesis pass.
+ *
+ * Throws rather than returning the blank completion. Returning it is what
+ * produces the renderer's undiagnosable "(empty response)" bubble, and
+ * synthesising fake assistant text instead would be worse: renderer/app.js
+ * persists whatever comes back as the assistant's own message and syncs it
+ * to the aegis account, so the notice would re-enter the model's context on
+ * the next turn as something it had said. Failing loudly leaves the turn's
+ * real tool log on screen, keeps the transcript honest, and names the cause
+ * (renderer prints `Error: <message>`).
+ */
+function emptyTurnError({ cls, model, maxTokens, finishReason }) {
+  const err = new Error(
+    `The model returned no answer after ${cls}/${model} was asked to summarise its results ` +
+      `(stop reason: ${finishReason || 'none'}, max_tokens: ${maxTokens}). The token budget ` +
+      'was most likely consumed before any visible text — raise the max-tokens setting, ' +
+      'or lower effort.'
+  );
+  err.status = 502;
+  return err;
+}
+
+function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBuilder, env, getConfirmMode }) {
   const controllers = new Map(); // sessionId -> AbortController
   const T = tools || toolsModule;
   const buildSystemPrompt = (promptBuilder && promptBuilder.buildSystemPrompt) || promptModule.buildSystemPrompt;
 
+  /** "Confirm before running tools" (Settings toggle, persisted by
+   *  lib/settings.js. Because gatedExecuteTool is called for EVERY tool round
+   *  it is read per call, not captured once at construction: flipping the
+   *  switch takes effect on the next tool call, with no restart.
+   *  An explicit `getConfirmMode` factory arg wins (used by tests); then the
+   *  settings store's own accessor; then the safe default — ON, i.e. the gate
+   *  stays up, so a store that predates the toggle can never silently
+   *  disable it. */
+  const confirmModeEnabled = () => {
+    if (typeof getConfirmMode === 'function') return getConfirmMode() !== false;
+    if (settings && typeof settings.getConfirmMode === 'function') {
+      const value = settings.getConfirmMode();
+      return value === undefined ? true : Boolean(value);
+    }
+    return true;
+  };
+
+  // ── Tool-call approval gate (renderer confirms exec/writeFile/editFile
+  // before they run) ─────────────────────────────────────────────────────
+  //
+  // `sessionAllowlists` is keyed by the CONVERSATION's root session id (the
+  // one the renderer's `send()` mints once per thread and reuses across
+  // turns — see rootSessionId below), never by the per-call sessionId a
+  // subagent gets, so "allow for this session" reads the way the user sees
+  // it: one decision per open conversation, not per nested tool round.
+  // In-memory only, on purpose — never persisted, so a restart (or
+  // newChat()'s clearSessionApprovals) always starts from a clean gate.
+  const sessionAllowlists = new Map(); // rootSessionId -> Set<toolName>
+  const pendingApprovals = new Map(); // approvalId -> { resolve }
+
+  function sessionAllows(rootId, name) {
+    const set = sessionAllowlists.get(rootId);
+    return Boolean(set && set.has(name));
+  }
+
+  function allowForSession(rootId, name) {
+    if (!sessionAllowlists.has(rootId)) sessionAllowlists.set(rootId, new Set());
+    sessionAllowlists.get(rootId).add(name);
+  }
+
+  /** newChat() in the renderer calls this so a fresh conversation never
+   *  inherits a prior thread's blanket allows. */
+  function clearSessionApprovals(rootSessionId) {
+    sessionAllowlists.delete(rootSessionId);
+    return { ok: true };
+  }
+
+  /** The renderer's approval card resolves the pending requestApproval()
+   *  promise below. An unknown/already-answered id is a no-op — the card
+   *  can only be clicked once (it disables itself), but a duplicate or
+   *  late message must never throw. */
+  function respondApproval(approvalId, decision) {
+    const pending = pendingApprovals.get(approvalId);
+    if (!pending) return { ok: false };
+    pendingApprovals.delete(approvalId);
+    pending.resolve(decision === 'session' || decision === 'once' ? decision : 'deny');
+    return { ok: true };
+  }
+
+  /**
+   * Ask the renderer to approve one mutating tool call. Resolves 'once',
+   * 'session' or 'deny'. Sent over `rootOnDelta` (see chat()) as an
+   * `{ approval }` chunk so it rides the exact same streaming channel as
+   * tool-activity chunks — no new IPC surface needed on the push side, only
+   * on the reply side (respondApproval). Fails safe: no listener able to
+   * ever answer (no onDelta, or the turn was aborted) resolves 'deny'
+   * instead of hanging the tool round forever.
+   */
+  function requestApproval(rootSessionId, rootOnDelta, signal, info) {
+    return new Promise((resolve) => {
+      if (signal && signal.aborted) {
+        resolve('deny');
+        return;
+      }
+      const id = randomUUID();
+      let settled = false;
+      const onAbort = () => finish('deny');
+      const finish = (decision) => {
+        if (settled) return;
+        settled = true;
+        pendingApprovals.delete(id);
+        if (signal) signal.removeEventListener('abort', onAbort);
+        resolve(decision);
+      };
+      if (signal) signal.addEventListener('abort', onAbort, { once: true });
+      pendingApprovals.set(id, { resolve: finish });
+      if (typeof rootOnDelta !== 'function') {
+        finish('deny');
+        return;
+      }
+      rootOnDelta({
+        delta: '',
+        approval: {
+          id,
+          sessionId: rootSessionId,
+          tool: info.tool,
+          args: info.args,
+          diff: info.diff || null,
+        },
+      });
+    });
+  }
+
+  /**
+   * The gate itself: read-only tools and already-session-allowed mutating
+   * tools run exactly like executeTool always did. A first-time mutating
+   * call previews writeFile/editFile (a preview failure — e.g. old_string
+   * not found — is returned as the ordinary tool error, no approval prompt
+   * needed for a call that couldn't succeed anyway), asks the renderer, and
+   * on approval either applies with a fresh hash check (writeFile/editFile)
+   * or runs normally (exec — nothing to hash-check).
+   *
+   * Confirm mode off (Settings → "Confirm before running tools") short-circuits
+   * ALL of that: no preview, no approval card, no requestApproval() — the call
+   * runs straight through exactly like a session-allowed one, so "don't ask"
+   * is one switch rather than a per-tool blanket allow in every conversation.
+   */
+  async function gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal }) {
+    const { name, args } = call;
+    if (!T.MUTATING_TOOLS.has(name)) return T.executeTool(name, args, toolCtx);
+    if (!confirmModeEnabled()) return T.executeTool(name, args, toolCtx);
+    if (sessionAllows(rootSessionId, name)) return T.executeTool(name, args, toolCtx);
+
+    let preview = null;
+    if (name === 'writeFile' || name === 'editFile') {
+      preview = T.previewMutation(name, args);
+      if (!preview.ok) return { ok: false, error: preview.error };
+    }
+
+    const decision = await requestApproval(rootSessionId, rootOnDelta, signal, {
+      tool: name,
+      args,
+      diff: preview && preview.diff,
+    });
+
+    if (decision === 'deny') {
+      return { ok: false, error: `${name} was not executed — the user denied the request.` };
+    }
+    if (decision === 'session') allowForSession(rootSessionId, name);
+
+    if (preview) return T.applyChecked(name, args, preview);
+    return T.executeTool(name, args, toolCtx);
+  }
+
   /**
    * Custom endpoints are only usable when they are actually configured:
    * a base URL is mandatory for both, and Anthropic additionally needs its own
@@ -225,6 +498,12 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         maxTokens: opts.maxTokens,
         stream: true,
         onStream: opts.onDelta,
+        // Extended-reasoning trace (the fan-out's worker findings). Its own
+        // channel so it never counts as answer text — see vendor/aegis.js.
+        onReasoning: opts.onReasoning,
+        // A brain fan-out is silent between passes; give it room (see
+        // AUTONOMOUS_IDLE_TIMEOUT_MS). Undefined elsewhere -> 60s default.
+        idleTimeoutMs: opts.idleTimeoutMs,
         signal: opts.signal,
         // aegis_memory: automatic, no button — the server both reads prior
         // synced memory into context AND writes this turn back to it, the
@@ -281,7 +560,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   async function chat(payload, onDelta) {
     const cls = payload && payload.class;
     const model = payload && payload.model;
-    const maxTokens = payload && payload.maxTokens;
+    const maxTokens = deepseekReasoningFloor(model, payload && payload.maxTokens, payload && payload.effort);
     // "Work autonomously" — routes this call through aegis1's pool_brain
     // worker fan-out (services/pool_brain.py: N reasoning workers + a
     // synthesis pass) instead of a single provider call. UI-gated to the
@@ -292,6 +571,27 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     // subagent spawned by depth N. Never set by an IPC caller — only by
     // runSubagent's own recursive chat() call below.
     const depth = Number.isInteger(payload && payload.depth) ? payload.depth : 0;
+    // The approval gate's identity for this whole conversation, regardless of
+    // depth: a real user turn defines it (defaults to its own sessionId); a
+    // subagent's nested chat() call always receives it explicitly from
+    // runSubagent below, so "allow for this session" means the same thing
+    // whether the call came from the top-level turn or three subagents deep.
+    const rootSessionId = (payload && payload.rootSessionId) || sessionId;
+    // Likewise, approval requests must always reach the ORIGINAL caller's
+    // stream — a subagent's own chat() call is invoked with a no-op onDelta
+    // (its tool activity/text is not streamed to the renderer), so without
+    // this a nested approval request would call that no-op and hang forever
+    // waiting for a response nobody can ever send.
+    const rootOnDelta = (payload && payload.rootOnDelta) || onDelta;
+
+    // A pooled brain call streams each worker's finding as extended reasoning
+    // before the synthesis pass writes the visible answer. Forward it on its
+    // own channel so the renderer can show the fan-out working instead of an
+    // apparently idle bubble for the whole worker phase. Uses `onDelta` (not
+    // rootOnDelta) on purpose: a subagent's reasoning should be suppressed
+    // exactly as its text already is.
+    const onReasoning =
+      typeof onDelta === 'function' ? (text) => text && onDelta({ reasoning: text }) : undefined;
 
     const controller = new AbortController();
     controllers.set(sessionId, controller);
@@ -335,10 +635,42 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         cls, model, mode: payload && payload.mode, maxTokens, autonomous, sessionId, signal, onDelta, cfg, apiKey, toolChoice,
         effort: payload && payload.effort,
         workers: payload && payload.workers,
+        onReasoning,
+        idleTimeoutMs: autonomous ? AUTONOMOUS_IDLE_TIMEOUT_MS : undefined,
+      };
+
+      // No round cap: a model that keeps calling tools keeps going for as
+      // long as it wants to. The old fixed cap (12 rounds) cut off genuinely
+      // long research/exploration turns mid-investigation. A turn ends when
+      // the model answers with text, or the user cancels.
+      //
+      // Both of those exit paths need a guard, because a provider's
+      // "I'm finished" signal can arrive with no answer attached — which is
+      // exactly how the renderer came to paint "(empty response)" over a turn
+      // that had actually done real work:
+      //   - truncated (finish_reason 'length'): the budget was consumed
+      //     before any visible text (DeepSeek's hidden reasoning bills
+      //     against max_tokens), or mid tool-call JSON. One doubled retry.
+      //   - empty (no tool call AND no text): re-dispatch once with no tools
+      //     and a nudge, so the model has to write up what it already found.
+      // Each guard fires at most once per turn, so a provider that is simply
+      // broken still terminates instead of looping.
+      let truncationRetried = false;
+      let synthesisDone = false;
+
+      // Round 1's shorthand prompt was sent as `prompt`, not as a message, so
+      // any follow-up dispatch in this turn must fold it into the history
+      // first or the model would be shown a nudge with no question above it.
+      const foldPromptIntoHistory = () => {
+        if (prompt === '') return;
+        const last = history[history.length - 1];
+        if (!(last && last.role === 'user' && last.content === prompt)) {
+          history.push({ role: 'user', content: prompt });
+        }
+        prompt = '';
       };
 
-      let last = null;
-      for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
+      for (;;) {
         const opts = { ...base, system, messages: history, prompt, tools: toolSchemas };
         let res;
         try {
@@ -351,23 +683,48 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           if (!retriable) throw e;
           res = await dispatch(cls, { ...opts, tools: [] });
         }
-        last = res;
+
+        // Budget exhausted before the answer was written. Doubling it costs
+        // one request and converts a dead turn into a real one; a second
+        // 'length' result is accepted as-is so a hard-capped model can't
+        // spin here forever.
+        //
+        // Gated on empty text on purpose. Every transport builds `content`
+        // by concatenating the deltas it already forwarded to onDelta, so
+        // empty content means nothing was streamed and re-dispatching cannot
+        // double up in the renderer's live view. When text *has* arrived the
+        // turn is not empty — the answer is merely truncated — and a retry
+        // would stream it a second time onto the same bubble.
+        if (!truncationRetried && !assistantText(res) && isTruncated(res)) {
+          truncationRetried = true;
+          res = await dispatch(cls, { ...opts, maxTokens: doubledBudget(opts.maxTokens) });
+        }
 
         const calls = toolSchemas.length ? extractToolCalls(res) : [];
-        if (!calls.length) return res;
-        if (round === MAX_TOOL_ROUNDS) return res; // round cap: hand back what we have
-
-        // Continuing the loop means round 1's shorthand prompt has to become
-        // part of the history — it was sent as `prompt`, not as a message, so
-        // without this the model would see a tool result and no question.
-        if (prompt !== '') {
-          const last = history[history.length - 1];
-          if (!(last && last.role === 'user' && last.content === prompt)) {
-            history.push({ role: 'user', content: prompt });
+        if (!calls.length) {
+          if (assistantText(res) || synthesisDone || !toolsEnabled) return res;
+          // The model stopped without calling a tool and without saying
+          // anything. Force the summary out of the context it already holds
+          // instead of handing the renderer a blank completion. Skipped when
+          // the caller opted out of the agent loop (`tools: false`): there is
+          // no gathered context to rescue, so a bare completion is just that.
+          synthesisDone = true;
+          foldPromptIntoHistory();
+          history.push({ role: 'user', content: EMPTY_TURN_NUDGE });
+          res = await dispatch(cls, { ...opts, messages: history, prompt: '', tools: [] });
+          if (!assistantText(res)) {
+            throw emptyTurnError({
+              cls,
+              model,
+              maxTokens: opts.maxTokens,
+              finishReason: finishReasonOf(res),
+            });
           }
-          prompt = '';
+          return res;
         }
 
+        foldPromptIntoHistory();
+
         // Thread the assistant turn (its tool_calls) and each result back in
         // the shapes both wire formats accept (providers.js normalises them).
         history.push({
@@ -382,8 +739,10 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
 
         for (const call of calls) {
           const result = call.name === T.SUBAGENT_TOOL
-            ? await runSubagent(call.args, { cls, model, maxTokens, mode: payload && payload.mode, parentSignal: signal, depth })
-            : await T.executeTool(call.name, call.args, toolCtx);
+            ? await runSubagent(call.args, {
+                cls, model, maxTokens, mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
+              })
+            : await gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal });
           if (onDelta) onDelta({ delta: '', tool: { name: call.name, args: call.args, ok: result.ok } });
           history.push({
             role: 'tool',
@@ -393,7 +752,6 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           });
         }
       }
-      return last;
     } finally {
       if (shell) shell.dispose();
       controllers.delete(sessionId);
@@ -408,7 +766,10 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    * throws — resolves { ok, output } or { ok:false, error }, matching
    * tools.js's executor contract so the caller treats it identically.
    */
-  async function runSubagent({ description, subagent_type, prompt: subPrompt } = {}, { cls, model, maxTokens, mode, parentSignal, depth } = {}) {
+  async function runSubagent(
+    { description, subagent_type, prompt: subPrompt } = {},
+    { cls, model, maxTokens, mode, parentSignal, depth, rootSessionId, rootOnDelta } = {}
+  ) {
     const task = String(subPrompt || description || '').trim();
     if (!task) return { ok: false, error: 'task requires a prompt' };
     const label = subagent_type && subagent_type !== 'general' ? agentRoleLabel(subagent_type) : 'general';
@@ -425,8 +786,15 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     }
 
     try {
+      // rootSessionId/rootOnDelta ride along explicitly (see chat()) so the
+      // subagent's own mutating tool calls still gate through the SAME
+      // approval card the user sees for the top-level turn, instead of
+      // silently hanging behind this call's no-op onDelta below.
       const res = await chat(
-        { class: cls, model, maxTokens, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1 },
+        {
+          class: cls, model, maxTokens, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1,
+          rootSessionId, rootOnDelta,
+        },
         () => {}
       );
       const text = assistantText(res);
@@ -448,13 +816,14 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
 
   return {
     CLASSES,
-    MAX_TOOL_ROUNDS,
     listClasses,
     listModels,
     chat,
     cancel,
+    respondApproval,
+    clearSessionApprovals,
     settings,
   };
 }
 
-module.exports = { CLASSES, MAX_TOOL_ROUNDS, createLocalEngine, extractToolCalls, parseArgs };
+module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs };