@aragon-agent/cli 0.6.39 → 0.6.40

package/dist/team/forced-dispatch.js

@@ -0,0 +1,208 @@
+/**
+ * `/subagent` — parse the user's arguments and compile them into ONE user turn
+ * (subagent-fanout 3.5.2 / 3.5.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and this module
+ * also produces text a model reads in a `cmd.exe` terminal.
+ *
+ * WHY A PROMPT AND NOT A DIRECT `dispatch()` CALL (D-8 / 3.5.1, option C). The
+ * alternative — the command splits the brief itself and calls
+ * `TeamRuntime.dispatch()` — needs a SECOND dispatch entry point (breaking I-1),
+ * a run lifecycle the command does not own (Esc, the lead's idle watchdog, the
+ * report rendered into the transcript, spend accounting, the concurrency lock),
+ * and a planner that cannot see the conversation. Compiling the user's intent
+ * into a normal user turn keeps all of that on the one path that already has it.
+ * The cost is that forcing is INSTRUCTION-LEVEL rather than mechanical, which is
+ * why the command body prints a plan ("the next turn dispatches them") instead
+ * of claiming results (D-10).
+ *
+ * TWO PURE FUNCTIONS, NO IO: parse and compile. Both are deterministic, so the
+ * whole surface is unit-testable without a terminal, a config file or a model.
+ */
+import { TEAM_LIMITS } from './limits.js';
+import { toSlug } from './normalize.js';
+/**
+ * Bumped whenever the directive's wording changes; the string appears VERBATIM
+ * on the directive's first line so a behaviour report ties to one revision with
+ * a single grep (D-15). The `-YYYY-MM` suffix is part of the version, not a
+ * comment: `v1` alone is easy to confuse with the other counters in this package.
+ */
+export const FORCED_DISPATCH_VERSION = 'v1-2026-10';
+/**
+ * A DECIMAL POSITIVE INTEGER, and nothing else.
+ *
+ * `0` is deliberately NOT accepted (R-P1-2). Writing `/subagent -n 0` means the
+ * user mistyped; silently clamping it to 1 would rewrite their intent, which is
+ * the one thing a clamp must never do. `-n 12` is different: 12 is unambiguous
+ * and merely exceeds the ceiling, so it is accepted and DISCLOSED as narrowed.
+ */
+const COUNT_PATTERN = /^[1-9][0-9]*$/;
+/** The flag name of a token, or `null` for a plain word (part of the brief). */
+function flagName(word) {
+    if (word.length < 2 || !word.startsWith('-'))
+        return null;
+    return word.replace(/^--?/, '').toLowerCase();
+}
+/** The brief, clipped with a VISIBLE marker (`forcedBriefChars`). */
+function clippedBrief(brief) {
+    const limit = TEAM_LIMITS.forcedBriefChars;
+    return brief.length > limit ? `${brief.slice(0, limit)}\n[brief truncated]` : brief;
+}
+/**
+ * Parse `/subagent` arguments. ONE parameter (R-P1-1): the structural bounds are
+ * constants this module imports, not a caller's opinion.
+ *
+ * NEVER THROWS and never guesses. Every malformed input maps to one of the four
+ * errors the command body has a sentence for, because "we did something
+ * reasonable with your typo" is indistinguishable from a bug at the terminal.
+ */
+export function parseSubagentArgs(raw) {
+    const words = raw.split(/\s+/).filter((word) => word.length > 0);
+    const brief = [];
+    const parts = [];
+    let count = null;
+    let readOnly = false;
+    // `--parts` was SEEN, even if every item it carried cleaned away. The conflict
+    // rule is about the two flags appearing together, not about the usable parts
+    // that survived: `-n 3 --parts ,,,` still names two sources for one number, and
+    // silently obeying the count would drop a flag the user typed.
+    let sawParts = false;
+    for (let index = 0; index < words.length;) {
+        const word = words[index];
+        const flag = flagName(word);
+        if (flag === null) {
+            brief.push(word);
+            index += 1;
+            continue;
+        }
+        if (flag === 'n' || flag === 'count') {
+            const value = words[index + 1];
+            if (value === undefined || !COUNT_PATTERN.test(value))
+                return { ok: false, error: 'count' };
+            count = Number(value);
+            index += 2;
+            continue;
+        }
+        if (flag === 'parts') {
+            const value = words[index + 1];
+            // A flag with no value is unusable rather than guessable, so it is
+            // reported as a bad option instead of being read as "no parts, then".
+            if (value === undefined)
+                return { ok: false, error: 'flag', token: word };
+            sawParts = true;
+            // A part that cleans to nothing is DROPPED rather than kept as an empty
+            // label; if every part cleans away the flag is treated as absent, because
+            // an empty part list cannot narrow a dispatch the brief still describes.
+            for (const item of value.split(',')) {
+                const slug = toSlug(item);
+                if (slug.length > 0 && !parts.includes(slug))
+                    parts.push(slug);
+            }
+            index += 2;
+            continue;
+        }
+        if (flag === 'read-only') {
+            readOnly = true;
+            index += 1;
+            continue;
+        }
+        // `-n=6` lands here: ONE spelling per option, so the `=` form is an unknown
+        // token rather than a second grammar with its own edge cases.
+        return { ok: false, error: 'flag', token: word };
+    }
+    // Count and parts answer the same question, so a request carrying both is
+    // refused instead of resolved in one direction the user did not choose.
+    if (count !== null && sawParts)
+        return { ok: false, error: 'conflict' };
+    const text = brief.join(' ').trim();
+    if (text.length === 0)
+        return { ok: false, error: 'brief' };
+    return {
+        ok: true,
+        args: {
+            brief: text,
+            count,
+            parts: parts.slice(0, TEAM_LIMITS.forcedPartsMax),
+            partsRequested: parts.length,
+            readOnly,
+        },
+    };
+}
+/**
+ * The sentence naming how many children to start.
+ *
+ * THE PERMISSION CLAUSE IS NOT OPTIONAL IN EITHER BRANCH. `--parts` REPLACES the
+ * count sentence, so a `readOnly` qualifier written only into the count branch
+ * disappears exactly when both flags are used - and `/subagent --read-only
+ * --parts api,ui <brief>` is one of the three examples the README advertises. The
+ * children would then be writeable while the notice said a read-only fan-out was
+ * forced (AC-13).
+ */
+function callSentence(request) {
+    const { count, readOnly, parts } = request;
+    if (parts.length > 0) {
+        const labels = 'Use those exact labels';
+        return `Call the \`task\` tool ONCE with one subagent per part: ${parts.join(', ')}. `
+            + (readOnly ? `${labels}; every spec readOnly: true.` : `${labels}.`);
+    }
+    const noun = count === 1 ? 'subagent' : 'subagents';
+    const permission = readOnly ? ', all readOnly: true' : '';
+    return `Call the \`task\` tool ONCE with exactly ${count} ${noun}${permission}.`;
+}
+/**
+ * The ONE user turn a `/subagent` invocation submits. Same input, same bytes -
+ * which is what makes the snapshot tests meaningful.
+ *
+ * THE ORDER OF THE SENTENCES IS THE ORDER OF THE MODEL'S DECISIONS: what to do
+ * (call `task` ONCE), what it must not do instead (work alone), then the lucky
+ * case (the brief does not split), then the brief itself, then the disclosure
+ * lines, then the per-spec rules.
+ */
+export function buildForcedDirective(request) {
+    const { brief, count, parts, maxSubagents, clamped, requested, planMode } = request;
+    // ONE SENTENCE PER LINE, and deliberately not hard-wrapped: the contract in
+    // 6.4 is checked by grepping phrases (`Call the `task` tool ONCE`, `Use those
+    // exact labels`), and a wrapper that split one of them across a newline would
+    // make the document and the artifact disagree about the same bytes.
+    const lines = [
+        `[forced team dispatch ${FORCED_DISPATCH_VERSION}] The user is forcing a parallel team `
+            + 'on this brief.',
+        callSentence(request),
+        'Then act on the combined report. Do not do the work yourself; the subagents exist to do it.',
+    ];
+    // NO "at least 2" FALLBACK FOR A SINGLE CHILD (R-P1-4): a sentence asking for
+    // at least two would be the louder instruction in a directive that asked for
+    // exactly one, and the model would follow it.
+    if (count > 1 && parts.length === 0) {
+        lines.push(`If the brief genuinely cannot be split into ${count} independent parts, use as many `
+            + 'as it splits into (at least 2) and say why in one line.');
+    }
+    lines.push('', 'Brief:', clippedBrief(brief), '');
+    // A PARTS LIST CAN BE NARROWED BY TWO DIFFERENT CEILINGS (R-P1-3), and the
+    // spec's sentence - "the configured maximum is N" - is only true when the
+    // POLICY ceiling is the one that bit. `parts.length >= maxSubagents` says it
+    // is; below that the structural `forcedPartsMax` did the cutting, and naming
+    // the configured maximum would point the user at a number they can change to
+    // fix a limit they cannot.
+    if (clamped) {
+        if (parts.length > 0) {
+            lines.push(parts.length >= maxSubagents
+                ? `You asked for ${requested} parts; the configured maximum is ${maxSubagents}, `
+                    + 'so the remaining parts are folded into these.'
+                : `You asked for ${requested} parts; only ${parts.length} fit in one directive, `
+                    + 'so the remaining parts are folded into these.');
+        }
+        else {
+            lines.push(`You asked for ${requested}; the configured maximum is ${maxSubagents}, `
+                + `so use ${count}.`);
+        }
+    }
+    if (planMode) {
+        lines.push('Plan mode is on; if the task tool is unavailable this turn, say so instead of '
+            + 'doing the work alone.');
+    }
+    lines.push('Rules for each spec: a self-contained prompt (the child has no memory of this '
+        + `conversation), a description of at most ${TEAM_LIMITS.descriptionChars} chars, a short `
+        + 'slug label, and a disjoint set of files per child.');
+    return lines.join('\n');
+}

