@aragon-agent/cli 0.6.40 → 0.6.42

package/dist/team/dispatch-gate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The dispatch gate: the THIRD and only MECHANICAL layer of forced team mode
+ * (team-command-forced-dispatch §3.7 / §6.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A MECHANICAL LAYER EXISTS AT ALL. The directive and the prompt block are
+ * both requests, and a request can be declined. The requirement behind `/team`
+ * is a COMMITMENT - "after the lead plans, subagents must do the work" - so the
+ * one part of it that does not depend on the model's cooperation is a decision
+ * taken by the host after the turn has already ended. Everything here is a pure
+ * function of four facts the caller counted, which is what keeps `ui/App.tsx`
+ * to wiring rather than policy.
+ *
+ * THREE BOUNDS, AND NONE OF THEM IS DECORATION (D-8):
+ *  - `toolsUsed > 0`   - a pure question ("what did those two children find?")
+ *                        must be answerable from context; nudging it would buy a
+ *                        second dispatch of a fact already in the transcript.
+ *  - `nudgesUsed < 1`  - a model that will not dispatch must not turn into an
+ *                        unbounded paid loop. `FORCED_NUDGE_LIMIT` is the whole
+ *                        defence, and I-10 pins WHERE it is reset (the user's own
+ *                        submit, never `agent_start`) because a per-turn reset
+ *                        would make this bound disappear while every test stayed
+ *                        green.
+ *  - `!aborted && !errored` - Esc and a provider failure are not disobedience.
+ *                        Urging a re-dispatch after an error would spend money to
+ *                        reproduce the error.
+ *
+ * `dispatchAttempted` IS NOT `dispatched` (P1-7). The `task` tool refuses for
+ * three reasons that never emit `dispatch_start` - team off, dispatch busy, no
+ * API key - and each of those refusals is the upstream telling the model "no".
+ * Counting only real dispatches would have the gate say "you dispatched nothing,
+ * dispatch now", the model comply, and the same refusal arrive twice: two turns
+ * of noise around a fact both layers already knew.
+ */
+/** The four facts the caller counts, and the run's own verdict on itself. */
+export interface ForcedDispatchProbe {
+    /** `getForcedTeam() !== null`. */
+    armed: boolean;
+    /**
+     * The armed fan-out count, echoed into the nudge's first sentence.
+     *
+     * NOT IN §3.7's FIVE-FIELD PROBE, and the omission does not survive contact
+     * with §5.2: the decision carries the MESSAGE (`{ kind: 'nudge'; message }`)
+     * and `App` submits `gate.message` verbatim, so the number the nudge names has
+     * to reach this function somehow. Reading it here - from the same probe the
+     * gate already receives - keeps the decision a pure function of its argument
+     * instead of forcing the caller to rebuild the message and losing the guarantee
+     * that `buildDispatchNudge()` is the only author of those bytes. Ignored when
+     * `armed` is false (see `team-command-forced-dispatch` spec,
+     * `## 实施过程发现的方案缺陷`).
+     */
+    count: number;
+    /** This turn emitted `dispatch_start` OR called `task` at least once (even refused). */
+    dispatchAttempted: boolean;
+    /** Tool calls the MODEL made this turn. Zero means a pure answer. */
+    toolsUsed: number;
+    /** Fallback nudges already spent. Reset only by a user-initiated submit (I-10). */
+    nudgesUsed: number;
+    runEnd: {
+        aborted: boolean;
+        errored: boolean;
+    };
+}
+export type ForcedDispatchDecision = {
+    kind: 'none';
+} | {
+    kind: 'nudge';
+    message: string;
+};
+/** The line written to the USER before the nudge is submitted (§6.4). */
+export declare const FORCED_NUDGE_NOTICE = "Forced team mode: no dispatch last turn - asking the agent to dispatch now.";
+/**
+ * The nudge itself, verbatim from §6.4.
+ *
+ * It names a NUMBER and then immediately permits fewer, because the one thing
+ * worse than a missing dispatch is four children inventing work to justify
+ * themselves. The closing sentence repeats the directive's prohibition: this
+ * message is the model's whole context for the turn it is about to run.
+ */
+export declare function buildDispatchNudge(count: number): string;
+/**
+ * Should the host ask for one more turn? Every clause must hold, short-circuiting
+ * in the order the header records so a cheap fact answers before a costly one.
+ */
+export declare function decideForcedDispatch(probe: ForcedDispatchProbe): ForcedDispatchDecision;

package/dist/team/dispatch-gate.js

@@ -0,0 +1,75 @@
+/**
+ * The dispatch gate: the THIRD and only MECHANICAL layer of forced team mode
+ * (team-command-forced-dispatch §3.7 / §6.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A MECHANICAL LAYER EXISTS AT ALL. The directive and the prompt block are
+ * both requests, and a request can be declined. The requirement behind `/team`
+ * is a COMMITMENT - "after the lead plans, subagents must do the work" - so the
+ * one part of it that does not depend on the model's cooperation is a decision
+ * taken by the host after the turn has already ended. Everything here is a pure
+ * function of four facts the caller counted, which is what keeps `ui/App.tsx`
+ * to wiring rather than policy.
+ *
+ * THREE BOUNDS, AND NONE OF THEM IS DECORATION (D-8):
+ *  - `toolsUsed > 0`   - a pure question ("what did those two children find?")
+ *                        must be answerable from context; nudging it would buy a
+ *                        second dispatch of a fact already in the transcript.
+ *  - `nudgesUsed < 1`  - a model that will not dispatch must not turn into an
+ *                        unbounded paid loop. `FORCED_NUDGE_LIMIT` is the whole
+ *                        defence, and I-10 pins WHERE it is reset (the user's own
+ *                        submit, never `agent_start`) because a per-turn reset
+ *                        would make this bound disappear while every test stayed
+ *                        green.
+ *  - `!aborted && !errored` - Esc and a provider failure are not disobedience.
+ *                        Urging a re-dispatch after an error would spend money to
+ *                        reproduce the error.
+ *
+ * `dispatchAttempted` IS NOT `dispatched` (P1-7). The `task` tool refuses for
+ * three reasons that never emit `dispatch_start` - team off, dispatch busy, no
+ * API key - and each of those refusals is the upstream telling the model "no".
+ * Counting only real dispatches would have the gate say "you dispatched nothing,
+ * dispatch now", the model comply, and the same refusal arrive twice: two turns
+ * of noise around a fact both layers already knew.
+ */
+import { FORCED_NUDGE_LIMIT } from './limits.js';
+/** The line written to the USER before the nudge is submitted (§6.4). */
+export const FORCED_NUDGE_NOTICE = 'Forced team mode: no dispatch last turn - asking the agent to dispatch now.';
+/**
+ * The nudge itself, verbatim from §6.4.
+ *
+ * It names a NUMBER and then immediately permits fewer, because the one thing
+ * worse than a missing dispatch is four children inventing work to justify
+ * themselves. The closing sentence repeats the directive's prohibition: this
+ * message is the model's whole context for the turn it is about to run.
+ */
+export function buildDispatchNudge(count) {
+    return [
+        'Forced team mode is on and the last turn dispatched nothing. Call the `task` tool now',
+        `with ${count} subagents - or fewer if the work genuinely does not split - then report `
+            + 'their',
+        'combined result. Do not do the work yourself.',
+    ].join('\n');
+}
+/**
+ * Should the host ask for one more turn? Every clause must hold, short-circuiting
+ * in the order the header records so a cheap fact answers before a costly one.
+ */
+export function decideForcedDispatch(probe) {
+    if (!probe.armed)
+        return { kind: 'none' };
+    // A REFUSED `task` STILL COUNTS (P1-7): "attempted" is the honest predicate.
+    if (probe.dispatchAttempted)
+        return { kind: 'none' };
+    if (!(probe.toolsUsed > 0))
+        return { kind: 'none' };
+    if (probe.runEnd.aborted || probe.runEnd.errored)
+        return { kind: 'none' };
+    if (probe.nudgesUsed >= FORCED_NUDGE_LIMIT)
+        return { kind: 'none' };
+    // THE MESSAGE IS BUILT HERE, from the same probe, so `buildDispatchNudge()`
+    // stays the only author of these bytes and the caller can submit
+    // `decision.message` without reconstructing it.
+    return { kind: 'nudge', message: buildDispatchNudge(probe.count) };
+}

package/dist/team/forced-mode.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Forced team mode: the SESSION STATE type and the PURE half of `/team`
+ * (team-command-forced-dispatch §3.3 / §3.5 / §5.2).
+ *
+ * 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.
+ *
+ * WHAT IS AND IS NOT HERE. Every export below is a deterministic function of its
+ * arguments: no `CommandContext`, no controller, no IO, no React. That is what
+ * lets the whole grammar - control words, the quote escape hatch, the two
+ * ceilings, the disclosure line - be tested without a terminal, a config file or
+ * a model. The command body (`commands/team-command.ts`) keeps the ctx-dependent
+ * half: speaking to the user, arming the session, submitting the turn.
+ *
+ * THE INTENT IS PARSED IN ONE STEP (§3.3), because the three rules interact:
+ *
+ *  1. CONTROL WORDS ARE WHOLE-ARGUMENT ONLY. `off the record` is a brief whose
+ *     first word happens to be `off`; treating it as "turn off, then take notes"
+ *     would delete a legitimate brief from the grammar.
+ *  2. THE QUOTE ESCAPE HATCH IS CHECKED BEFORE THE CONTROL WORDS. `/team "off"`
+ *     asks for a fan-out on the brief `off`. Without this rule the three control
+ *     words would be permanently unavailable as briefs, and a user working on a
+ *     feature called "off" would have no way to say so.
+ *  3. FLAG PARSING IS NOT REIMPLEMENTED. `parseSubagentArgs` owns the four error
+ *     classes and both disclosure ceilings, and its bytes are pinned by
+ *     `subagent-command.test.ts`; a second grammar here would drift from it on
+ *     the first `-n=6` someone tried.
+ */
+import type { SubagentCommandArgs } from './forced-dispatch.js';
+import type { TeamConfig } from '../config/schema.js';
+/**
+ * The default count when the user names none (D-7).
+ *
+ * FOUR, not `maxSubagents`: `<team_mode>` tells the model two to four is usually
+ * enough, so "force one dispatch" must not silently become the most expensive
+ * call the session can make. The status line advertises the real ceiling so the
+ * user who wants the widest fan-out knows which flag to add.
+ */
+export declare const DEFAULT_FORCED_COUNT = 4;
+/**
+ * What one `/team ...` argument string means. A TOTAL union: every input the
+ * lexer can see maps to exactly one member, which is what lets the command body
+ * be a flat dispatch rather than a chain of "did we already answer?" flags.
+ */
+export type TeamIntent = {
+    kind: 'status';
+} | {
+    kind: 'off';
+} | {
+    kind: 'on';
+} | {
+    kind: 'brief';
+    args: SubagentCommandArgs;
+    quoted: boolean;
+} | {
+    kind: 'error';
+    error: 'count' | 'conflict' | 'flag' | 'brief';
+    token?: string;
+};
+/**
+ * Session-level forced team mode: the state `/team` writes and `<forced_team_mode>`
+ * plus the status chip read (team-command-forced-dispatch §3.5 / §6.1).
+ *
+ * `null` MEANS "NOT ARMED" and is the constructor's value. It is never persisted
+ * (D-4): no `config.json` key, no session-file field, no checkpoint. A persisted
+ * "always fan out" would be inherited by `aragon exec` and by every launch after
+ * one experiment, at N children a turn - and the whole point of the bound in
+ * `dispatch-gate.ts` is that nobody may widen it by accident.
+ */
+export interface ForcedTeamState {
+    /** Children per turn. Already clamped to `[1, team.maxSubagents]`. */
+    count: number;
+}
+/**
+ * Parse the whole argument of `/team`. NEVER THROWS and never guesses.
+ *
+ * The empty argument is the STATUS question, not an error: "what is on?" is the
+ * one thing a user asks a mode command most often, and it must answer even in a
+ * session that cannot dispatch at all (that is exactly where they ask).
+ */
+export declare function readTeamIntent(raw: string): TeamIntent;
+/**
+ * How many children the ONE directive text must ask for, and why the count
+ * shrank. Every field is read by either the directive or the disclosure line.
+ */
+export interface ForcedPlan {
+    brief: string;
+    /** Already narrowed to `[1, team.maxSubagents]`. */
+    count: number;
+    /** What the request implied BEFORE `maxSubagents` narrowed it. */
+    requested: number;
+    /** Already narrowed to `maxSubagents`; may be empty. */
+    parts: string[];
+    /** Parts that survived the structural cap, before the policy cap applied. */
+    partsAdmitted: number;
+    /** Parts the user asked for, before the structural `forcedPartsMax` cap. */
+    partsRequested: number;
+    readOnly: boolean;
+}
+/**
+ * Narrow the parsed intent against the LIVE width.
+ *
+ * TWO CEILINGS, IN THIS ORDER (R-P1-3): the structural `forcedPartsMax` bounds
+ * what one argument may carry (the parser already applied it), and the policy
+ * `maxSubagents` bounds what this session may dispatch - which only this layer
+ * can apply, because only it can read the live config.
+ */
+export declare function planForced(args: SubagentCommandArgs, team: TeamConfig): ForcedPlan;
+/**
+ * The one line that says what the NEXT turn will do - a plan, not a result.
+ *
+ * IT IS PRINTED BEFORE THE TURN IS SUBMITTED and it never claims children
+ * started: forcing is instruction-level for the first turn, and a notice that
+ * said "4 subagents started" would be a promise the command cannot keep.
+ */
+export declare function planNotice(planned: ForcedPlan, team: TeamConfig): string;

package/dist/team/forced-mode.js

@@ -0,0 +1,156 @@
+/**
+ * Forced team mode: the SESSION STATE type and the PURE half of `/team`
+ * (team-command-forced-dispatch §3.3 / §3.5 / §5.2).
+ *
+ * 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.
+ *
+ * WHAT IS AND IS NOT HERE. Every export below is a deterministic function of its
+ * arguments: no `CommandContext`, no controller, no IO, no React. That is what
+ * lets the whole grammar - control words, the quote escape hatch, the two
+ * ceilings, the disclosure line - be tested without a terminal, a config file or
+ * a model. The command body (`commands/team-command.ts`) keeps the ctx-dependent
+ * half: speaking to the user, arming the session, submitting the turn.
+ *
+ * THE INTENT IS PARSED IN ONE STEP (§3.3), because the three rules interact:
+ *
+ *  1. CONTROL WORDS ARE WHOLE-ARGUMENT ONLY. `off the record` is a brief whose
+ *     first word happens to be `off`; treating it as "turn off, then take notes"
+ *     would delete a legitimate brief from the grammar.
+ *  2. THE QUOTE ESCAPE HATCH IS CHECKED BEFORE THE CONTROL WORDS. `/team "off"`
+ *     asks for a fan-out on the brief `off`. Without this rule the three control
+ *     words would be permanently unavailable as briefs, and a user working on a
+ *     feature called "off" would have no way to say so.
+ *  3. FLAG PARSING IS NOT REIMPLEMENTED. `parseSubagentArgs` owns the four error
+ *     classes and both disclosure ceilings, and its bytes are pinned by
+ *     `subagent-command.test.ts`; a second grammar here would drift from it on
+ *     the first `-n=6` someone tried.
+ */
+import { parseSubagentArgs } from './forced-dispatch.js';
+/**
+ * The default count when the user names none (D-7).
+ *
+ * FOUR, not `maxSubagents`: `<team_mode>` tells the model two to four is usually
+ * enough, so "force one dispatch" must not silently become the most expensive
+ * call the session can make. The status line advertises the real ceiling so the
+ * user who wants the widest fan-out knows which flag to add.
+ */
+export const DEFAULT_FORCED_COUNT = 4;
+/** The three words that command the session rather than describe work. */
+const CONTROL_WORDS = new Set(['on', 'off', 'status']);
+/**
+ * The argument with one pair of wrapping double quotes removed, or `null`.
+ *
+ * DELIBERATELY ONE PAIR AND NOT A LEXER. `/team "off"` and `/team "the off
+ * switch"` both work; nested or unbalanced quotes fall through to the ordinary
+ * parser, where the text simply keeps its quotes - the honest outcome for input
+ * the grammar does not claim.
+ */
+function unquoted(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length < 2)
+        return null;
+    if (!trimmed.startsWith('"') || !trimmed.endsWith('"'))
+        return null;
+    return trimmed.slice(1, -1);
+}
+/**
+ * Parse the whole argument of `/team`. NEVER THROWS and never guesses.
+ *
+ * The empty argument is the STATUS question, not an error: "what is on?" is the
+ * one thing a user asks a mode command most often, and it must answer even in a
+ * session that cannot dispatch at all (that is exactly where they ask).
+ */
+export function readTeamIntent(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return { kind: 'status' };
+    // RULE 2, FIRST: the escape hatch has to win, or the control words could never
+    // be briefs at all.
+    const inner = unquoted(trimmed);
+    if (inner !== null) {
+        const parsed = parseSubagentArgs(inner);
+        if (!parsed.ok)
+            return { kind: 'error', error: parsed.error, token: parsed.token };
+        return { kind: 'brief', args: parsed.args, quoted: true };
+    }
+    // RULE 1: whole-argument equality, compared case-insensitively.
+    const word = trimmed.toLowerCase();
+    if (CONTROL_WORDS.has(word))
+        return { kind: word };
+    // RULE 3: everything else is a brief, parsed by the one grammar there is.
+    const parsed = parseSubagentArgs(trimmed);
+    if (!parsed.ok)
+        return { kind: 'error', error: parsed.error, token: parsed.token };
+    return { kind: 'brief', args: parsed.args, quoted: false };
+}
+/**
+ * Narrow the parsed intent against the LIVE width.
+ *
+ * TWO CEILINGS, IN THIS ORDER (R-P1-3): the structural `forcedPartsMax` bounds
+ * what one argument may carry (the parser already applied it), and the policy
+ * `maxSubagents` bounds what this session may dispatch - which only this layer
+ * can apply, because only it can read the live config.
+ */
+export function planForced(args, team) {
+    const max = team.maxSubagents;
+    if (args.parts.length > 0) {
+        // A PARTS LIST STARTS WITH A CHILD PER SURVIVING PART, and `requested` is the
+        // number the user TYPED - not the structural 8 the parser already applied.
+        // Quoting the post-truncation count made the old notice tell a user who asked
+        // for eleven parts that they had asked for eight (R-4: the notice and the
+        // directive must both name the user's number).
+        const parts = args.parts.slice(0, max);
+        return {
+            brief: args.brief,
+            parts,
+            partsAdmitted: args.parts.length,
+            partsRequested: args.partsRequested,
+            requested: args.partsRequested,
+            count: parts.length,
+            readOnly: args.readOnly,
+        };
+    }
+    const requested = args.count ?? Math.min(DEFAULT_FORCED_COUNT, max);
+    return {
+        brief: args.brief,
+        parts: [],
+        partsAdmitted: 0,
+        partsRequested: 0,
+        requested,
+        count: Math.max(1, Math.min(requested, max)),
+        readOnly: args.readOnly,
+    };
+}
+/**
+ * The one line that says what the NEXT turn will do - a plan, not a result.
+ *
+ * IT IS PRINTED BEFORE THE TURN IS SUBMITTED and it never claims children
+ * started: forcing is instruction-level for the first turn, and a notice that
+ * said "4 subagents started" would be a promise the command cannot keep.
+ */
+export function planNotice(planned, team) {
+    const noun = planned.count === 1 ? 'subagent' : 'subagents';
+    const head = `Forcing a fan-out of ${planned.count} ${noun}`;
+    const followUp = `${head} (max ${team.maxSubagents}) - the next turn dispatches them. `
+        + 'Esc stops the turn.';
+    // TWO CEILINGS, TWO SENTENCES. `forcedPartsMax` bounds what one argument may
+    // carry and `team.maxSubagents` bounds what may be dispatched; naming the wrong
+    // one sends the user to change a number that is not the reason.
+    if (planned.parts.length > 0) {
+        if (planned.parts.length < planned.partsAdmitted) {
+            return `${head} (asked for ${planned.partsRequested} parts; `
+                + `team.maxSubagents is ${team.maxSubagents}).`;
+        }
+        if (planned.partsAdmitted < planned.partsRequested) {
+            return `${head} (asked for ${planned.partsRequested} parts, `
+                + `the first ${planned.parts.length} are used).`;
+        }
+        return followUp;
+    }
+    if (planned.requested > planned.count) {
+        return `${head} (asked for ${planned.requested}; `
+            + `team.maxSubagents is ${team.maxSubagents}).`;
+    }
+    return followUp;
+}

