@aragon-agent/cli 0.6.40 → 0.6.43

package/dist/exec/runner.js

@@ -15,6 +15,7 @@
  * same `--session-id` must not race the writer of the file it is about to read.
  */
 import { formatStreamError } from '../agent/reducer.js';
+import { runDurationMs } from '../team/report.js';
 import { setSignalTerminator } from '../logging/install.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
 import { EXEC_SCHEMA_VERSION, buildRequestEndEvent } from './events.js';
@@ -1622,7 +1623,7 @@ export class ExecRunner {
                 label: run.label,
                 phase: run.phase,
                 description: run.description,
-                durationMs: Math.max(0, (run.endedAt ?? 0) - (run.startedAt ?? 0)),
+                durationMs: runDurationMs(run),
                 toolCalls: run.toolCalls,
             });
             return;

package/dist/team/bus.d.ts

@@ -36,6 +36,10 @@ export type SendVerdict = {
     ok: false;
     reason: 'unknown_recipient';
     recipients: string[];
+} | {
+    ok: false;
+    reason: 'recipient_finished';
+    who: string[];
 } | {
     ok: false;
     reason: 'agent_quota';

package/dist/team/bus.js

@@ -103,10 +103,20 @@ export class TeamBus {
     send(from, to, subjectRaw, bodyRaw) {
         const target = to.trim().toLowerCase();
         const cost = target === ALL_KEY ? TEAM_LIMITS.broadcastCost : 1;
-        const recipients = this.resolveRecipients(from, target);
-        if (recipients.length === 0) {
+        const addressed = this.resolveRecipients(from, target);
+        if (addressed.length === 0) {
             return { ok: false, reason: 'unknown_recipient', recipients: this.participants() };
         }
+        // A finished peer has no loop left to drain its mailbox, so "Delivered" would be
+        // a false receipt and the quota spent on it a pure loss. Same fact `checkWaitable`
+        // already honours. The lead is always addressable: its mail is collected for the
+        // report, not read by a loop. Refused like every other refusal: nothing is spent
+        // and `lastSentAt` does not move. A peer that is about to finish but has not yet is
+        // still delivered to; that window cannot be closed without a lock.
+        const recipients = addressed.filter((r) => r === LEAD_KEY || this.canSend(r));
+        if (recipients.length === 0) {
+            return { ok: false, reason: 'recipient_finished', who: addressed };
+        }
         const used = this.sentCount(from);
         if (used + cost > TEAM_LIMITS.messagesPerAgent) {
             return { ok: false, reason: 'agent_quota', used, max: TEAM_LIMITS.messagesPerAgent };

package/dist/team/comm-tools.js

@@ -64,6 +64,9 @@ export function makeTeamSend(bus, selfKey) {
                 case 'unknown_recipient':
                     return textResult(`Not sent: no subagent labelled "${to.trim()}". Teammates: ` +
                         `${verdict.recipients.filter((r) => r !== selfKey).join(', ')}.`);
+                case 'recipient_finished':
+                    return textResult(`Not sent: ${verdict.who.join(', ')} already finished and will not read it. ` +
+                        'Put what matters in your own final summary instead.');
                 case 'agent_quota':
                     return textResult(`Not sent: message quota spent (${verdict.used}/${verdict.max}). Finish your work ` +
                         'and put it in your final summary.');

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