@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/agent/controller.js

@@ -11,7 +11,7 @@ import { resolveModelProfileState } from '../config/model-profile-resolution.js'
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { ModelWindows } from '../config/model-windows.js';
-import { createBuiltinTools } from '../tools/index.js';
+import { createBuiltinTools, gatedToolTimeouts, } from '../tools/index.js';
 import { createFileChangeStore } from '../tools/file-change-store.js';
 import { createToolOutputStore, } from '../tools/tool-output-store.js';
 import { TeamRuntime } from '../team/runtime.js';
@@ -34,18 +34,25 @@ import { getHomeRoot } from '../config/app-paths.js';
 import { addSignalHook } from '../logging/install.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
+// ONE-SHOT FAST CALLS (tui-shortcut-drawer-and-task-summary §6.1). The TYPES come
+// from `fast/task-summary-types.ts` and only `fast/` produces them, so this module
+// never learns how a label is made - it owns the controller and the epoch, which
+// is the pair `runTaskSummaryCall` is forbidden to own (see its header).
+import { createTaskSummaryDeps, runTaskSummaryCall } from '../fast/summary-call.js';
 import { CompactionWiring, offCompactionSnapshot } from '../compaction/wiring.js';
 import { ContextMeter } from '../compaction/meter.js';
 import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
-import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
+import { ASK_GUARD_LIMITS, DENY_ALL_HUMAN_INPUT, questionFingerprint, } from '../tools/human-input.js';
 import { getLogger } from '../logging/logger.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
+import { SKILL_TRIAGE_LIMITS } from '../skills/triage.js';
 import { buildSystemPrompt } from './system-prompt.js';
+import { buildSkillTriageBlock } from './skill-triage-prompt.js';
 import { resetConversationWith, } from './conversation-reset.js';
 import { archiveClearedConversation, } from '../session/clear-archive.js';
 /**
@@ -74,9 +81,41 @@ export class AgentController {
     modelMetadataAbort = new AbortController();
     disposed = false;
     tools;
+    /**
+     * Tools the CALLER serves, replaced on every `tool_register` (I-13).
+     *
+     * A SECOND ARRAY, NOT ONE GROWN ONE. `this.tools` is read by `listTools()`,
+     * `toolNames()`, `composeSystemPrompt()` and three "fixed at construction" flags
+     * (bash_output/bash_kill, task, todo_write). Growing it would silently change
+     * what those flags mean; keeping the caller's tools beside it gives one honest
+     * rule - the REGISTRY is the union, `this.tools` stays the host's own set.
+     */
+    callerTools = [];
     skills;
     skillsEnabled;
     onSkillsChanged;
+    // -----------------------------------------------------------------------
+    // Skill triage (skill-triage-and-unbounded-ask §4.2.5) — PER-TURN state.
+    //
+    // Every field here is written in `prepareUserTurn` and cleared on `agent_end`,
+    // because a stale candidate set in the prompt is worse than no candidate set:
+    // it points the model at a skill chosen for a task it is no longer doing.
+    // -----------------------------------------------------------------------
+    /**
+     * This turn's routing result, or `null` when triage is off or nothing scored.
+     *
+     * It also carries the task it was computed for (`SkillRoutingReport.task`), so
+     * there is no separate copy of the turn's text to keep in step with it.
+     */
+    turnRouting = null;
+    /** The previous turn's routing, for `/skills route` with no argument. */
+    lastSkillRouting = null;
+    /** Did this turn call `skill(name)` successfully? The only proof of adoption. */
+    skillLoadedThisTurn = false;
+    /** Tool calls this turn, EXCLUDING `skill` / `skill_find` (see §4.2.7). */
+    toolCallsThisTurn = 0;
+    /** Skills already reported as "not loaded" — a session says it once (I-T5). */
+    skillTriageNoticed = new Set();
     /** Mutable session cwd — tools resolve relative paths against this. */
     cwd;
     /**
@@ -88,6 +127,17 @@ export class AgentController {
      * Empty on every path but `aragon exec`.
      */
     appendSystemPrompt;