package/dist/team/limits.d.ts

@@ -29,6 +29,11 @@ export declare const TEAM_LIMITS: {
      * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
      * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
      * for thirty can exceed it.
+     *
+     * 10 IS THE CEILING, 8 IS THE DEFAULT (`DEFAULT_TEAM_CONFIG`): different
+     * numbers on purpose (subagent-fanout D-1 / D-2). The default is a policy
+     * choice the user may move in either direction from the settings screen; this
+     * bound is what no user may move.
      */
     readonly hardMaxSubagents: 10;
     /** `SubagentSpec.description`, clamped (never rejected). */
@@ -36,6 +41,21 @@ export declare const TEAM_LIMITS: {
     /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
      *  this has to be generous enough to carry a whole brief. */
     readonly promptChars: 8000;
+    /**
+     * The brief `/subagent <brief>` copies into its forced-directive turn
+     * (subagent-fanout 3.5.4 / R-10). CHARACTERS, not bytes, because this bound
+     * feeds a user-visible truncation marker rather than a wire budget: past it
+     * the directive says `[brief truncated]` so a clipped instruction is never
+     * mistaken for a complete one.
+     */
+    readonly forcedBriefChars: 4000;
+    /**
+     * Parts `/subagent --parts a,b,c` may name BEFORE `maxSubagents` narrows them
+     * (subagent-fanout 3.5.2 rule 3). The second, smaller ceiling is the policy
+     * number and belongs to the command body; this one only bounds what one
+     * argument can carry.
+     */
+    readonly forcedPartsMax: 8;
     /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
      *  short enough that five of them fit one row of an 80-column terminal. */
     readonly labelChars: 12;
@@ -245,4 +265,4 @@ export declare const TEAM_SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
  * Bumped whenever the wording of either prompt block changes, so a behaviour
  * report can be tied to a block revision with one grep.
  */
-export declare const TEAM_BLOCK_VERSION = "v1-2026-07";
+export declare const TEAM_BLOCK_VERSION = "v2-2026-10";

package/dist/team/limits.js

@@ -36,6 +36,11 @@ export const TEAM_LIMITS = {
      * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
      * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
      * for thirty can exceed it.
+     *
+     * 10 IS THE CEILING, 8 IS THE DEFAULT (`DEFAULT_TEAM_CONFIG`): different
+     * numbers on purpose (subagent-fanout D-1 / D-2). The default is a policy
+     * choice the user may move in either direction from the settings screen; this
+     * bound is what no user may move.
      */
     hardMaxSubagents: HARD_MAX_SUBAGENTS,
     // --- Spec normalization (§3.3.1) ---
@@ -44,6 +49,21 @@ export const TEAM_LIMITS = {
     /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
      *  this has to be generous enough to carry a whole brief. */
     promptChars: 8000,
+    /**
+     * The brief `/subagent <brief>` copies into its forced-directive turn
+     * (subagent-fanout 3.5.4 / R-10). CHARACTERS, not bytes, because this bound
+     * feeds a user-visible truncation marker rather than a wire budget: past it
+     * the directive says `[brief truncated]` so a clipped instruction is never
+     * mistaken for a complete one.
+     */
+    forcedBriefChars: 4000,
+    /**
+     * Parts `/subagent --parts a,b,c` may name BEFORE `maxSubagents` narrows them
+     * (subagent-fanout 3.5.2 rule 3). The second, smaller ceiling is the policy
+     * number and belongs to the command body; this one only bounds what one
+     * argument can carry.
+     */
+    forcedPartsMax: 8,
     /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
      *  short enough that five of them fit one row of an 80-column terminal. */
     labelChars: 12,
@@ -259,4 +279,4 @@ export const TEAM_SUBAGENT_TOOL_NAMES = new Set(['team_send', 'team_wait']);
  * Bumped whenever the wording of either prompt block changes, so a behaviour
  * report can be tied to a block revision with one grep.
  */
-export const TEAM_BLOCK_VERSION = 'v1-2026-07';
+export const TEAM_BLOCK_VERSION = 'v2-2026-10';

package/dist/team/normalize.d.ts

@@ -30,6 +30,21 @@ export interface NormalizedSpecs {
     /** How many entries the model asked for, before dropping and capping. */
     requested: number;
 }
+/**
+ * The slug rule for a subagent label, EXPORTED because a second caller needs the
+ * same bytes: `/subagent --parts api,UI,tests` cleans its parts through this
+ * function rather than through a copy of the regex (subagent-fanout R-9 /
+ * R-P1-6). Two copies of `[^a-z0-9-]` would drift the first time either side
+ * gains a rule, and the user would see `UI` accepted by one and rewritten by the
+ * other.
+ *
+ * MAY RETURN THE EMPTY STRING. That is the difference from `slugLabel` below:
+ * an empty result is meaningful here ("this part cleans to nothing, drop it"),
+ * whereas a spec's label needs the positional fallback so a child is never
+ * nameless in the panel. The fallback is therefore the CALLER's decision, and
+ * this function stays a pure transformation.
+ */
+export declare function toSlug(raw: unknown): string;
 /**
  * Repair and bound a raw `subagents` array.
  *

package/dist/team/normalize.js

@@ -33,16 +33,33 @@ function clamp(text, maxChars) {
     return trimmed.length > maxChars ? trimmed.slice(0, maxChars) : trimmed;
 }
 /**
- * Slugify a label to `[a-z0-9-]{1,12}`. An empty result falls back to the
- * positional default so a child is never nameless in the panel.
+ * The slug rule for a subagent label, EXPORTED because a second caller needs the
+ * same bytes: `/subagent --parts api,UI,tests` cleans its parts through this
+ * function rather than through a copy of the regex (subagent-fanout R-9 /
+ * R-P1-6). Two copies of `[^a-z0-9-]` would drift the first time either side
+ * gains a rule, and the user would see `UI` accepted by one and rewritten by the
+ * other.
+ *
+ * MAY RETURN THE EMPTY STRING. That is the difference from `slugLabel` below:
+ * an empty result is meaningful here ("this part cleans to nothing, drop it"),
+ * whereas a spec's label needs the positional fallback so a child is never
+ * nameless in the panel. The fallback is therefore the CALLER's decision, and
+ * this function stays a pure transformation.
  */
-function slugLabel(raw, index) {
-    const slug = asString(raw)
+export function toSlug(raw) {
+    return asString(raw)
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, '-')
         .replace(/^-+|-+$/g, '')
         .slice(0, TEAM_LIMITS.labelChars);
+}
+/**
+ * Slugify a label to `[a-z0-9-]{1,12}`. An empty result falls back to the
+ * positional default so a child is never nameless in the panel.
+ */
+function slugLabel(raw, index) {
+    const slug = toSlug(raw);
     return slug.length > 0 ? slug : `a${index + 1}`;
 }
 /**

package/dist/team/prompt.d.ts

@@ -24,10 +24,13 @@ export interface TeamBlockParams {
  * for on EVERY turn of every team-enabled session, so anything that does not
  * change a delegation decision does not belong in it.
  *
- * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * "Two to four is usually enough" is where the requirement's "shu liang zi shi
  * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
- * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
- * that informs it.
+ * elsewhere (`team.maxSubagents`, quoted in the first paragraph); the CHOICE is
+ * the model's, and this paragraph is the only thing that informs it. It names a
+ * USUAL size rather than the maximum on purpose: the default fan-out moved to 8
+ * (subagent-fanout D-1), and a block that told the model "eight is normal"
+ * would turn every two-part job into an eight-agent bill.
  */
 export declare function buildTeamBlock(params: TeamBlockParams): string;
 export interface SubagentBlockParams {

package/dist/team/prompt.js

@@ -20,10 +20,13 @@ export { TEAM_BLOCK_VERSION };
  * for on EVERY turn of every team-enabled session, so anything that does not
  * change a delegation decision does not belong in it.
  *
- * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * "Two to four is usually enough" is where the requirement's "shu liang zi shi
  * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
- * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
- * that informs it.
+ * elsewhere (`team.maxSubagents`, quoted in the first paragraph); the CHOICE is
+ * the model's, and this paragraph is the only thing that informs it. It names a
+ * USUAL size rather than the maximum on purpose: the default fan-out moved to 8
+ * (subagent-fanout D-1), and a block that told the model "eight is normal"
+ * would turn every two-part job into an eight-agent bill.
  */
 export function buildTeamBlock(params) {
     const max = Math.max(1, Math.floor(params.maxSubagents));
@@ -39,8 +42,9 @@ export function buildTeamBlock(params) {
         '',
         'Do not delegate when: one part needs another part\'s result (do those in order',
         'yourself); two parts would edit the same file; the whole job is a few edits.',
-        'One well-scoped subagent is better than four vague ones. Two to four is the',
-        'usual size; more than that is rarely faster.',
+        'One well-scoped subagent is better than four vague ones. Two to four is',
+        'usually enough; go wider only when the parts are genuinely independent - a',
+        'narrow fan-out is cheaper and easier to read.',
         '',
         'Each subagent starts with no memory of this conversation, so its prompt must',
         'carry everything it needs: the goal, the files or areas it owns, and what to',

package/dist/team/task-tool.js

@@ -49,11 +49,11 @@ const TASK_DESCRIPTION = 'Run several independent subagents in parallel and get
     'result (do those yourself, in order), when two parts would edit the same file, or for ' +
     'a change small enough to just make. Subagents cannot dispatch further subagents and ' +
     'cannot ask the user anything. Give each a description of at most ' +
-    `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. Extra entries beyond the ` +
-    'configured maximum are dropped, so keep within it. A supervisor watches the ' +
-    'fan-out: a child that stalls or runs very long may be nudged with guidance ' +
-    'or replaced by a fresh attempt, and the report\'s Supervisor section ' +
-    'records every intervention.';
+    `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. The current fan-out ` +
+    'maximum and concurrency are stated in <team_mode>; extra entries beyond it are ' +
+    'dropped, so keep within it. A supervisor watches the fan-out: a child that ' +
+    'stalls or runs very long may be nudged with guidance or replaced by a fresh ' +
+    'attempt, and the report\'s Supervisor section records every intervention.';
 export function createTaskTool(deps) {
     return {
         name: 'task',
@@ -64,8 +64,12 @@ export function createTaskTool(deps) {
             properties: {
                 subagents: {
                     type: 'array',
-                    description: `2-5 independent subagents to run in parallel (hard maximum ${TEAM_LIMITS.hardMaxSubagents}; ` +
-                        'extras are dropped).',
+                    // NO NUMBER HERE (subagent-fanout D-14): the width is a user setting
+                    // now (`team.maxSubagents`, 8 by default, 10 at most), so a literal
+                    // "2-5" in the schema would contradict the block the model reads in
+                    // the very same request. `<team_mode>` is the single authority.
+                    description: 'Independent subagents to run in parallel in ONE call. See <team_mode> for ' +
+                        'the current maximum and concurrency; extras are dropped.',
                     items: {
                         type: 'object',
                         properties: {

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