@aragon-agent/cli 0.6.39 → 0.6.42

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/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 };