+    /**
+     * The `<structured_result>` block (headless-request-scope-and-typed-result
+     * section 2.3.8), or `''`.
+     *
+     * A FIELD FOR THE SAME REASON `appendSystemPrompt` IS ONE: `composeSystemPrompt()`
+     * runs again on every rebuild, so a value spliced once at construction would vanish
+     * at the first `/cwd` change, skills rescan or mode flip - and the model would then
+     * be asked to submit a result it had never been told about. Empty on every path but
+     * `aragon exec --result-schema`.
+     */
+    structuredResultBlock;
     // -----------------------------------------------------------------------
     // Plan mode (§3.1) — THE CONTROLLER OWNS THE MODE.
     //
@@ -98,7 +148,20 @@ export class AgentController {
     // -----------------------------------------------------------------------
     effectiveMode;
     pendingMode = null;
-    askRounds = 0;
+    /**
+     * Fingerprints of the question SETS the user ANSWERED in this turn. Bounded,
+     * and the bound is storage hygiene rather than a refusal rule — see
+     * `ASK_GUARD_LIMITS`.
+     *
+     * Replaces a numeric round counter that capped `ask_user` at four calls. There
+     * is no cap now; the only thing this prevents is the same batch of questions
+     * being put to the user twice, which is noise rather than information.
+     *
+     * Cleared in `prepareUserTurn` for a NEW turn only. A steer continuation is the
+     * same turn — clearing there would disable the guard exactly when a long turn
+     * most needs it (§4.1.6).
+     */
+    askedFingerprints = new Set();
     /** Static: whether this session could ever render a question overlay. */
     planInteractive;
     // -----------------------------------------------------------------------
@@ -308,6 +371,10 @@ export class AgentController {
         this.config = config;
         this.cwd = config.cwd;
         this.appendSystemPrompt = deps.appendSystemPrompt ?? '';
+        // ABOVE `createBuiltinTools` FOR THE REASON THE PROMPT FIELD IS: the tool has to
+        // exist before the array is built, and the block has to exist before the prompt is
+        // composed - and both are read again on every rebuild.
+        this.structuredResultBlock = deps.structuredResultBlock ?? '';
         const humanInput = deps.humanInput ?? DENY_ALL_HUMAN_INPUT;
         this.planInteractive = humanInput.neverPrompts !== true;
         this.effectiveMode = config.startInPlanMode ? 'plan' : 'build';
@@ -431,6 +498,14 @@ export class AgentController {
                 // mid-dispatch and abort it at `idleTimeoutMs`. The queue pauses the
                 // CHILD's watchdog instead, which is the one that needs it (P0-4).
                 ...(confirm ? { humanQueue: new TeamHumanQueue(confirm) } : {}),
+                // SITE ONE OF TWO FOR THE CHILD GATE (headless-host-bridge 2.3.7). The
+                // second is `runtime.ts::subDeps`; declaring it here and forgetting that
+                // one type-checks and forwards nothing, and every child would then run
+                // unapproved while the caller believes it is approving.
+                ...(deps.toolGateForChild ? { toolGateFor: deps.toolGateForChild } : {}),
+                ...(deps.decisionBudgetMs !== undefined
+                    ? { decisionBudgetMs: deps.decisionBudgetMs }
+                    : {}),
                 // CHILDREN INHERIT THE POLICY (§4.2 invariant 3 / R-4 / AC-12).
                 // Without this line `--deny-tool bash` is bypassed by one `task` call
                 // and nothing anywhere reports it. Spread conditionally so a session
@@ -453,7 +528,12 @@ export class AgentController {
         this.jobsRegistered = config.jobs.enabled && config.bash.background;
         this.jobMirror =
             this.jobsRegistered && config.jobs.persistLog
-                ? new JobLogMirror({ root: () => join(getHomeRoot(), 'jobs', this.jobSessionTag) })
+                ? new JobLogMirror({
+                    root: () => join(getHomeRoot(), 'jobs', this.jobSessionTag),
+                    // NAMED, NOT DERIVED. The mirror sweeps only this directory; the session
+                    // tagging above is what keeps its own run out of the sweep's reach.
+                    jobsRoot: () => join(getHomeRoot(), 'jobs'),
+                })
                 : undefined;
         this.procs = new ProcSupervisor({
             readyTimeoutMs: () => this.config.bash.readyTimeoutMs,
@@ -547,7 +627,13 @@ export class AgentController {
             // (or 11 with skills) it is today.
             planTools: createPlanTools({
                 gate: humanInput,
-                takeAskRound: () => this.takeAskRound(),
+                // TWO CALLBACKS, AND THE SPLIT IS LOAD-BEARING (§4.1.2). One
+                // read-and-write accessor could only be called before the question
+                // (recording an answer nobody gave, which makes "a cancelled round stays
+                // askable" impossible) or after it (which cannot stop a repeat). The guard
+                // is "read before, write only after a real answer".
+                hasAnsweredQuestions: (questions) => this.hasAnswered(questions),
+                noteAnsweredQuestions: (questions) => this.noteAnswered(questions),
                 withHumanWait: (fn) => this.withHumanWait(fn),
                 onPlanApproved: () => this.setAgentMode('build', { force: true }),
             }),
@@ -599,6 +685,15 @@ export class AgentController {
                     }),
                 ]
                 : [],
+            // SPREAD, NEVER `resultTool: deps.resultTool` (the D-12 lesson, and the shape
+            // every optional dep in this bag follows). With no schema the options bag has no
+            // such key, so `createBuiltinTools` adds nothing and the tool array is the one it
+            // builds today - which is what makes I-S2 provable by object identity.
+            ...(deps.resultTool ? { resultTool: deps.resultTool } : {}),
+            // THE HOOK PAIR, SPREAD FOR THE SAME REASON AND AT THE SAME SITE (D-12): a dep that
+            // is declared but not forwarded is dropped in silence, and the only symptom is that
+            // the caller's hooks never fire.
+            ...(deps.hookRunner ? { hookRunner: deps.hookRunner } : {}),
             // The PULL port. Absent when jobs are off, which leaves every tool object
             // untouched and provable by identity.
             ...(this.jobsRegistered
@@ -663,6 +758,21 @@ export class AgentController {
             // today — which is what makes "the TUI and `-p` are unchanged" provable by
             // identity rather than by inspection.
             ...(deps.permission ? { permission: deps.permission } : {}),
+            // THE CALLER'S APPROVAL GATE, spread the same way and for the same reason
+            // (headless-host-bridge section 2.3.3): with no gate the options bag has no
+            // such key, so `createBuiltinTools` never enters its mapping branch and the
+            // tool OBJECTS are the ones it builds today.
+            //
+            // THE PAUSE IS `withHumanWait`, NOT A SECOND WRAPPER. `withPausedWatchdog` is
+            // documented as not reentrant, and this is the same function the plan tools
+            // already receive - so an approval wait and a question wait can never nest
+            // two pauses and resume the watchdog one level early.
+            ...(deps.toolGate
+                ? {
+                    toolGate: deps.toolGate,
+                    withToolWait: (fn) => this.withHumanWait(fn),
+                }
+                : {}),
             // Omitted entirely when skills are off, which is what leaves the seven
             // built-ins unwrapped and AC-G17 provable by object identity.
             ...(this.skillsEnabled
@@ -747,6 +857,22 @@ export class AgentController {
                 toolTimeoutOverrides: {
                     ask_user: config.planModeHumanTimeoutMs,
                     submit_plan: config.planModeHumanTimeoutMs,
+                    // THE TWO PHASES, ADDED (headless-host-bridge §2.3.4). The executor
+                    // arms its timer BEFORE the approval wrapper runs, so a ceiling of
+                    // `toolTimeoutMs` alone would leave the tool less than its configured
+                    // budget by exactly the time a human took to answer. ADMITTED
+                    // OVER-GRANT: a caller that answers instantly still gets the sum. The
+                    // opposite trade - charging the wait to the tool - would make "the
+                    // human thought for two minutes" read as "this command is too slow",
+                    // and a tool timeout is supposed to mean the latter.
+                    //
+                    // THE KEY SET IS `CALLER_GATED_TOOLS`, the same constant
+                    // `ToolGate.applies` is built from (I-6): two lists here would drift,
+                    // and the drift would be a gated tool with no wait budget - a
+                    // five-minute approval that kills its own tool at 180 s.
+                    ...(deps.decisionBudgetMs !== undefined
+                        ? gatedToolTimeouts(config.toolTimeoutMs, deps.decisionBudgetMs)
+                        : {}),
                     // A fan-out is not a hung tool either. Like the two above, this
                     // number only bites BECAUSE `task` races `ctx.signal` — the
                     // executor's timeout is cooperative, so an override is inert for any
@@ -831,6 +957,17 @@ export class AgentController {
                 this.activeToolCalls += 1;
             if (event.type === 'tool_execution_end') {
                 this.activeToolCalls = Math.max(0, this.activeToolCalls - 1);
+                // The ONLY proof a skill was adopted is a successful `skill` call. Reading
+                // the model's prose for a skill name would be a heuristic; this is a fact
+                // the executor already reports.
+                if (event.toolName === 'skill' && event.isError !== true)
+                    this.skillLoadedThisTurn = true;
+                // `skill` / `skill_find` do not count as "work done": the notice below is
+                // for a turn that changed something without reading its skill, and a turn
+                // that ONLY searched for a skill is a turn that already tried.
+                if (event.toolName !== 'skill' && event.toolName !== 'skill_find') {
+                    this.toolCallsThisTurn += 1;
+                }
                 // THE ONE PUSH SITE. A notice that could not be pushed here is picked up
                 // by the next tool result (the pull channel) or by the next user turn
                 // (the fill channel), so nothing is lost by declining.
@@ -847,6 +984,9 @@ export class AgentController {
                 // required: `turn_start` covers the next turn of the same run, and this
                 // covers a run that ended with a notice stranded in the queue.
                 this.jobRelay?.requeueUndelivered();
+                // AFTER the requeue, so a turn that ends with a stranded notice still gets
+                // its feedback line. Order between the two is otherwise irrelevant.
+                this.maybeReportSkillTriage();
             }
         });
         if (this.fast) {
@@ -895,13 +1035,27 @@ export class AgentController {
         const tier = resolveFastTier(config, (id, role) => !!makeGetApiKey(config, role)(id));
         const fastAvailable = config === this.config ? this.fast?.available() === true
             : this.fast?.isRegistered() && config.fast.enabled && tier.ok;
+        const skillsCatalog = this.skillsEnabled ? this.skills.catalogBlock() : '';
+        // READ LIVE FROM THE SERVICE, never `config.skills` (§4.2.5 / R-12).
+        // `SkillService.updateConfig` replaces the SERVICE's own config object, so
+        // `this.config.skills` goes stale the moment `/skills triage off` runs — and a
+        // stale read would leave the block in the prompt until the next launch, which
+        // looks exactly like a broken switch. Same discipline as `/todo off`.
+        const triageOn = this.skillsEnabled && this.skills.getConfig().triage === true;
+        // An empty catalog means there is nothing to triage against, so the block is
+        // absent rather than present-and-useless (I-T1 / AC-T18).
+        const triageBlock = triageOn && skillsCatalog.length > 0
+            ? buildSkillTriageBlock({ candidates: this.turnRouting?.candidates ?? [] })
+            : '';
         return buildSystemPrompt({
             cwd: this.cwd,
             tools: this.tools,
-            skillsBlock: this.skillsEnabled ? this.skills.catalogBlock() + this.skills.alwaysBlock() : '',
+            skillsBlock: this.skillsEnabled ? skillsCatalog + this.skills.alwaysBlock() : '',
+            // Immediately after the catalog it refers to, before the plan block whose
+            // first step defers to it (§4.2.4).
+            skillTriageBlock: triageBlock,
             agentMode: this.effectiveMode,
             planInteractive: this.planInteractive,
-            planMaxAskRounds: config.planModeMaxAskRounds,
             // BOTH flags, and both are required (§4.5). `teamRegistered` false means
             // there is no `task` tool to advertise; `teamEnabled` false means the user
             // turned it off for this session. Advertising in either case would
@@ -946,6 +1100,11 @@ export class AgentController {
             // tools that make its promises achievable are registered. With the flag off
             // the prompt is byte-identical to the pre-feature text (I-3).
             jobsBlock: this.jobsRegistered ? buildBackgroundJobsBlock() : '',
+            // FROM THE FIELD, so the block survives every rebuild for the reason the field's
+            // own comment records. Empty everywhere but `aragon exec --result-schema`, and
+            // `buildSystemPrompt` splices it conditionally - so every existing prompt is
+            // byte-identical (I-S1).
+            structuredResultBlock: this.structuredResultBlock,
             // Read from the FIELD on every rebuild, for the reason the field's own
             // comment gives. Empty everywhere but `aragon exec`, and `buildSystemPrompt`
             // splices it conditionally, so every existing prompt is byte-identical.
@@ -1100,7 +1259,7 @@ export class AgentController {
     }
     /** Prepare before clearing the plan, then enter the engine without yielding. */
     async startPrompt(text, options, request) {
-        this.prepareUserTurn(text);
+        this.prepareUserTurn(text, { steering: false });
         if (request !== this.startupSequence) {
             return { status: 'not-started', reason: 'cancelled' };
         }
@@ -1129,10 +1288,39 @@ export class AgentController {
         // failure AC-25 exists to prevent.
         this.jobRelay?.flushForTurn();
     }
-    prepareUserTurn(text) {
+    /**
+     * THE BOUNDARY OF ONE TURN — and there are TWO call sites, which is the reason
+     * this takes an explicit flag instead of resetting everything unconditionally.
+     *
+     * `startPrompt` passes `{ steering: false }`: the user typed something new, so
+     * this really is a new turn. `continue()` passes `{ steering: true }` with the
+     * CONCATENATED queued steering text, which resumes the SAME turn.
+     *
+     * A steer continuation must not re-triage (the candidates would change mid-turn,
+     * and rebuilding the prompt aborts an idle compaction for no gain) and must not
+     * clear the answered-question guard (a long turn interrupted by one steer is
+     * exactly when a repeat question is most likely). Hence per-turn state is
+     * initialised in ONE branch.
+     *
+     * `steering` is REQUIRED and positional-second so each call site states which
+     * kind of turn it is starting, rather than letting a default make "new turn" the
+     * thoughtless option.
+     */
+    prepareUserTurn(text, options) {
         if (this.skillsEnabled)
             this.skills.beginUserTurn();
-        this.askRounds = 0;
+        if (!options.steering) {
+            this.askedFingerprints.clear();
+            this.turnRouting = this.skillsEnabled ? this.skills.triage(text) : null;
+            this.skillLoadedThisTurn = false;
+            this.toolCallsThisTurn = 0;
+            // BEFORE the engine is entered, because `runAgentLoop` captures the system
+            // prompt BY VALUE on its way in — a rebuild after `agent.prompt()` would be
+            // one turn late. This is also why steer does not rebuild: `continue()` runs
+            // while the loop already holds its snapshot, so the cost would be an idle
+            // compaction aborted for a prompt nothing has read yet (§4.2.5).
+            this.rebuildSystemPrompt();
+        }
         this.fast?.setGoal(text);
     }
     /** Cancel pending startup as well as any engine run already in progress. */
@@ -1310,7 +1498,7 @@ export class AgentController {
         }
         if (this.pendingUserSteering.size > 0) {
             const request = ++this.startupSequence;
-            this.prepareUserTurn([...this.pendingUserSteering.values()].join('\n\n'));
+            this.prepareUserTurn([...this.pendingUserSteering.values()].join('\n\n'), { steering: true });
             if (request !== this.startupSequence) {
                 return { status: 'not-started', reason: 'cancelled' };
             }
@@ -1411,18 +1599,90 @@ export class AgentController {
         return {
             effective: this.effectiveMode,
             pending: this.pendingMode,
-            askRoundsUsed: this.askRounds,
-            maxAskRounds: this.config.planModeMaxAskRounds,
         };
     }
-    /** Spend one `ask_user` round. Called from the tool, never from the UI. */
-    takeAskRound() {
-        const max = this.config.planModeMaxAskRounds;
-        if (this.askRounds >= max) {
-            return { ok: false, used: this.askRounds, remaining: 0, max };
+    /**
+     * READ-ONLY guard probe, called by `ask_user` BEFORE it opens the overlay.
+     *
+     * No side effect of any kind: a check that also writes cannot be placed before
+     * the question without recording an answer that has not happened yet, and the
+     * "a cancelled round stays askable" rule would then be unimplementable.
+     */
+    hasAnswered(questions) {
+        return this.askedFingerprints.has(questionFingerprint(questions));
+    }
+    /**
+     * Record an ANSWERED question set, called by `ask_user` after a real answer.
+     *
+     * Evicts the oldest entry past `ASK_GUARD_LIMITS.maxRemembered`. That eviction
+     * is memory hygiene and NOT a refusal rule — a bounded rejection would be the
+     * deleted round cap wearing a bigger number.
+     */
+    noteAnswered(questions) {
+        this.askedFingerprints.add(questionFingerprint(questions));
+        while (this.askedFingerprints.size > ASK_GUARD_LIMITS.maxRemembered) {
+            const oldest = this.askedFingerprints.values().next();
+            if (oldest.done === true)
+                break;
+            this.askedFingerprints.delete(oldest.value);
+        }
+    }
+    /** `/skills route` with no argument: the LAST turn's real routing result. */
+    getSkillRouting() {
+        return this.lastSkillRouting;
+    }
+    /**
+     * One line when a confidently-matched skill was NOT loaded — and silence every
+     * other time (D-8).
+     *
+     * THE DISCIPLINE IS "SILENT ON SUCCESS, VISIBLE ON FAILURE". Announcing the
+     * candidates every turn would be ignored by the third day; announcing nothing
+     * ever would make the whole feature unfalsifiable. "A skill covered this task,
+     * you did the work anyway, and you never opened it" is precisely the failure this
+     * feature exists to fix, so it is the one case that speaks — and it names the
+     * command that explains it.
+     *
+     * SEVEN CONDITIONS, and the first one is the one that is easy to get wrong.
+     *
+     * 0. This turn was NOT aborted and NOT ended by an error.
+     *    `agent_end` is emitted unconditionally from a `finally` block in
+     *    `core/src/engine/agent.ts` and its payload carries no reason, no `aborted`
+     *    and no `error` field — so "did this turn finish normally?" has to be read
+     *    from this class's own state. `stopEngine()` sets `abortRequested` before it
+     *    calls `agent.abort()` and `agent_start` clears it, which makes it an exact
+     *    answer. Without this condition an Esc mis-touch would produce a line
+     *    criticising the model for not loading a skill: commentary in response to an
+     *    interruption.
+     *
+     * Conditions 5 and 0 are not redundant: 0 decides what counts as the end of a
+     * turn, 5 decides whether the turn did any work. With only 5, a tool call made
+     * before an abort would still trigger the notice.
+     */
+    maybeReportSkillTriage() {
+        const routing = this.turnRouting;
+        const best = routing?.candidates[0];
+        const shouldReport = this.abortRequested === false &&
+            this.skillsEnabled &&
+            this.skills.getConfig().triage === true &&
+            routing !== null &&
+            best !== undefined &&
+            best.score >= SKILL_TRIAGE_LIMITS.confidentScore &&
+            this.skillLoadedThisTurn === false &&
+            this.toolCallsThisTurn >= 1 &&
+            !this.skillTriageNoticed.has(best.name);
+        if (shouldReport && best !== undefined) {
+            this.skillTriageNoticed.add(best.name);
+            this.notifyHostFn?.('info', `No skill was loaded; the closest installed match was "${best.name}". ` +
+                'Run /skills route to see why.');
         }
-        this.askRounds += 1;
-        return { ok: true, used: this.askRounds, remaining: max - this.askRounds, max };
+        // The routing result outlives the turn so `/skills route` can explain it; the
+        // candidates themselves must not, or the next `rebuildSystemPrompt()` would
+        // resurrect a set computed for a task that is over.
+        if (routing !== null)
+            this.lastSkillRouting = routing;
+        this.turnRouting = null;
+        this.skillLoadedThisTurn = false;
+        this.toolCallsThisTurn = 0;
     }
     /**
      * Run `fn` with the idle watchdog paused.
@@ -2273,6 +2533,60 @@ export class AgentController {
     fastSnapshot() {
         return this.fast?.snapshot() ?? null;
     }
+    /**
+     * Summarise one user prompt into a header label, using the FAST tier only.
+     *
+     * NEVER REJECTS - the same contract `prompt()` has, and the reason `App` needs
+     * no `.catch`. Every failure is folded into a discriminated
+     * `TaskSummaryOutcome`, because a header label must not be able to produce an
+     * unhandled rejection in a TUI that has nowhere to show one.
+     *
+     * THE CONTROLLER OWNS THE `AbortController` AND ABORTS IT UNCONDITIONALLY on the
+     * way out: `runTaskSummaryCall` may return a `timeout` outcome while the request
+     * is still open (it is forbidden to abort its own call - see that file's
+     * header), so this `finally` is what actually releases the connection.
+     *
+     * EVERY `this.fast` READ IS BEHIND THE CLOSURE, exactly as the reviewer and the
+     * overseer wiring do it: `complete` is only reached from inside the call, which
+     * runs long after construction, so there is no use-before-assign.
+     */
+    async summarizeTask(anchor, opts = {}) {
+        const deps = createTaskSummaryDeps({
+            getConfig: () => this.config,
+            hasKey: (id, role) => this.hasApiKey(id, role),
+            getApiKey: (id, role) => this.resolveKey(id, role),
+            complete: (providerId, request) => {
+                if (this.fast === null) {
+                    // A session whose tier never registered has no fast transport at all;
+                    // rejecting here is caught by `runTaskSummaryCall` and reported as a
+                    // tier reason rather than as a crash.
+                    return Promise.reject(new Error('Fast tier is not registered for this session.'));
+                }
+                return this.fast.completeViaFastRegistry(providerId, request);
+            },
+            ...(opts.ellipsis ? { ellipsis: () => opts.ellipsis } : {}),
+        });
+        const controller = new AbortController();
+        const upstream = opts.signal;
+        const onAbort = () => controller.abort();
+        if (upstream) {
+            if (upstream.aborted)
+                controller.abort();
+            else
+                upstream.addEventListener('abort', onAbort);
+        }
+        try {
+            return await runTaskSummaryCall(deps, {
+                anchor,
+                signal: controller.signal,
+                now: Date.now(),
+            });
+        }
+        finally {
+            upstream?.removeEventListener('abort', onAbort);
+            controller.abort();
+        }
+    }
     // -----------------------------------------------------------------------
     // Context occupancy (context-usage-gauge-accuracy §4.2) — THREE FORWARDERS
     //
@@ -2485,8 +2799,39 @@ export class AgentController {
             return () => { };
         return this.compaction.subscribe(listener);
     }
-    /** List usable tools (name + description) for the /tools command. */
+    /**
+     * List usable tools (name + description) for the /tools command.
+     *
+     * THE UNION, SO THE VIEW AND THE REGISTRY CANNOT DISAGREE (I-13). `system/init`
+     * builds `init.tools` from here, as do `/tools` and `/skills`; reporting only the
+     * host's own set while the model is calling `db_query` is the exact failure that
+     * invariant names - a caller reading "the model has no such tool" about a tool it
+     * is watching run.
+     */
     listTools() {
-        return this.tools;
+        return this.callerTools.length === 0 ? this.tools : [...this.tools, ...this.callerTools];
+    }
+    /**
+     * Replace the caller-served tool set. Called ONLY at a turn boundary.
+     *
+     * `Agent.setTools()` unregisters and re-registers entries in the LIVE registry.
+     * This class already learned the lesson once: `submit_plan` mutates the mode from
+     * INSIDE a tool execution, so rebuilding the array at that moment would mutate
+     * the registry mid-iteration (see the comment on the plan tools). Hence the
+     * refusal rather than a silently deferred write: a caller that registers
+     * mid-turn gets an error it can act on, and the bridge defers the frame instead.
+     *
+     * `[]` is meaningful and not an omission: it means "restore the factory set".
+     */
+    applyCallerTools(tools) {
+        if (this.agent.state.isRunning) {
+            throw new Error('applyCallerTools() called mid-turn; defer to the turn boundary.');
+        }
+        this.callerTools = [...tools];
+        this.agent.setTools([...this.tools, ...this.callerTools]);
+    }
+    /** The names the caller currently serves, for `ack.tools`. */
+    callerToolNames() {
+        return this.callerTools.map((tool) => tool.name);
     }
 }

package/dist/agent/model-profile-settings.js

@@ -97,8 +97,19 @@ export function releasedSlots(draft) {
             || hasConnectionPatch(draft.patch, role))
             released.add(role);
     }
-    if (draft.patch.team !== undefined)
+    // ONLY A MODEL BINDING DECISION RELEASES THE SLOT (subagent-fanout D-7). The
+    // fan-out width and the supervisor live in the SAME `team` section but are not
+    // the kit's business: `{ maxSubagents: 6 }` used to hit the old
+    // `patch.team !== undefined` test, so narrowing the fan-out from the settings
+    // screen silently dropped the subagent model a session kit had installed for
+    // this session - with every value on screen still correct.
+    //
+    // `'model' in patch`, not `patch.model !== undefined`: an explicit
+    // `model: undefined` still means "this transaction spoke about the model".
+    const teamPatch = draft.patch.team;
+    if (teamPatch && ('model' in teamPatch || 'modelProfileId' in teamPatch)) {
         released.add('subagent');
+    }
     return [...released].filter((slot) => held.includes(slot));
 }
 /** The session kit as it stands AFTER this transaction's explicit decisions. */

package/dist/agent/plan-prompt.d.ts

@@ -8,11 +8,9 @@
  * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
  */
 /** Bump when the wording changes, so a transcript can be dated. */
-export declare const PLAN_MODE_BLOCK_VERSION = "v2-2026-10-08";
+export declare const PLAN_MODE_BLOCK_VERSION = "v3-2026-10-26";
 export interface PlanModeBlockOptions {
     /** False under `-p` / piped stdin: no overlay can be rendered, so no tools. */
     interactive: boolean;
-    /** `planModeMaxAskRounds`; substituted into the guidance so the two agree. */
-    maxAskRounds: number;
 }
 export declare function buildPlanModeBlock(options: PlanModeBlockOptions): string;

package/dist/agent/plan-prompt.js

@@ -8,7 +8,7 @@
  * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
  */
 /** Bump when the wording changes, so a transcript can be dated. */
-export const PLAN_MODE_BLOCK_VERSION = 'v2-2026-10-08';
+export const PLAN_MODE_BLOCK_VERSION = 'v3-2026-10-26';
 /**
  * The closing paragraph of the interactive block.
  *
@@ -42,13 +42,18 @@ const HEADLESS_PARAGRAPH = [
     '  write the finished plan as your final message in markdown.',
 ].join('\n');
 export function buildPlanModeBlock(options) {
-    const { interactive, maxAskRounds } = options;
+    const { interactive } = options;
+    // NO ROUND COUNT APPEARS HERE, and none may be reintroduced: the number used
+    // to be substituted from `planModeMaxAskRounds`, which meant the prompt itself
+    // told the model it would run out. "3-5 questions" was also wrong against a
+    // schema and normalizer that both accept 1-5; correcting it here is one line.
     const askStep = interactive
         ? [
             '2. If a decision would change the work and you cannot settle it by reading, call',
-            '   ask_user with 3-5 multiple-choice questions in ONE call. Mark exactly one',
-            `   option recommended:true and put the reason in its description. You may ask up`,
-            `   to ${maxAskRounds} rounds; each round costs the user time, so make them count.`,
+            '   ask_user with 1-5 multiple-choice questions in ONE call. Mark exactly one option',
+            '   recommended:true and put the reason in its description. There is NO round limit -',
+            '   ask as many rounds as the work needs - but each round costs the user time, so batch',
+            '   the questions and skip anything the workspace already answers.',
         ]
         : [
             '2. If a decision would change the work and you cannot settle it by reading, state',
@@ -76,8 +81,9 @@ export function buildPlanModeBlock(options) {
         '',
         'Work in this order:',
         '1. Follow the project-guidance protocol: read applicable guidance and index navigation',
-        '   before any source search or read. Then inspect the real code with read_file,',
-        '   list_dir, glob, grep and relevant skills. Never plan against unread structure.',
+        '   before any source search or read. Then run the skill triage described above and load',
+        '   any skill that covers this task, BEFORE inspecting the real code with read_file,',
+        '   list_dir, glob and grep. Never plan against unread structure.',
         ...askStep,
         ...submitStep,
         '',