package/dist/team/forced-prompt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `<forced_team_mode>`: the SECOND of the three layers that make `/team <brief>`
+ * mean something (team-command-forced-dispatch §3.6 / §6.3).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A BLOCK AT ALL. The first layer - the directive `buildForcedDirective()`
+ * submits - is a single user turn, and it dies with that turn. The session stays
+ * in forced mode until `/team off`, so every LATER turn needs the same
+ * constraint, and the only surface that survives a turn is the system prompt.
+ *
+ * WHY NOT SIMPLY WIDEN `<team_mode>`. That block says "you CAN dispatch"; this
+ * one says "you MUST". Merging them would make the permission and the obligation
+ * one string, and a session that only needs the first (an ordinary team session)
+ * would start paying for the second's words and, worse, inheriting its tone.
+ *
+ * THE LAST PARAGRAPH IS A SAFETY VALVE AND MUST STAY LAST: "If the task tool is
+ * unavailable this turn, say so in one line" is what remains when all three
+ * layers fail, and it has to be the last sentence the model read. The plan-mode
+ * variant is therefore spliced BEFORE `Answer without dispatching`, never at the
+ * end (§6.3, P1-8).
+ */
+import { FORCED_TEAM_BLOCK_VERSION } from './limits.js';
+/**
+ * What one `<forced_team_mode>` rendering needs, and NOTHING ELSE.
+ *
+ * NO CEILING FIELD (§3.6 lists `maxSubagents`; §6.3 never spends it). The block
+ * names one number twice - the armed count - and `forced-prompt.test.ts` asserts
+ * that no ceiling appears in it: a sentence offering "up to 8" beside "Count: 4"
+ * is read as permission for eight, which is the cost D-7 caps at four. Carrying
+ * an unused ceiling here would invite exactly that sentence back.
+ */
+export interface ForcedTeamBlockParams {
+    /** Already narrowed to `[1, team.maxSubagents]` by `armForcedTeam()`. */
+    count: number;
+    /** Plan mode variant sentence: dispatch read-only research, then `submit_plan`. */
+    planMode: boolean;
+}
+/**
+ * Render the block for one prompt build.
+ *
+ * NO TRUNCATION PATH (unlike the team report): the text is a constant with two
+ * numbers in it, so its length is knowable at build time, and
+ * `forced-prompt.test.ts` asserts both the ASCII-only rule and the ceiling. A
+ * silent elision would delete the safety valve this block ends with.
+ */
+export declare function buildForcedTeamBlock(params: ForcedTeamBlockParams): string;
+export { FORCED_TEAM_BLOCK_VERSION };

