@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/tools/bash-tool.js

@@ -19,12 +19,22 @@
  *      inheriting the pipe — `Start-Process`, `&`, `nohup`, and every
  *      `npm run dev` that re-execs — keeps that pipe open after the shell is
  *      long gone. The shell exited; the promise did not.
+ *
  *   2. `stdio` defaulted to `'pipe'` for stdin, so a command that PROMPTS —
  *      `npm init`, a package manager asking to install something, `sudo`, a git
  *      credential prompt — blocked on a read that could never be satisfied.
  *   3. An abort killed the tree and then went on waiting for a `'close'` that a
  *      detached grandchild was still holding.
  *
+ * WHY THE DRAIN WINDOW IS A BOUND AND NOT A VERDICT. The first build called
+ * anything still unsettled when that window closed "a held pipe" and printed
+ * the `'exit'` drain note on the strength of it. Under load the two disagree:
+ * the release gate caught a command that had printed two lines and exited
+ * immediately being reported as holding its output stream, because the timers
+ * phase came round before libuv delivered the close notification. The note is a
+ * claim about STATE, so it is decided by asking the streams
+ * (`proc/output-streams.ts`) instead of guessing from a clock.
+ *
  * The happy path is BYTE-IDENTICAL to the pre-change build: `$ cmd\n<output>\n
  * [exit code N]`, same truncation, same footer. That is what keeps the existing
  * `bash` assertions meaningful rather than rewritten.
@@ -35,6 +45,7 @@ import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
 import { looksLongRunning } from '../proc/classify.js';
 import { killTree } from '../proc/kill-tree.js';
 import { PROC_LIMITS } from '../proc/limits.js';
+import { hasOpenOutputStreams } from '../proc/output-streams.js';
 import { isTerminalStatus } from '../proc/types.js';
 /**
  * The two sentences appended to the tool description when background launches
@@ -285,6 +296,14 @@ export function makeBash(deps, options = {}) {
                  * the same choice for its `killedByTimeout` flag, for the same reason.
                  */
                 let killReason;
+                /**
+                 * The exit code, remembered the moment `'exit'` reports it.
+                 *
+                 * THREE PATHS SETTLE THE ORDINARY CASE NOW - the two streams ending, the
+                 * `'close'` event, and the drain bound - and all three must build the same
+                 * body, so none of them may depend on having been handed the code itself.
+                 */
+                let exitInfo = null;
                 /**
                  * The result body, from whatever is known at settle time.
                  *
@@ -342,6 +361,25 @@ export function makeBash(deps, options = {}) {
                     releaseForeground();
                     resolvePromise(build());
                 };
+                /** See `proc/output-streams.ts` for why this is asked and not assumed. */
+                const streamsStillOpen = () => hasOpenOutputStreams(child);
+                /**
+                 * THE ORDINARY BODY, built from whatever the streams say at this instant.
+                 *
+                 * Without a held pipe it is byte-identical to the `'close'` path - no note -
+                 * which is what AC-30 measures. With one it is the honest diagnosis, and the
+                 * sentence is only ever printed while it is TRUE.
+                 */
+                const settleOrdinary = () => {
+                    const info = exitInfo;
+                    if (!info)
+                        return;
+                    settle(() => buildBody({
+                        code: info.code,
+                        signalName: info.signalName,
+                        note: streamsStillOpen(),
+                    }));
+                };
                 const captured = () => (output.length > 0 ? output : '(no output)');
                 /**
                  * Arm the post-kill force-settle. AT MOST ONCE.
@@ -421,16 +459,43 @@ export function makeBash(deps, options = {}) {
                     settle(() => errorResult(`Failed to run command: ${err.message}`));
                 });
                 /**
-                 * DEFENCE 1. `'exit'` fires when the PROCESS ends; `'close'` waits for
-                 * every stdio stream, which a detached grandchild can hold open forever.
-                 * So `'exit'` starts a short drain and `'close'` — if it arrives — wins
-                 * the race and produces the byte-identical happy-path body.
+                 * DEFENCE 1. `'exit'` fires when the PROCESS ends; `'close'` waits for every
+                 * stdio stream, which a detached grandchild can hold open forever. So `'exit'`
+                 * starts a short drain and `'close'` - if it arrives - wins the race and
+                 * produces the byte-identical happy-path body.
+                 *
+                 * AND THE COMMON CASE NO LONGER WAITS FOR THAT RACE AT ALL. Two ended streams
+                 * after `'exit'` mean not one more byte can arrive, so the body `'close'` would
+                 * build is already known: settle it there. That removes the only window in which
+                 * a busy event loop could hand the timer a verdict the pipes had already
+                 * contradicted - the release-gate failure recorded in `proc/output-streams.ts`.
                  */
