@aragon-agent/cli 0.6.39 → 0.6.42

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,44 @@ 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";
+/**
+ * The version string on `<forced_team_mode>`'s first line.
+ *
+ * The block's words are a CONTRACT with the model, so a behaviour report ("it
+ * still did the work itself") has to be tieable to one revision. Kept beside
+ * `TEAM_BLOCK_VERSION` rather than reusing it: the two blocks answer different
+ * questions ("can dispatch" versus "must dispatch") and a shared number would
+ * name neither revision.
+ */
+export declare const FORCED_TEAM_BLOCK_VERSION = "v1-2026-10";
+/**
+ * Length ceiling of the `<forced_team_mode>` text.
+ *
+ * THE FIRST BLOCK LENGTH IN THIS SUBSYSTEM THAT A TEST ASSERTS: the `<team_mode>`
+ * block's 1200 is a comment in `team/prompt.ts`, and unifying the two is a
+ * separate small refactor (deliberately out of scope here). Looser than 1200
+ * because this block is only ever paid for while the session is ARMED, and it
+ * carries three layers of instruction rather than one.
+ */
+export declare const FORCED_TEAM_BLOCK_MAX_CHARS = 1400;
+/**
+ * Fallback nudges per user turn. ONE, and not configurable.
+ *
+ * The gate exists because the first two layers (the directive and the prompt
+ * block) both depend on the model cooperating. A second nudge would double the
+ * worst case of a model that is simply not going to dispatch - at N children per
+ * attempt - and D-8's whole argument is that the mechanical layer must be
+ * bounded by something other than the model's willingness.
+ */
+export declare const FORCED_NUDGE_LIMIT = 1;
+/**
+ * Grace window before the fallback nudge fires, in milliseconds.
+ *
+ * SAME ORDER AS THE TODO FOLLOW-THROUGH GRACE, for a structural reason rather
+ * than a stylistic one: both continuations share ONE `followTimer` in `App`
+ * (I-9), so "at most one armed continuation" is only explicable while the two
+ * numbers stay in the same order of magnitude. **Changing todo's grace means
+ * re-reading this constant.**
+ */
+export declare const FORCED_NUDGE_GRACE_MS = 3000;

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,52 @@ 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';
+// ---------------------------------------------------------------------------
+// Forced team mode (`/team <brief>`, team-command-forced-dispatch §6.5).
+//
+// FOUR STRUCTURAL NUMBERS, here rather than in the modules that read them for
+// the reason this file's header records: none of them is a user preference, and
+// a `config.json` key for any of them would make "the model ignored the
+// instruction" tunable by the person the instruction exists to protect.
+// ---------------------------------------------------------------------------
+/**
+ * The version string on `<forced_team_mode>`'s first line.
+ *
+ * The block's words are a CONTRACT with the model, so a behaviour report ("it
+ * still did the work itself") has to be tieable to one revision. Kept beside
+ * `TEAM_BLOCK_VERSION` rather than reusing it: the two blocks answer different
+ * questions ("can dispatch" versus "must dispatch") and a shared number would
+ * name neither revision.
+ */
+export const FORCED_TEAM_BLOCK_VERSION = 'v1-2026-10';
+/**
+ * Length ceiling of the `<forced_team_mode>` text.
+ *
+ * THE FIRST BLOCK LENGTH IN THIS SUBSYSTEM THAT A TEST ASSERTS: the `<team_mode>`
+ * block's 1200 is a comment in `team/prompt.ts`, and unifying the two is a
+ * separate small refactor (deliberately out of scope here). Looser than 1200
+ * because this block is only ever paid for while the session is ARMED, and it
+ * carries three layers of instruction rather than one.
+ */
+export const FORCED_TEAM_BLOCK_MAX_CHARS = 1400;
+/**
+ * Fallback nudges per user turn. ONE, and not configurable.
+ *
+ * The gate exists because the first two layers (the directive and the prompt
+ * block) both depend on the model cooperating. A second nudge would double the
+ * worst case of a model that is simply not going to dispatch - at N children per
+ * attempt - and D-8's whole argument is that the mechanical layer must be
+ * bounded by something other than the model's willingness.
+ */
+export const FORCED_NUDGE_LIMIT = 1;
+/**
+ * Grace window before the fallback nudge fires, in milliseconds.
+ *
+ * SAME ORDER AS THE TODO FOLLOW-THROUGH GRACE, for a structural reason rather
+ * than a stylistic one: both continuations share ONE `followTimer` in `App`
+ * (I-9), so "at most one armed continuation" is only explicable while the two
+ * numbers stay in the same order of magnitude. **Changing todo's grace means
+ * re-reading this constant.**
+ */
+export const FORCED_NUDGE_GRACE_MS = 3000;

package/dist/team/model.d.ts

@@ -5,16 +5,16 @@
  * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
  *
  * EVERY CONSUMER READS THE CHILD'S MODEL THROUGH THIS FUNCTION AND NOWHERE
- * ELSE — `createSubagent`, the `task` report header, the settings root row and
- * `/team model` — following the `resolveFastTier` precedent one directory over:
- * four call sites each recomputing "which model do children run on?" from raw
+ * ELSE — `createSubagent`, the `task` report header and the settings root row —
+ * following the `resolveFastTier` precedent one directory over: three call
+ * sites each recomputing "which model do children run on?" from raw
  * config keys is exactly how the report ends up naming a model the children
  * silently fell back from.
  *
  * IT IS RE-RUN ON EVERY DISPATCH AND EVERY RENDER, NOT ONCE (rule 8 / RV-3 of
  * the fast tier, inherited here): `team.model`, the fast tier and the profile
- * library are all LIVE keys a settings save, `/fast off` or `/team model` can
- * rewrite mid-session. A resolution captured at construction would be a
+ * library are all LIVE keys a settings save (the `Subagent model` row), `/fast
+ * off` or a kit can rewrite mid-session. A resolution captured at construction would be a
  * resolution describing a session that no longer exists.
  *
  * A CHILD IS NEVER LEFT WITHOUT A MODEL (D-4). Every failure mode — fast tier

package/dist/team/model.js

@@ -5,16 +5,16 @@
  * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
  *
  * EVERY CONSUMER READS THE CHILD'S MODEL THROUGH THIS FUNCTION AND NOWHERE
- * ELSE — `createSubagent`, the `task` report header, the settings root row and
- * `/team model` — following the `resolveFastTier` precedent one directory over:
- * four call sites each recomputing "which model do children run on?" from raw
+ * ELSE — `createSubagent`, the `task` report header and the settings root row —
+ * following the `resolveFastTier` precedent one directory over: three call
+ * sites each recomputing "which model do children run on?" from raw
  * config keys is exactly how the report ends up naming a model the children
  * silently fell back from.
  *
  * IT IS RE-RUN ON EVERY DISPATCH AND EVERY RENDER, NOT ONCE (rule 8 / RV-3 of
  * the fast tier, inherited here): `team.model`, the fast tier and the profile
- * library are all LIVE keys a settings save, `/fast off` or `/team model` can
- * rewrite mid-session. A resolution captured at construction would be a
+ * library are all LIVE keys a settings save (the `Subagent model` row), `/fast
+ * off` or a kit can rewrite mid-session. A resolution captured at construction would be a
  * resolution describing a session that no longer exists.
  *
  * A CHILD IS NEVER LEFT WITHOUT A MODEL (D-4). Every failure mode — fast tier

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.

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));
         },
     };
 }