@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/team/subagent.js

@@ -14,7 +14,7 @@ import { Agent, createSkillFindTool, } from '@aragon-agent/core';
 import { formatStreamError } from '../agent/reducer.js';
 import { buildSystemPrompt } from '../agent/system-prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
-import { createBuiltinTools } from '../tools/index.js';
+import { createBuiltinTools, gatedToolTimeouts, } from '../tools/index.js';
 import { describeToolActivity, pickActivityArgs, sanitizeActivity } from './activity.js';
 import { TEAM_LIMITS, TEAM_SUBAGENT_TOOL_NAMES } from './limits.js';
 import { appendTimeline } from './timeline.js';
@@ -24,6 +24,26 @@ import { makeTeamSend, makeTeamWait, withMailboxTail } from './comm-tools.js';
 import { buildSubagentBlock } from './prompt.js';
 /** The default factory: a real `Agent` from `@aragon-agent/core`. */
 export const defaultSubagentFactory = (config) => new Agent(config);
+/**
+ * Hold a child's idle watchdog across a caller wait.
+ *
+ * The child's watchdog is its own (that is the point of a separate ceiling), so a
+ * four-minute approval would otherwise abort the child and take the dispatch with
+ * it - R-1, one level down. `finally` is what makes "paused" never outlive the
+ * wait, including on an abort.
+ */
+function pauseChildWatchdog(getAgent) {
+    return async (fn) => {
+        const agent = getAgent();
+        agent?.pauseIdleWatchdog();
+        try {
+            return await fn();
+        }
+        finally {
+            agent?.resumeIdleWatchdog();
+        }
+    };
+}
 /** The final assistant text of a turn, or `''` when the turn was tool calls only. */
 function assistantText(message) {
     if (!message || !Array.isArray(message.content))
@@ -59,6 +79,21 @@ export function buildSubagentTools(spec, deps, getAgent) {
     const tools = createBuiltinTools({
         getCwd: deps.getCwd,
         confirmTools: deps.confirmTools,
+        // THE CHILD ASKS THE CALLER TOO (section 2.3.7). Without this the approval
+        // gate would hold for the lead and be bypassed by one `task` call - the hole
+        // the `--deny-tool` pass-through above records, one feature later and with a
+        // human on the other end of it who believes they are approving everything.
+        //
+        // The watchdog pause is the CHILD'S OWN, never `TeamHumanQueue`'s: that queue
+        // is `--confirm`'s, and nesting a second pause is exactly what
+        // `withPausedWatchdog` forbids. `getAgent()` is the same live handle the queue
+        // and `team_wait` already use.
+        ...(deps.toolGateFor
+            ? {
+                toolGate: deps.toolGateFor(spec.label),
+                withToolWait: pauseChildWatchdog(getAgent),
+            }
+            : {}),
         // Queued through the ONE human slot, with this child's watchdog paused for
         // the whole queue wait (§3.11 / I-4 / P0-4).
         ...(deps.confirmTools && deps.humanQueue
@@ -253,6 +288,15 @@ export function createSubagent(spec, deps, hooks) {
         ...(deps.config.maxTokens !== undefined ? { maxTokens: deps.config.maxTokens } : {}),
         timeouts: {
             toolTimeout: deps.config.toolTimeoutMs,
+            // THE SAME TWO PHASES THE LEAD GETS (section 2.3.4). A child that asks the
+            // caller and waits is billed for the wait out of its tool's budget unless
+            // this is here, and the symptom would be "the approved command was killed
+            // mid-run" only inside a fan-out.
+            ...(deps.toolGateFor && deps.decisionBudgetMs !== undefined
+                ? {
+                    toolTimeoutOverrides: gatedToolTimeouts(deps.config.toolTimeoutMs, deps.decisionBudgetMs),
+                }
+                : {}),
             // A child keeps its OWN idle watchdog, and that is a feature: a wedged
             // child is aborted by its own ceiling without taking the dispatch with it
             // (§3.8). The two places a child legitimately blocks on something other

package/dist/tools/bash-tool.d.ts

@@ -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.

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/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/tool-gate.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The per-call approval gate: one wrapper, one shared denial text, no I/O.
+ *
+ * ASCII ONLY - `src/tools/**` is inside the glyph scanner's scope.
+ *
+ * WHY A WRAPPER AND NOT A CORE HOOK (headless-host-bridge section 2.3.3). A
+ * `beforeExecute` callback on Core's `ToolExecutor` would put a human wait in
+ * front of the plan gate's refusal, freeze a new field into the public API that
+ * `public-api.test.ts` guards, and teach the engine about a host shape it has no
+ * business knowing. The `{...tool, execute}` shape below is the one already used
+ * three times in `tools/index.ts` (confirmation, skill ceiling, plan gate), so
+ * nothing in the engine has to learn that an approval exists.
+ *
+ * WHERE IT SITS IN THE STACK IS PART OF THE DESIGN, not an accident of import
+ * order: `tools/index.ts` applies it AFTER every append (so `skill_create` is
+ * reachable) and BEFORE the `toolPolicy` / plan-gate wrappers are added, so at
+ * call time those two refusals - which need no I/O - happen first and a tool that
+ * policy would refuse never interrupts a human.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+export interface ToolGateRequest {
+    tool: string;
+    /** Core's tool-call id, so the caller can pair this with the `tool_call` event. */
+    callId: string;
+    input: Record<string, unknown>;
+    /** One readable line: `Run: npm test`. Comes from the same `summarize()`. */
+    summary: string;
+    /** The turn this belongs to, when the host can say. */
+    turn?: number;
+    /**
+     * The tool's `ctx.signal`. WITHOUT IT THE WAIT HAS NO CEILING: the idle
+     * watchdog is paused for the duration and the executor's own timeout only
+     * aborts the context, so an unanswered request would wait for the process to
+     * die. Passed through, never invented.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * `message` is the model-visible text used VERBATIM when present.
+ *
+ * The three non-approval outcomes are not variations of "denied": a timeout says
+ * how long it waited, an interruption says the turn ended. Collapsing them into
+ * one sentence would make the model re-try a command after a one-second user
+ * click and would hide a real timeout in a log that reads like a refusal.
+ */
+export type ToolGateVerdict = {
+    allow: true;
+} | {
+    allow: false;
+    reason?: string;
+    message?: string;
+};
+export interface ToolGate {
+    /**
+     * PURE AND NAME-ONLY: `CALLER_GATED_TOOLS.has(name)`.
+     *
+     * The session-level allow set is deliberately NOT consulted here - it lives in
+     * `decide()`. Mixing them would make `applies()` stateful, and the object
+     * identity assertions that prove "no gate means no change" would stop being
+     * decidable.
+     */
+    applies(toolName: string): boolean;
+    /** NEVER rejects. Resolves `deny` on abort / timeout / capacity / closure. */
+    decide(request: ToolGateRequest): Promise<ToolGateVerdict>;
+}
+/**
+ * THE ONE PLACE A DENIAL IS WORDED. Shared by the wrapper below and by the tests,
+ * so "the model is told what happened and what to do instead" is a single string
+ * rather than a paragraph repeated in two modules.
+ *
+ * The last sentence is not politeness. A bare "denied" makes a model retry the
+ * same call; the observed failure mode is a paid loop that burns a budget on one
+ * forbidden command. Naming the tool and the reason is what lets it route around
+ * the refusal instead.
+ */
+export declare function denialMessage(tool: string, reason?: string): string;
+/** The text a timed-out decision produces. Exported for the same reason. */
+export declare function timeoutMessage(tool: string, timeoutMs: number): string;
+/** The text an aborted turn produces, in the middle of a decision wait. */
+export declare function interruptedMessage(tool: string): string;
+export interface WithToolApprovalOptions {
+    /**
+     * The host's watchdog pause, forwarded straight from the controller.
+     *
+     * THE WAIT IS THE WHOLE REASON IT EXISTS: the idle watchdog would otherwise fire
+     * mid-approval and abort a run the user was in the middle of authorising, which
+     * on screen reads as "it randomly stopped". `withPausedWatchdog` is not
+     * reentrant, so this is the SAME function the plan tools receive rather than a
+     * second wrapper around it.
+     */
+    withHumanWait?: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+/**
+ * Wrap a tool behind the gate. Same `{...tool, execute}` shape as every other
+ * wrapper in this package, and the same `errorResult` discipline: a refusal is a
+ * TOOL RESULT, never a throw, because the engine pushes whatever this returns
+ * into history - and a `tool_use` with no `tool_result` is an HTTP 400 on the next
+ * request.
+ */
+export declare function withToolApproval(tool: AgentTool, gate: ToolGate, options?: WithToolApprovalOptions): AgentTool;