+                const onStreamSettled = () => {
+                    if (!exitInfo || settled)
+                        return;
+                    if (!streamsStillOpen())
+                        settleOrdinary();
+                };
+                child.stdout?.on('end', onStreamSettled);
+                child.stderr?.on('end', onStreamSettled);
                 child.on('exit', (code, signalName) => {
-                    if (settled || drainTimer)
+                    exitInfo = { code, signalName };
+                    if (settled)
+                        return;
+                    if (!streamsStillOpen()) {
+                        settleOrdinary();
+                        return;
+                    }
+                    if (drainTimer)
                         return;
                     drainTimer = setTimeout(() => {
-                        settle(() => buildBody({ code, signalName, note: true }));
+                        // DEFERRED PAST THE POLL PHASE, DELIBERATELY. Asking the streams from
+                        // inside the timer callback would look at them before the loop has
+                        // dispatched an `'end'`/`'close'` already queued behind it - which is
+                        // precisely the starvation that produced the false note. The check phase
+                        // runs after the poll phase of the same iteration, so by then the answer is
+                        // observable rather than guessable.
+                        setImmediate(settleOrdinary);
                     }, PROC_LIMITS.drainMs);
                 });
                 child.on('close', (code, signalName) => {

package/dist/tools/human-input.d.ts

@@ -137,6 +137,23 @@ export declare const PLAN_LIMITS: {
     readonly maxRisks: 10;
     readonly maxOpenQuestions: 10;
 };
+/**
+ * The STORAGE bound of the `ask_user` de-duplication guard — NOT a refusal
+ * condition, and the distinction is the whole point.
+ *
+ * Storage is memory hygiene: a turn that asks a thousand DISTINCT question sets
+ * is pathological, but it is still the user's turn, and Esc interrupts it. The
+ * refusal rule is semantic: "never ask the same answered questions twice". Folding
+ * the bound into the refusal rule would restore the round cap this feature
+ * deletes, with a different number written on it.
+ *
+ * Owned here rather than in `plan-tools.ts` (the caller) or `controller.ts` (the
+ * state holder) because this file is already the single authority on the
+ * structural limits of human input, beside `QUESTION_LIMITS` / `PLAN_LIMITS`.
+ */
+export declare const ASK_GUARD_LIMITS: {
+    readonly maxRemembered: 128;
+};
 /**
  * Trim to `max` characters, preferring a word boundary within the last
  * `WORD_BOUNDARY_WINDOW` characters. Cutting a sentence mid-word reads as
@@ -165,13 +182,29 @@ export declare function normalizePlan(raw: unknown): NormalizedPlan | null;
 export interface AnswersResultShape {
     answers: Answer[];
     cancelled: boolean;
-    roundsUsed: number;
-    roundsRemaining: number;
 }
+/**
+ * A question SET's identity: the question texts, trimmed, lowercased, whitespace
+ * collapsed, sorted, joined.
+ *
+ * `id` and `header` are excluded on purpose — a model that re-asks the same thing
+ * under a new id is asking the same thing, and the ids are the model's own
+ * bookkeeping rather than part of what the user reads.
+ *
+ * The fingerprint is stable because `normalizeQuestions` already ran on the TOOL
+ * side: header truncation and option trimming cannot make the same question look
+ * different here. Worst case is 5 questions x 300 chars = 1,500 chars.
+ */
+export declare function questionFingerprint(questions: NormalizedQuestion[]): string;
 /**
  * Render the `ask_user` result: one human-readable line so the transcript
  * preview is legible without parsing, then the JSON the model reads.
  *
+ * CARRIES NO ROUND COUNTER, deliberately (D-4). The model used to be told
+ * `roundsUsed` / `roundsRemaining` on every call, which is a per-turn reminder
+ * that it is running out — and an agent that reads "you have 1 round left"
+ * behaves like one. There is no limit any more, so there is nothing to report.
+ *
  * `asked` is passed separately rather than derived from `answers.length`
  * because a cancelled wizard returns fewer answers than it asked for, and
  * "answered 1 of 3" is the whole information content of that line.

package/dist/tools/human-input.js

@@ -51,6 +51,21 @@ export const PLAN_LIMITS = {
     maxRisks: 10,
     maxOpenQuestions: 10,
 };
+/**
+ * The STORAGE bound of the `ask_user` de-duplication guard — NOT a refusal
+ * condition, and the distinction is the whole point.
+ *
+ * Storage is memory hygiene: a turn that asks a thousand DISTINCT question sets
+ * is pathological, but it is still the user's turn, and Esc interrupts it. The
+ * refusal rule is semantic: "never ask the same answered questions twice". Folding
+ * the bound into the refusal rule would restore the round cap this feature
+ * deletes, with a different number written on it.
+ *
+ * Owned here rather than in `plan-tools.ts` (the caller) or `controller.ts` (the
+ * state holder) because this file is already the single authority on the
+ * structural limits of human input, beside `QUESTION_LIMITS` / `PLAN_LIMITS`.
+ */
+export const ASK_GUARD_LIMITS = { maxRemembered: 128 };
 /** How far back a truncation will look for a space before cutting hard. */
 const WORD_BOUNDARY_WINDOW = 12;
 // ---------------------------------------------------------------------------
@@ -208,10 +223,33 @@ export function normalizePlan(raw) {
         openQuestions: nonEmptyStrings(src.openQuestions, PLAN_LIMITS.maxOpenQuestions),
     };
 }
+/**
+ * A question SET's identity: the question texts, trimmed, lowercased, whitespace
+ * collapsed, sorted, joined.
+ *
+ * `id` and `header` are excluded on purpose — a model that re-asks the same thing
+ * under a new id is asking the same thing, and the ids are the model's own
+ * bookkeeping rather than part of what the user reads.
+ *
+ * The fingerprint is stable because `normalizeQuestions` already ran on the TOOL
+ * side: header truncation and option trimming cannot make the same question look
+ * different here. Worst case is 5 questions x 300 chars = 1,500 chars.
+ */
+export function questionFingerprint(questions) {
+    return questions
+        .map((q) => q.question.trim().toLowerCase().replace(/\s+/g, ' '))
+        .sort()
+        .join(' | ');
+}
 /**
  * Render the `ask_user` result: one human-readable line so the transcript
  * preview is legible without parsing, then the JSON the model reads.
  *
+ * CARRIES NO ROUND COUNTER, deliberately (D-4). The model used to be told
+ * `roundsUsed` / `roundsRemaining` on every call, which is a per-turn reminder
+ * that it is running out — and an agent that reads "you have 1 round left"
+ * behaves like one. There is no limit any more, so there is nothing to report.
+ *
  * `asked` is passed separately rather than derived from `answers.length`
  * because a cancelled wizard returns fewer answers than it asked for, and
  * "answered 1 of 3" is the whole information content of that line.

package/dist/tools/index.d.ts

@@ -14,6 +14,8 @@ import type { ToolPermission } from '../exec/permission.js';
 import type { FilePatch } from './patch.js';
 import type { ProcSupervisorPort } from '../proc/types.js';
 import type { JobNotice } from '../proc/notices.js';
+import { type ToolGate } from './tool-gate.js';
+import { type ToolHookRunner } from '../exec/hooks/tool-wrapper.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -191,6 +193,22 @@ export interface BuiltinToolsOptions {
      * to the pre-feature build.
      */
     jobTools?: AgentTool[];
+    /**
+     * `submit_result`, appended verbatim when the caller supplied `--result-schema`
+     * (headless-request-scope-and-typed-result section 2.3.9).
+     *
+     * THROUGH THE FACTORY FOR THE REASON `teamTools`, `todoTools`, `procTools` AND
+     * `jobTools` EACH RECORD IN CAPITALS: `tools.test.ts::C7` asserts `HOST_TOOL_NAMES`
+     * equals what this factory PRODUCES, so appending `submit_result` in
+     * `AgentController` after the factory returned would turn it red with a message
+     * about two lists of names that says nothing about structured results.
+     *
+     * ABSENT ON EVERY OTHER PATH - the TUI, `-p`, every subagent - which leaves their
+     * tool array byte-identical to the pre-feature build (I-S2). A subagent must never
+     * receive it: its product is a report that goes back through `task`, and a second
+     * submitter in one request would compete with the lead's schema.
+     */
+    resultTool?: AgentTool;
     /**
      * The completion-notice queue's read side, for the PULL channel (§4.6).
      *
@@ -260,7 +278,81 @@ export interface BuiltinToolsOptions {
      * `ToolPermission.isAllowed` applies for itself.
      */
     permission?: ToolPermission;
+    /**
+     * The per-call approval gate (headless-host-bridge §2.3.3). Bridge mode only.
+     *
+     * ABSENT EVERYWHERE ELSE, which is what keeps every other tool array identical
+     * by object identity: the mapping below runs only when this key exists, the same
+     * house rule `permission` and `jobNotices` follow.
+     */
+    toolGate?: ToolGate;
+    /**
+     * The caller's lifecycle hooks, wrapping `tool_pre` / `tool_post`
+     * (headless-threads-and-lifecycle-hooks section 2.4.9).
+     *
+     * IT IS PRESENT WHENEVER THE HOOK CHANNEL IS OPEN, not only once a hook is registered:
+     * `hook_register` arrives AFTER the controller (and therefore after this factory) was
+     * built, so a wrapper installed lazily would never be installed at all. The wrappers
+     * read the table live and cost one `chainFor` when it is empty, which is why the
+     * observable behaviour with zero hooks is exactly today's.
+     *
+     * ABSENT FOR THE TUI, `-p`, every subagent and every non-bridge exec run - so their tool
+     * arrays stay byte-identical to the pre-feature build (I-H1's spirit, and `tools.test.ts`
+     * C7's letter).
+     */
+    hookRunner?: ToolHookRunner;
+    /**
+     * The host's watchdog pause, handed to the gate wrapper.
+     *
+     * THE SAME FUNCTION the plan tools receive (`withPausedWatchdog`), not a second
+     * wrapper around it: that method is documented as NOT reentrant, and nesting two
+     * pauses would resume the watchdog one level too early.
+     */
+    withToolWait?: <T>(fn: () => Promise<T>) => Promise<T>;
 }
