@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/agent/controller.d.ts

@@ -19,6 +19,8 @@ import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig,
 import type { ModelRole } from '../config/model-profiles.js';
 import { ModelWindows } from '../config/model-windows.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import type { ToolGate } from '../tools/tool-gate.js';
+import type { ToolHookRunner } from '../exec/hooks/tool-wrapper.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
@@ -28,6 +30,7 @@ import { ProcSupervisor } from '../proc/supervisor.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener, FastSnapshot } from '../fast/types.js';
+import type { TaskSummaryOutcome } from '../fast/task-summary-types.js';
 import { ContextMeter, type ContextUsageListener } from '../compaction/meter.js';
 import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot } from '../compaction/types.js';
 import type { AcceptanceItem, TodoEventListener, TodoSnapshot } from '../todo/types.js';
@@ -100,6 +103,36 @@ export interface ControllerDeps {
      * `tools/index.ts`.
      */
     permission?: ToolPermission;
+    /**
+     * The caller's per-call approval gate (headless-host-bridge §2.3.3).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE. Unlike `permission` it
+     * does NOT reach subagents in this round: every child builds its own tool array
+     * through `team/runtime.ts`, and a fan-out that asked "may I run bash?" once per
+     * child for one decision is an approval waterfall, not a control. Absent on
+     * every existing path, which is what keeps the tool array identical there.
+     */
+    toolGate?: ToolGate;
+    /**
+     * How long a decision may wait, added to the tool's own budget.
+     *
+     * SEE THE TWO-PHASE FORMULA AT `toolTimeoutOverrides`. The executor arms its
+     * timer BEFORE the approval wrapper runs, so a ceiling of `toolTimeoutMs` alone
+     * would give the tool less than its configured time by exactly however long the
+     * caller took to answer.
+     */
+    decisionBudgetMs?: number;
+    /**
+     * The gate each SUBAGENT gets, keyed by its label (headless-host-bridge
+     * section 2.3.7).
+     *
+     * A SEPARATE FIELD BECAUSE THE SCOPE DIFFERS, NOT BECAUSE THE GATE DOES: every
+     * child reports `{id, label, depth: 1}` so the caller can render "subagent A
+     * wants to run bash", while the lead reports `depth: 0`. One shared instance
+     * would attribute every child's request to the lead. Absent outside bridge mode,
+     * which keeps a child's tool array identical today.
+     */
+    toolGateForChild?: (label: string) => ToolGate;
     /**
      * `--append-system-prompt` text, appended verbatim to the composed prompt
      * (§4.1). Threaded through `composeSystemPrompt` so it survives every rebuild
@@ -107,6 +140,41 @@ export interface ControllerDeps {
      * once at construction and lost at the first `rebuildSystemPrompt()`.
      */
     appendSystemPrompt?: string;
+    /**
+     * `submit_result`, registered with the lead's toolset when the caller supplied
+     * `--result-schema` (headless-request-scope-and-typed-result section 2.3.9).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE. It must NOT reach a
+     * subagent: a child's product is a report that goes back through `task`, and a
+     * second submitter inside one request would compete with the lead's schema for the
+     * one accepted value. The child's `createBuiltinTools` call site is
+     * `team/subagent.ts`, and it deliberately passes nothing here.
+     *
+     * Absent on every existing path (the TUI, `-p`, every subcommand), which is what
+     * keeps their tool arrays byte-identical (I-S2).
+     */
+    resultTool?: AgentTool;
+    /**
+     * The rendered `<structured_result>` block, or absent.
+     *
+     * SEE THE FIELD'S OWN COMMENT for why this is threaded through the controller
+     * rather than spliced once: the prompt is rebuilt, and a block that vanished on a
+     * rebuild would leave the model unaware of the contract it is being graded against.
+     */
+    structuredResultBlock?: string;
+    /**
+     * The caller's lifecycle hooks (headless-threads-and-lifecycle-hooks section 2.4.9).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE, in the same shape `resultTool`
+     * is: absent on every existing path (the TUI, `-p`, every subcommand and every
+     * subagent), which is what keeps their tool arrays byte-identical.
+     *
+     * THE CHILD'S CALL SITE IS DELIBERATELY SILENT ABOUT IT. Hooks see the LEAD's tool calls;
+     * a subagent builds its own array in `team/subagent.ts` and a hook installed for tenant
+     * isolation on the lead must not silently become a hook on every child's identical
+     * `read_file` - that is a different security decision with its own design (section 9.5).
+     */
+    hookRunner?: ToolHookRunner;
     /**
      * The per-model window table from ~/.aragon-agent/model-windows.json.
      * Injectable so tests can hand the controller a table without writing into
@@ -131,6 +199,17 @@ export interface PreflightResult {
     /** 'config' for a missing/invalid key or unusable provider. */
     kind?: 'config';
 }