package/dist/team/forced-prompt.js

@@ -0,0 +1,84 @@
+/**
+ * `<forced_team_mode>`: the SECOND of the three layers that make `/team <brief>`
+ * mean something (team-command-forced-dispatch §3.6 / §6.3).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A BLOCK AT ALL. The first layer - the directive `buildForcedDirective()`
+ * submits - is a single user turn, and it dies with that turn. The session stays
+ * in forced mode until `/team off`, so every LATER turn needs the same
+ * constraint, and the only surface that survives a turn is the system prompt.
+ *
+ * WHY NOT SIMPLY WIDEN `<team_mode>`. That block says "you CAN dispatch"; this
+ * one says "you MUST". Merging them would make the permission and the obligation
+ * one string, and a session that only needs the first (an ordinary team session)
+ * would start paying for the second's words and, worse, inheriting its tone.
+ *
+ * THE LAST PARAGRAPH IS A SAFETY VALVE AND MUST STAY LAST: "If the task tool is
+ * unavailable this turn, say so in one line" is what remains when all three
+ * layers fail, and it has to be the last sentence the model read. The plan-mode
+ * variant is therefore spliced BEFORE `Answer without dispatching`, never at the
+ * end (§6.3, P1-8).
+ */
+import { FORCED_TEAM_BLOCK_MAX_CHARS, FORCED_TEAM_BLOCK_VERSION, } from './limits.js';
+/** The plan-mode sentence, spliced before the "answer without dispatching" line. */
+const PLAN_SENTENCE = 'Plan mode is on: dispatch the read-only research '
+    + '(every spec readOnly: true), then call submit_plan.';
+/**
+ * The block's body, in the exact order and wording §6.3 fixes.
+ *
+ * `{count}` appears TWICE (the `Count:` line and the "more than N" clause) and
+ * both are the same number on purpose: a block that allowed "up to maxSubagents"
+ * in one sentence and "N" in the other would be read as authorising the wider
+ * number, which is exactly the cost D-7 caps at four.
+ */
+function body(count, planMode) {
+    const wide = [
+        `<forced_team_mode ${FORCED_TEAM_BLOCK_VERSION}>`,
+        'The user put this session in forced team mode. Work is done by subagents, not by you.',
+        'For every turn that produces or changes something, call the `task` tool ONCE and let',
+        'the children do it. Never do that work yourself, and never end such a turn having done',
+        'it alone: a turn that did the work itself is a failed turn here.',
+        `Count: ${count} subagents unless the work genuinely splits into fewer. `
+            + 'Two to four is usual;',
+        `more than ${count} only when the parts are truly independent. Each spec needs a `
+            + 'self-contained',
+        'prompt (the child has no memory of this conversation), a short slug label, a description',
+        'of at most 60 chars, and a disjoint set of files.',
+        'You may plan first: research with read_file / glob / grep, or write the plan with',
+        'todo_write. Planning is yours; executing the plan is theirs. Relay the combined report',
+        'in your own words and say which child did what.',
+    ];
+    // SPLICED HERE, BEFORE the closing sentence, for the reason the header records.
+    const plan = planMode ? [PLAN_SENTENCE] : [];
+    return [
+        ...wide,
+        ...plan,
+        'Answer without dispatching only when the turn is a question this conversation already',
+        'answers - no new files, no new commands, no new findings.',
+        'If the task tool is unavailable this turn, say so in one line instead of doing the work',
+        'alone.',
+        '</forced_team_mode>',
+    ];
+}
+/**
+ * Render the block for one prompt build.
+ *
+ * NO TRUNCATION PATH (unlike the team report): the text is a constant with two
+ * numbers in it, so its length is knowable at build time, and
+ * `forced-prompt.test.ts` asserts both the ASCII-only rule and the ceiling. A
+ * silent elision would delete the safety valve this block ends with.
+ */
+export function buildForcedTeamBlock(params) {
+    const count = Math.max(1, Math.floor(params.count));
+    const text = body(count, params.planMode).join('\n');
+    // A CEILING, NOT A CLIP. Every sentence in this block is load-bearing, so a
+    // length overrun is a wording bug to fix in the source rather than a paragraph
+    // to lose at run time - and this branch is unreachable today (1143 chars).
+    if (text.length > FORCED_TEAM_BLOCK_MAX_CHARS) {
+        throw new Error(`forced team block is ${text.length} chars, ceiling is `
+            + `${FORCED_TEAM_BLOCK_MAX_CHARS} (team/forced-prompt.ts)`);
+    }
+    return text;
+}
+export { FORCED_TEAM_BLOCK_VERSION };

package/dist/team/limits.d.ts

@@ -266,3 +266,43 @@ export declare const TEAM_SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
  * report can be tied to a block revision with one grep.
  */
 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

@@ -280,3 +280,51 @@ export const TEAM_SUBAGENT_TOOL_NAMES = new Set(['team_send', 'team_wait']);
  * report can be tied to a block revision with one grep.
  */
 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;