+/**
+ * The filesystem-mutating set the `--confirm` wrapper shares.
+ *
+ * EXPORTED SO `CALLER_GATED_TOOLS` CAN EXTEND IT rather than restating it
+ * (headless-host-bridge §2.3.2). `exec/permission.ts` already records the rule:
+ * a second copy of a name list is a list that drifts, and the drift is discovered
+ * by the tool that is refused in one mode and allowed in the other.
+ */
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
+/**
+ * The names `--permission-mode ask` asks the caller about.
+ *
+ * `MUTATING_TOOLS` is the filesystem set the confirm wrapper already shares.
+ * `skill_install` is deliberately ABSENT: it already has its own gate
+ * (`ApprovalGate`, `exec/bridge/decisions.ts`) and asking twice reads as "no
+ * approval at all" - the same argument that makes `--confirm` and `ask` mutually
+ * exclusive in `exec/options.ts`. `skill_create` is PRESENT because it writes
+ * SKILL.md plus arbitrary bundled files and has no gate of any kind: without it,
+ * `ask` mode would let a headless run create files on disk that the caller never
+ * saw.
+ *
+ * ONE DEFINITION, THREE CONSUMERS: `ToolGate.applies`, the executor's two-phase
+ * timeout override in `agent/controller.ts`, and the acks and docs that report
+ * which tools are gated. That is `BRIDGE_LIMITS`-style discipline (I-6) for a name
+ * set instead of a number.
+ */
+export declare const CALLER_GATED_TOOLS: ReadonlySet<string>;
+/**
+ * The executor timeout each gated tool needs while a human may be answering.
+ *
+ * THE TWO PHASES, ADDED (headless-host-bridge section 2.3.4). `ToolExecutor` 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
+ * the caller 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.
+ *
+ * IT IS A FUNCTION RATHER THAN A LINE IN THE CONTROLLER so the formula has a name
+ * and a test: the numbers here reach a place (`toolTimeoutOverrides`) that no
+ * assertion can read back, and an unreadable ceiling is one that quietly drifts.
+ */
+export declare function gatedToolTimeouts(toolTimeoutMs: number, decisionBudgetMs: number): Record<string, number>;
 /**
  * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
  * this host's tools are read-only — core must not (D-G7).
@@ -309,5 +401,5 @@ export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
  * declaration MEANS, and that reading must not change with how the CLI was
  * started.
  */