+/** Inputs for one task-label attempt (`AgentController.summarizeTask`). */
+export interface SummarizeTaskOptions {
+    /**
+     * Cancels the call. The CALLER also owns the epoch guard
+     * (tui-shortcut-drawer-and-task-summary D-10): aborting frees the connection,
+     * the epoch decides correctness, and neither substitutes for the other.
+     */
+    signal?: AbortSignal;
+    /** The glyph a cut label ends with. ASCII by default so a headless caller is safe. */
+    ellipsis?: string;
+}
 export declare class AgentController {
     private config;
     private readonly agent;
@@ -143,6 +222,16 @@ export declare class AgentController {
     private modelMetadataAbort;
     private disposed;
     private readonly 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.
+     */
+    private callerTools;
     private readonly skills;
     private readonly skillsEnabled;
     private onSkillsChanged?;
@@ -157,6 +246,17 @@ export declare class AgentController {
      * Empty on every path but `aragon exec`.
      */
     private readonly 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`.
+     */
+    private readonly structuredResultBlock;
     private effectiveMode;
     private pendingMode;
     private askRounds;
@@ -870,6 +970,24 @@ export declare class AgentController {
      * consumed by `App` too, and this round promised to be purely additive.
      */
     fastSnapshot(): FastSnapshot | 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.
+     */
+    summarizeTask(anchor: string, opts?: SummarizeTaskOptions): Promise<TaskSummaryOutcome>;
     /**
      * Subscribe to occupancy publications. Returns an unsubscribe function.
      *
@@ -970,6 +1088,29 @@ export declare class AgentController {
      * `subscribeTodos` and `subscribeFast` already set.
      */
     subscribeCompaction(listener: CompactionEventListener): () => void;
-    /** 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(): AgentTool[];
+    /**
+     * 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: AgentTool[]): void;
+    /** The names the caller currently serves, for `ack.tools`. */
+    callerToolNames(): string[];
 }

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,6 +34,11 @@ 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';
@@ -74,6 +79,16 @@ 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;
@@ -88,6 +103,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.
     //
@@ -308,6 +334,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 +461,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
@@ -599,6 +637,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 +710,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 +809,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
@@ -946,6 +1024,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.
@@ -2273,6 +2356,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 +2622,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/reducer.d.ts

@@ -20,9 +20,17 @@ import type { AcceptanceSnapshot, TodoItem, TodoSnapshot } from '../todo/types.j
 import type { JobKind, ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
+import type { TaskSummaryView } from '../fast/task-summary-types.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
-export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents';
+export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents'
+/**
+ * tui-shortcut-drawer-and-task-summary §4.5: the keyboard drawer (`Ctrl+G` /
+ * `/keys`). A single field, so the drawer and `/help` cannot both hold the
+ * keyboard - which is also why `Ctrl+G` TAKES OVER from another overlay instead
+ * of being swallowed while one is open (P2-3).
+ */
+ | 'shortcuts';
 export type ToolStatus = 'pending' | 'running' | 'done' | 'error';
 /** Ephemeral, auto-dismissed acknowledgement (spec §3.9). */
 export interface Toast {
@@ -391,6 +399,23 @@ export interface ViewState {
      * totals. `null` is what leaves an ordinary session's status bar unchanged.
      */
     compaction: CompactionSnapshot | null;
+    /**
+     * The session's task label, or `null` while there is none
+     * (tui-shortcut-drawer-and-task-summary D-13).
+     *
+     * PURE VIEW STATE: never persisted, never in the conversation history, never in
+     * `config.json`. It lives here because the header and the drawer must read the
+     * SAME field - two copies would be two labels for one task.
+     *
+     * THE TWO WRITERS ARE `taskSummaryPending` / `taskSummaryReady`, and the two
+     * CLEARERS are `resetConversation` and `restoreEntries`: clearing is the
+     * reducer's job (it is the only place that knows a task ended), while
+     * REBUILDING after `/resume` is the App wrapper's job, because only it can see
+     * the restored entries before they are reduced.
+     */
+    taskSummary: TaskSummaryView | null;
+    /** A summary call is in flight. Drives the drawer's `summarizing` line and `/task`. */
+    taskSummaryPending: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -562,6 +587,21 @@ export type ViewAction = {
 } | {
     type: 'restoreEntries';
     entries: Entry[];
+}
+/**
+ * The task label lifecycle (tui-shortcut-drawer-and-task-summary §7.1).
+ *
+ * TWO ACTIONS, because "a call started" and "a call finished" are different
+ * facts and the drawer reports them differently (`summarizing` vs the label).
+ * `taskSummaryReady` carries `null` in exactly one case: the call failed AND
+ * `taskSummary.fallback` is off, which is a deliberate "show nothing" rather
+ * than an empty string that would read as a broken feature.
+ */
+ | {
+    type: 'taskSummaryPending';
+} | {
+    type: 'taskSummaryReady';
+    view: TaskSummaryView | null;
 } | {
     type: 'setAgentMode';
     mode: AgentMode;

package/dist/agent/reducer.js

@@ -67,6 +67,8 @@ export function initialViewState(seed = {}) {
         retry: null,
         fast: null,
         compaction: null,
+        taskSummary: null,
+        taskSummaryPending: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
@@ -906,9 +908,25 @@ export function viewReducer(state, action) {
                 turnProduced: false,
                 errorNoticed: false,
                 aborted: false,
+                // THE TASK LABEL IS PART OF THE TASK (D-13). `/clear`, `/reset` and a
+                // session switch all land here, so the header loses its label without the
+                // App needing a second cleanup path. `/clear screen` does NOT come here -
+                // it keeps the conversation, so it keeps the label.
+                taskSummary: null,
+                taskSummaryPending: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
+        // --- Task summary (tui-shortcut-drawer-and-task-summary §7.1) ----------
+        //
+        // TWO FIELDS, ONE DIRECTION: `pending` is a latch the App raises before the
+        // call and releases on the result, and `taskSummary` is only ever replaced
+        // wholesale. Neither is persisted and neither is derived from `entries`, so a
+        // resumed conversation shows nothing until the App rebuilds the label.
+        case 'taskSummaryPending':
+            return { ...state, taskSummaryPending: true };
+        case 'taskSummaryReady':
+            return { ...state, taskSummary: action.view, taskSummaryPending: false };
         // Pure mirror write. The App only ever dispatches what
         // `controller.setAgentMode()` reported it ADOPTED, so this reducer has no
         // deferral logic of its own to get out of step with (§3.1 / R-P7).
@@ -1423,6 +1441,13 @@ export function viewReducer(state, action) {
                 // NOT cleared — it is the session's own tier projection, which a
                 // `/resume` does not change.
                 fastEntryId: undefined,
+                // `/resume` ADOPTS ANOTHER CONVERSATION, so the previous conversation's
+                // label describes something that is no longer on screen. The reducer only
+                // CLEARS it; the App's `makeCtx().dispatch` wrapper rebuilds one from
+                // `action.entries` (D-13), because it is the only layer that sees the
+                // restored entries BEFORE this branch runs.
+                taskSummary: null,
+                taskSummaryPending: false,
             };
         }
         // --- Background services (§3.10 / D-11) -----------------------------

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

@@ -114,6 +114,20 @@ export interface SystemPromptParams {
      * the child does not have.
      */
     jobsBlock?: string;
+    /**
+     * The rendered `<structured_result>` block, or `''`
+     * (headless-request-scope-and-typed-result section 2.3.8).
+     *
+     * Spliced conditionally exactly as every block above is, which is what keeps I-S1
+     * true: a run without `--result-schema` produces the pre-feature prompt BYTE FOR
+     * BYTE for a fixed tool array.
+     *
+     * POSITION IS THE SEMANTICS. It goes after every subsystem block and before
+     * `## Additional instructions`: it describes the SHAPE OF THE ANSWER, which is
+     * closer to the end of the work than any "how to behave" block, while the caller's
+     * own appended instructions still come last and still win.
+     */
+    structuredResultBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -44,6 +44,7 @@ export function buildSystemPrompt(params) {
     const fastBlock = params.fastBlock ?? '';
     const backgroundBlock = params.backgroundBlock ?? '';
     const jobsBlock = params.jobsBlock ?? '';
+    const structuredResultBlock = params.structuredResultBlock ?? '';
     const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
@@ -67,6 +68,10 @@ export function buildSystemPrompt(params) {
         ...(fastBlock ? ['', fastBlock] : []),
         ...(backgroundBlock ? ['', backgroundBlock] : []),
         ...(jobsBlock ? ['', jobsBlock] : []),
+        // AFTER every subsystem block, BEFORE the caller's own instructions: it describes
+        // the shape of the answer, which is the last thing to know before answering, while
+        // `## Additional instructions` still has the final word (section 2.3.8).
+        ...(structuredResultBlock ? ['', structuredResultBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',