-export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "job_wait", "job_list", "task"];
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "job_wait", "job_list", "submit_result", "task"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -14,7 +14,57 @@ import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-too
 import { makeGlob, makeGrep } from './search-tools.js';
 import { makeBash } from './bash-tool.js';
 import { withJobNoticeTail } from './job-tools.js';
-const MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'bash']);
+import { withToolApproval } from './tool-gate.js';
+// VALUE IMPORTS, AND THE DIRECTION IS SAFE: `exec/hooks/tool-wrapper.ts` imports only Core
+// and its own siblings, so `tools/index.ts -> exec/hooks -> (nothing back here)` is not a
+// cycle. The wrappers are plain `{...tool, execute}` objects, exactly like the four this
+// file already composes.
+import { withToolPostHooks, withToolPreHooks, } from '../exec/hooks/tool-wrapper.js';
+/**
+ * The filesystem-mutating set the `--confirm` wrapper shares.
+ *
+ * EXPORTED SO `CALLER_GATED_TOOLS` CAN EXTEND IT rather than restating it
+ * (headless-host-bridge §2.3.2). `exec/permission.ts` already records the rule:
+ * a second copy of a name list is a list that drifts, and the drift is discovered
+ * by the tool that is refused in one mode and allowed in the other.
+ */
+export const MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'bash']);
+/**
+ * The names `--permission-mode ask` asks the caller about.
+ *
+ * `MUTATING_TOOLS` is the filesystem set the confirm wrapper already shares.
+ * `skill_install` is deliberately ABSENT: it already has its own gate
+ * (`ApprovalGate`, `exec/bridge/decisions.ts`) and asking twice reads as "no
+ * approval at all" - the same argument that makes `--confirm` and `ask` mutually
+ * exclusive in `exec/options.ts`. `skill_create` is PRESENT because it writes
+ * SKILL.md plus arbitrary bundled files and has no gate of any kind: without it,
+ * `ask` mode would let a headless run create files on disk that the caller never
+ * saw.
+ *
+ * ONE DEFINITION, THREE CONSUMERS: `ToolGate.applies`, the executor's two-phase
+ * timeout override in `agent/controller.ts`, and the acks and docs that report
+ * which tools are gated. That is `BRIDGE_LIMITS`-style discipline (I-6) for a name
+ * set instead of a number.
+ */
+export const CALLER_GATED_TOOLS = new Set([...MUTATING_TOOLS, 'skill_create']);
+/**
+ * The executor timeout each gated tool needs while a human may be answering.
+ *
+ * THE TWO PHASES, ADDED (headless-host-bridge section 2.3.4). `ToolExecutor` 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
+ * the caller 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.
+ *
+ * IT IS A FUNCTION RATHER THAN A LINE IN THE CONTROLLER so the formula has a name
+ * and a test: the numbers here reach a place (`toolTimeoutOverrides`) that no
+ * assertion can read back, and an unreadable ceiling is one that quietly drifts.
+ */
+export function gatedToolTimeouts(toolTimeoutMs, decisionBudgetMs) {
+    return Object.fromEntries([...CALLER_GATED_TOOLS].map((name) => [name, toolTimeoutMs + decisionBudgetMs]));
+}
 /**
  * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
  * this host's tools are read-only — core must not (D-G7).
@@ -146,6 +196,13 @@ export const HOST_TOOL_NAMES = [
     // (long-task-jobs §4.3).
     'job_wait',
     'job_list',
+    // `submit_result` (headless-request-scope-and-typed-result section 2.3.9) belongs to
+    // the superset for the reason the two job names above do: a skill's
+    // `allowed-tools: [submit_result]` must be answerable, and `--allow-tool` /
+    // `--deny-tool` validate against THIS list. REGISTRATION is a separate decision -
+    // only `--result-schema` registers it, which is why `--deny-tool submit_result`
+    // without a schema is warned about rather than obeyed (`exec/options.ts` W-3).
+    'submit_result',
     // `team_send` / `team_wait` are DELIBERATELY ABSENT (P2-5). This constant
     // answers "can a skill's `allowed-tools` declaration ever take effect?", and
     // those two are never registered on a lead — so a skill naming them genuinely
@@ -309,12 +366,53 @@ export function createBuiltinTools(options) {
     if (options.jobTools && options.jobTools.length > 0) {
         tools = [...tools, ...options.jobTools];
     }
+    // AFTER `jobTools`, BEFORE `teamTools`: `submit_result` is the answer-shaped sibling
+    // of the plan tools rather than a team tool, and keeping a lead's `task` last means
+    // `HOST_TOOL_NAMES` grows by one insertion instead of a reshuffle
+    // (headless-request-scope-and-typed-result section 2.6 row 16).
+    //
+    // INSIDE THE FACTORY, NEVER APPENDED IN `AgentController` - `tools.test.ts::C7`
+    // compares `HOST_TOOL_NAMES` against what this function produces.
+    if (options.resultTool) {
+        tools = [...tools, options.resultTool];
+    }
     // BEFORE both wrappers, so the lead's `task` is covered by the plan gate and
     // the ceiling like everything else, and a child's comm tools are covered by
     // everything except the ceiling (see `policyExempt`).
     if (options.teamTools && options.teamTools.length > 0) {
         tools = [...tools, ...options.teamTools];
     }
+    // --- The caller's per-call approval gate (headless-host-bridge §2.3.3). ---
+    //
+    // AFTER THE LAST APPEND AND BEFORE THE PERMISSION FILTER, for the two structural
+    // reasons the `permission` block below records, plus one of its own: the appends
+    // above are what put `skill_create` in this array, and that is the single
+    // write-capable tool with no other gate. Placing this immediately after
+    // `withConfirmation` - where the array still holds only the seven built-ins -
+    // would leave it permanently unaskable, so a headless run could create files in
+    // the skills directory that the caller never saw.
+    //
+    // At CALL time this ends up inside the plan gate and inside the skill ceiling
+    // (both applied below), which is the order their comments demand: neither needs
+    // I/O, so neither may sit behind a human wait.
+    if (options.toolGate) {
+        const gate = options.toolGate;
+        const withToolWait = options.withToolWait;
+        tools = tools.map((tool) => gate.applies(tool.name)
+            ? withToolApproval(tool, gate, withToolWait ? { withHumanWait: withToolWait } : {})
+            : tool);
+    }
+    // --- The caller's lifecycle hooks: `tool_pre` (section 2.4.9). ---
+    //
+    // IMMEDIATELY AFTER THE APPROVAL GATE, WHICH MAKES IT OUTSIDE IT AT CALL TIME: a human
+    // must approve the arguments the hook produced, never the ones it replaced. The two
+    // policy wrappers below are applied later and are therefore outside this one, so a tool
+    // plan mode already refuses never costs a hook round trip (I-H4b - a recorded trade-off,
+    // not an oversight).
+    if (options.hookRunner) {
+        const hookRunner = options.hookRunner;
+        tools = tools.map((tool) => withToolPreHooks(tool, hookRunner));
+    }
     // --- The `aragon exec` permission filter (cli-integration-surface §4.2). ---
     //
     // ITS OWN `if`, AFTER THE LAST APPEND AND BEFORE THE `toolPolicy` WRAPPER, and
@@ -386,8 +484,19 @@ export function createBuiltinTools(options) {
             return list;
         return list.map((tool) => withJobNoticeTail(tool, () => queue.drain()));
     };
+    // THE OUTERMOST LAYER OF ALL, AND THAT IS THE WHOLE OF I-H13 (section 2.4.9): the
+    // `<job_notices>` tail is appended INSIDE this wrapper and carries a background job's
+    // last raw output lines, so a redactor placed any deeper would miss the most likely
+    // leak. The cost - a `tool_post` `replace` swallows the notice block - is accepted and
+    // documented: every notice is also a `job` event the caller already received.
+    const withHooksPost = (list) => {
+        const hookRunner = options.hookRunner;
+        if (!hookRunner)
+            return list;
+        return list.map((tool) => withToolPostHooks(tool, hookRunner));
+    };
     if (!options.agentMode)
-        return withJobNotices(tools);
+        return withHooksPost(withJobNotices(tools));
     const getMode = options.agentMode;
-    return withJobNotices(tools.map((t) => withPlanModeGate(t, getMode)));
+    return withHooksPost(withJobNotices(tools.map((t) => withPlanModeGate(t, getMode))));
 }

package/dist/tools/plan-tools.d.ts

@@ -17,22 +17,30 @@
  * selected by whether an optional install step succeeded.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import { type HumanInputGate } from './human-input.js';
-/** The outcome of trying to spend one `ask_user` round. */
-export interface AskRoundTicket {
-    ok: boolean;
-    used: number;
-    remaining: number;
-    max: number;
-}
+import { type HumanInputGate, type NormalizedQuestion } from './human-input.js';
 export interface PlanToolsOptions {
     gate: HumanInputGate;
     /**
-     * Spend one `ask_user` round. The counter is owned by the controller because
-     * it resets per user turn, and the controller is the only object that sees a
-     * turn begin.
+     * Read-only: has this exact question SET already been ANSWERED in this turn?
+     *
+     * Called BEFORE `gate.request`, and it must have no side effects — that is why
+     * the guard is two callbacks rather than one. A single read-and-write function
+     * can only be placed before the question (which records an answer nobody gave)
+     * or after it (which cannot prevent a repeat). Both are wrong, and the second
+     * one silently turns "cancelled rounds stay askable" into a lie.
+     */
+    hasAnsweredQuestions: (questions: NormalizedQuestion[]) => boolean;
+    /**
+     * Write-only: remember that this question SET was answered. Called AFTER
+     * `gate.request`, and NEVER when the round was cancelled.
+     *
+     * Cancellation is not consent. `Esc` may be a mis-touch, and turning a
+     * mis-touch into "this question may never be asked again" forces the model to
+     * guess exactly when it most needs to ask — the behaviour this feature exists
+     * to remove. The cheap failure (asking once more) is preferable to the
+     * expensive one (information lost for the rest of the turn).
      */
-    takeAskRound: () => AskRoundTicket;
+    noteAnsweredQuestions: (questions: NormalizedQuestion[]) => void;
     /**
      * Run `fn` with the idle watchdog paused. `try/finally` inside, so a throw in
      * the overlay path cannot leave the watchdog disarmed for the rest of the run.

package/dist/tools/plan-tools.js

@@ -25,18 +25,25 @@ const NO_INTERACTIVE_USER = 'No interactive user is attached (-p/--print mode).
     'state your assumptions explicitly and continue.';
 const NO_INTERACTIVE_REVIEWER = 'No interactive reviewer is attached. Emit the full plan as your final answer ' +
     'in markdown instead.';
-function roundCapRefusal(used) {
-    return (`You have already asked ${used} rounds of questions (the configured maximum). ` +
-        'Proceed with your best assumptions and state them in the plan.');
-}
 // ---------------------------------------------------------------------------
 // ask_user
 // ---------------------------------------------------------------------------
 const ASK_USER_DESCRIPTION = 'Ask the user 1-5 multiple-choice questions when a decision would change the work. ' +
-    'Give each question a stable id, a header of at most 12 characters, and 2-4 options; ' +
-    'exactly one option must set recommended:true, with the reason in its description. ' +
-    'Extra questions or options beyond these limits are dropped, so keep within them. ' +
-    'Do not ask anything you could answer by reading the workspace.';
+    'There is no limit on how many rounds you ask: call this as many times as the work ' +
+    'needs, one batch at a time. Give each question a stable id, a header of at most 12 ' +
+    'characters, and 2-4 options; exactly one option must set recommended:true, with the ' +
+    'reason in its description. Extra questions or options beyond the per-call limits are ' +
+    'dropped, so keep each round inside them. Do not ask anything you could answer by ' +
+    'reading the workspace, and never re-ask a question this turn already answered.';
+/**
+ * The de-duplication notice, as a NON-error result.
+ *
+ * `textResult`, not `errorResult`: a tool failure invites the model to retry the
+ * same call, and its only possible outcome is the same refusal. This is the same
+ * reasoning as the cancellation path below.
+ */
+const DUPLICATE_ROUND_RESULT = 'You already asked this exact set of questions in this turn and the user answered. ' +
+    'Use those answers; if you need something else, ask a different question.';
 function makeAskUser(opts) {
     return {
         name: 'ask_user',
@@ -91,9 +98,10 @@ function makeAskUser(opts) {
             if (questions.length === 0) {
                 return errorResult('No usable questions: each needs 2-4 distinct options.');
             }
-            const ticket = opts.takeAskRound();
-            if (!ticket.ok)
-                return errorResult(roundCapRefusal(ticket.used));
+            // BEFORE the wait: a set the user has already answered must not open an
+            // overlay a second time. Read-only — nothing is recorded here.
+            if (opts.hasAnsweredQuestions(questions))
+                return textResult(DUPLICATE_ROUND_RESULT);
             const response = await opts.withHumanWait(() => opts.gate.request({ kind: 'questions', questions }, ctx.signal));
             // `null` covers cancel, unmount, abort AND timeout. From the model's point
             // of view an unanswered question and an abandoned one are the same
@@ -102,12 +110,11 @@ function makeAskUser(opts) {
             // invites a retry loop.
             const cancelled = response === null || response.kind !== 'answers' || response.cancelled;
             const answers = response !== null && response.kind === 'answers' ? response.answers : [];
-            return textResult(formatAnswersResult({
-                answers,
-                cancelled,
-                roundsUsed: ticket.used,
-                roundsRemaining: ticket.remaining,
-            }, questions.length));
+            // AFTER the answer, and only for a real answer. A cancelled round leaves
+            // the set askable: mis-touch must not cost the user information.
+            if (!cancelled)
+                opts.noteAnsweredQuestions(questions);
+            return textResult(formatAnswersResult({ answers, cancelled }, questions.length));
         },
     };
 }