@xingular/harness 1.4.0-unstable → 1.5.0-unstable

package/dist/sdk/sessions/goalStop.js

@@ -0,0 +1,41 @@
+// The goal part of a stop: a /goal that ended blocked, paused or at a limit leaves work for the
+// person, and its checkpoint's done/next comes from the reply's todo list. An ordinary reply has no
+// gate and settles as it ends (ADR-0075).
+import { MAX_CHECKPOINT_DONE } from "./contracts.js";
+/** The todo items a reply has not finished. */
+export function openItems(todo) {
+    return todo.filter((item) => item.status !== 'completed');
+}
+/**
+ * `goal` is the session's /goal, when it has one: a goal that ended blocked needs the person, and
+ * one that ended on a limit or a pause leaves work (ADR-0072).
+ */
+export function goalStopOutcome(todo, goal) {
+    const open = openItems(todo);
+    if (goal?.status === 'blocked')
+        return { code: 'needs_person', reason: goal.lastReason || 'The goal is blocked.', open };
+    if (goal && (goal.status === 'budget_limited' || goal.status === 'usage_limited' || goal.status === 'paused')) {
+        return { code: 'unfinished', reason: goal.lastReason || `The goal is ${goal.status.replace('_', ' ')}.`, open };
+    }
+    return null;
+}
+/** What a checkpoint learns from the reply's todo list and the goal. */
+export function handoffFields(todo, goal) {
+    const next = openItems(todo)[0]?.text || '';
+    const blocked = goal?.status === 'blocked' ? (goal.lastReason || 'The goal is blocked.').slice(0, 500) : '';
+    return {
+        done: todo.filter((item) => item.status === 'completed').slice(0, MAX_CHECKPOINT_DONE).map((item) => ({ item: item.text.slice(0, 300), evidence: [] })),
+        next: next.slice(0, 500),
+        ...(blocked ? { blocked } : {})
+    };
+}
+/** Why a checkpoint written for a stop outcome was written. */
+export const stopCheckpointReason = (outcome) => outcome.code === 'needs_person' ? 'requested' : 'stuck';
+/** The summary a stop outcome's checkpoint falls back to when the reply left no text. */
+export function stopSummary(outcome) {
+    if (outcome.code === 'needs_person')
+        return `The reply stopped for the person: ${outcome.reason}`.slice(0, 1_200);
+    if (outcome.reason)
+        return `The reply ended with work left: ${outcome.reason}`.slice(0, 1_200);
+    return `The reply ended with ${outcome.open.length} open todo item${outcome.open.length === 1 ? '' : 's'}.`;
+}

package/dist/sdk/sessions/runner.d.ts

@@ -8,7 +8,6 @@ import { type ContextUpdate } from "../prompt/compile.js";
 import type { ToolSpec } from "../tools/types.js";
 import { type SliceState } from "./workSlice.js";
 import type { GoalController } from "./goal.js";
-import { type StopGateState } from "./stopGate.js";
 import { type ExtensionHost } from "./extensionUi.js";
 import type { ActiveRun } from "./registry.js";
 export { EFFORTS };
@@ -86,8 +85,6 @@ export interface TurnParams {
         state: SliceState;
         maxToolCalls: number;
     };
-    /** The stop gate's view of this reply (ADR-0069): its todo list. */
-    stopGate?: StopGateState;
     /** The run's /goal (ADR-0072); the runner counts a claim check's model request with the run's usage. */
     goal?: {
         controller: GoalController;

package/dist/sdk/sessions/runner.js

@@ -10,7 +10,9 @@ import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from "../prompt/compile.js
 import { PLAN_REPAIR_CUSTOM_TYPE, PLAN_REPAIR_INSTRUCTIONS, finalizePlanOutcome } from "./planMode.js";
 import { MAX_CHECKPOINT_CHECKS, MAX_CHECKPOINT_FILES, MAX_CHECKPOINT_SUMMARY } from "./contracts.js";
 import { derivedReason } from "./workSlice.js";
-import { createStopGateState, handoffFields, stopCheckpointReason, stopOutcome, stopSummary } from "./stopGate.js";
+import { goalStopOutcome, handoffFields, stopCheckpointReason, stopSummary } from "./goalStop.js";
+import { TODO_WRITE } from "../tools/todo.js";
+import { validatedTodo } from "./compactionCheckpoint.js";
 import { toolAttachmentRefsSchema } from "./contracts.js";
 import { completedReasoningSummary, REASONING_SUMMARY_APIS, requestDetailedReasoningSummary } from "./reasoningSummaries.js";
 import { extensionUi } from "./extensionUi.js";
@@ -163,10 +165,10 @@ const lastLine = (text) => {
  * Files and checks come from the reply's tool calls, done and next from its todo list, and blocked
  * from a goal that ended blocked (ADR-0069, ADR-0072).
  */
-function derivedCheckpoint(ledger, slice, reason, fallback, gate, goal) {
+function derivedCheckpoint(ledger, slice, reason, fallback, goal) {
     return {
         summary: ledger.lastText.trim().slice(0, MAX_CHECKPOINT_SUMMARY) || fallback,
-        ...handoffFields(gate, goal),
+        ...handoffFields(ledger.todo, goal),
         files: [...ledger.files].slice(-MAX_CHECKPOINT_FILES).map(([path, why]) => ({ path: path.slice(0, 300), why: why.slice(0, 200) })),
         checks: ledger.checks.slice(-MAX_CHECKPOINT_CHECKS),
         decisions: [],
@@ -191,7 +193,7 @@ export async function runTurn(run, session, params) {
     let costReported = false;
     const toolStartedAt = new Map();
     const slice = params.slice?.state ?? null;
-    const ledger = { files: new Map(), checks: [], lastText: '' };
+    const ledger = { files: new Map(), checks: [], lastText: '', todo: [] };
     const bashCommands = new Map();
     const heartbeat = slice
         ? setInterval(() => {
@@ -416,6 +418,11 @@ export async function runTurn(run, session, params) {
                     if (typeof command === 'string')
                         bashCommands.set(tool.toolCallId, command);
                 }
+                if (tool.toolName === TODO_WRITE) {
+                    const items = validatedTodo(tool.args && typeof tool.args === 'object' ? tool.args.items : undefined);
+                    if (items)
+                        ledger.todo = items;
+                }
                 break;
             }
             case 'tool_execution_end': {
@@ -619,16 +626,16 @@ export async function runTurn(run, session, params) {
         }
         if (slice?.endedBy && !aborted && !lastError) {
             // The model stopped because its slice was over. The harness keeps the state for the next slice.
-            run.emit('checkpoint', derivedCheckpoint(ledger, slice.slice, derivedReason(slice.endedBy), `The reply stopped after ${slice.steps} steps at its work-slice boundary.`, params.stopGate, params.goal?.controller.get()));
+            run.emit('checkpoint', derivedCheckpoint(ledger, slice.slice, derivedReason(slice.endedBy), `The reply stopped after ${slice.steps} steps at its work-slice boundary.`, params.goal?.controller.get()));
             run.finish('interrupted', undefined, 'slice_complete', slice.endedBy === 'budget' ? 'slice_budget' : 'compaction_thrash');
             return;
         }
-        // A reply that ended with work left is not complete (ADR-0069, ADR-0072): open todo items, or a
-        // goal that was blocked, paused or ran into a limit. Either way the person can continue it.
+        // An ordinary reply settles as it ends (ADR-0075). Only a goal that was blocked, paused or ran
+        // into a limit stops it for the person, and then the checkpoint carries what is left.
         const goalState = params.goal?.controller.get() ?? null;
-        const stop = (params.stopGate || goalState) && !aborted && !lastError ? stopOutcome(params.stopGate ?? createStopGateState(), goalState) : null;
+        const stop = goalState && !aborted && !lastError ? goalStopOutcome(ledger.todo, goalState) : null;
         if (stop) {
-            run.emit('checkpoint', derivedCheckpoint(ledger, slice?.slice ?? 1, stopCheckpointReason(stop), stopSummary(stop), params.stopGate, goalState));
+            run.emit('checkpoint', derivedCheckpoint(ledger, slice?.slice ?? 1, stopCheckpointReason(stop), stopSummary(stop), goalState));
             run.finish('interrupted', undefined, stop.code, stop.code);
             return;
         }

package/dist/sdk/sessions/sessions.js

@@ -22,8 +22,7 @@ import { ASK_USER } from "../tools/askUser.js";
 import { defaultSkillPaths } from "../tools/defaultSkills.js";
 import { TODO_WRITE } from "../tools/todo.js";
 import { checkpointOf } from "./checkpoint.js";
-import { createStopGateState, sessionCheckModel, stopGate, stopGateNotice, STOP_GATE_EXTENSION } from "./stopGate.js";
-import { launchSwitchOff } from "./completionCheck.js";
+import { launchSwitchOff, sessionCheckModel } from "./completionCheck.js";
 import { GOAL_TOOLS, GoalController, GoalError, continuationPrompt, goalTools, provenanceText } from "./goal.js";
 import { GOAL_EXTENSION, goalLoop, goalNotice } from "./goalLoop.js";
 import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
@@ -64,24 +63,6 @@ function checkCommand(command, historyFile, input) {
     }
 }
 const CONTINUE_TEXT = 'Continue from where you stopped.';
-/** The person's request behind a chain of continuations: the first goal that is not the continue text. */
-function requestOfChain(root, runId) {
-    const seen = new Set();
-    for (let current = runId; current && !seen.has(current);) {
-        seen.add(current);
-        let record;
-        try {
-            record = loadRun(root, current);
-        }
-        catch {
-            return null;
-        }
-        if (record.goal && record.goal.trim() !== CONTINUE_TEXT)
-            return record.goal;
-        current = record.resumedFromRunId ?? null;
-    }
-    return null;
-}
 /** Fills a continuing run's input from the run it continues, refusing anything that would differ. */
 function continueInput(root, input) {
     const continuation = continuationOf(root, input.continueFrom, input.sessionDir);
@@ -557,6 +538,7 @@ export class Sessions {
             const own = [plan, resumed, profiles].filter((section) => section !== null);
             const effectiveLaunch = {
                 ...launch,
+                model: input.model ?? launch.model ?? null,
                 ...(sessionState ? { sessionState } : {}),
                 sections: own.length ? [...(launch.sections ?? []).filter((section) => !own.some((entry) => entry.id === section.id)), ...own] : launch.sections,
                 tools: capabilities.tools,
@@ -575,12 +557,9 @@ export class Sessions {
         const planResearchChild = input.plan === true && input.run.relation === 'subagent';
         const sliceEnabled = slicePolicy.enabled && (harnessStateTools || planResearchChild);
         const sliceState = createSliceState(slicePolicy, sliceOf(root, runId));
-        // The stop gate (ADR-0069) keeps an attended top-level reply working while its todo list has open
-        // items. Never for plan, command, automatic, subagent or other related runs.
-        const gateEnabled = harnessStateTools && !input.plan && !input.command && !input.automatic && !input.run.relation && !launchSwitchOff('XINGULAR_STOP_GATE');
-        // The completion check judges the person's request, not "Continue from where you stopped.".
-        const originalRequest = input.text.trim() === CONTINUE_TEXT ? requestOfChain(root, previousRun?.id ?? null) : null;
-        const stopGateState = gateEnabled ? createStopGateState(continuation?.todo) : null;
+        // The stop gate stays gone (ADR-0075): a reply the model ends settles as it ends, and the todo
+        // list is progress, not a gate. The goal loop below is the only layer that continues a reply.
+        // The completion check judges the goal's claim, not "Continue from where you stopped."
         // The goal: a continuation slice picks up the previous run's goal where it stopped.
         let goalController = null;
         if (goalWanted && input.goal) {
@@ -706,15 +685,7 @@ export class Sessions {
                     { name: COMPACTION_CHECKPOINT_EXTENSION, factory: compactionCheckpoint({ initialTodo: continuation?.todo, planInstructions: checkpointPlanInstructions }) },
                     ...(sliceEnabled ? [{ name: WORK_SLICE_EXTENSION, factory: workSliceGuard({ policy: slicePolicy, state: sliceState, onRefuse: (event, reason) => { if (typeof event.toolCallId === 'string')
                                     run.emit('tool.refused', { toolCallId: event.toolCallId, name: event.toolName, code: 'work_slice', reason: reason.slice(0, 2000) }); } }) }] : []),
-                    // Last, so delivered subagent results and plan repair continue first and the gate sees them.
-                    ...(stopGateState ? [{ name: STOP_GATE_EXTENSION, factory: stopGate({
-                                state: stopGateState,
-                                initialTodo: continuation?.todo,
-                                request: () => originalRequest,
-                                sliceEnded: () => sliceEnabled && sliceState.endedBy !== null,
-                                onEvent: (event) => run.emit('extension.notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: stopGateNotice(event) })
-                            }) }] : []),
-                    // After the todo gate: a goal continues a reply the gate let end (ADR-0072).
+                    // A goal continues a reply the model ended (ADR-0072).
                     ...(goalController ? [{ name: GOAL_EXTENSION, factory: goalLoop({
                                 controller: goalController,
                                 check: launchSwitchOff('XINGULAR_COMPLETION_CHECK') ? null : sessionCheckModel,
@@ -727,7 +698,6 @@ export class Sessions {
                 activatedPlugins: (ids) => updateRun(root, runId, (record) => { record.activatedPlugins = ids; }),
                 system,
                 ...(sliceEnabled ? { slice: { state: sliceState, maxToolCalls: slicePolicy.maxToolCalls } } : {}),
-                ...(stopGateState ? { stopGate: stopGateState } : {}),
                 ...(goalController ? { goal: goalHandle } : {}),
                 // A command sends no request of its own, so the context update waits for the next turn.
                 update: input.command ? null : update,

package/dist/sdk/sessions/workSlice.js

@@ -143,7 +143,7 @@ export function workSliceGuard(options) {
         return { block: true, terminate: true, reason };
     };
     return (pi) => {
-        // Pi emits agent_start again for every continuation (a stop-gate nudge, delivered subagent
+        // Pi emits agent_start again for every continuation (a slice continuation, delivered subagent
         // results, a plan repair), and those belong to the same reply and the same budget. Only a
         // person's message starts a new slice.
         pi.on('before_agent_start', (event) => {

package/dist/sdk/terminal/piExtension.js

@@ -12,11 +12,11 @@ import { SPAWN_SUBAGENT, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, sub
 import { PLAN_RESEARCH_TOOLS } from "../agents/planResearch.js";
 import { askUserTool } from "../tools/askUser.js";
 import { TODO_WRITE, todoTool } from "../tools/todo.js";
-import { createStopGateState, handoffFields, sessionCheckModel, stopCheckpointReason, stopGate, stopGateNotice, stopOutcome, stopSummary, STOP_GATE_EXTENSION } from "../sessions/stopGate.js";
-import { launchSwitchOff } from "../sessions/completionCheck.js";
+import { goalStopOutcome, handoffFields, stopCheckpointReason, stopSummary } from "../sessions/goalStop.js";
+import { launchSwitchOff, sessionCheckModel } from "../sessions/completionCheck.js";
 import { GOAL_STATE_ENTRY, GOAL_TOOLS, goalTools } from "../sessions/goal.js";
 import { GOAL_EXTENSION, goalLoop, goalNotice } from "../sessions/goalLoop.js";
-import { createSliceState, DEFAULT_SLICE_POLICY, parseWorkSlice, sliceContinuation, workSliceGuard } from "../sessions/workSlice.js";
+import { createSliceState, DEFAULT_SLICE_POLICY, parseWorkSlice, sliceContinuation, workSliceGuard, WORK_SLICE_EXTENSION } from "../sessions/workSlice.js";
 import { DEFAULT_COMMAND_TIMEOUT_SECONDS, withCommandBudget } from "../core/commandBudget.js";
 import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
 import { CAPABILITY_DISCOVERY, describeCapabilities } from "../tools/getCapabilities.js";
@@ -190,8 +190,6 @@ export default async function (pi, planRun, getSession, goal) {
     }
     const sliceState = createSliceState(slicePolicy);
     // `XINGULAR_WORK_SLICE=off` at launch leaves terminal replies unbounded, as before PROP-0041.
-    // One stop-gate state per terminal session; each reply resets it.
-    const gateState = createStopGateState();
     // A goal-claim check's model request counts with the reply's usage, like any other request.
     const recordCheckUsage = (raw) => {
         const message = raw;
@@ -490,21 +488,10 @@ export default async function (pi, planRun, getSession, goal) {
             continue: true
         };
     });
-    // The stop gate (ADR-0069), after subagent delivery and plan repair so it sees their
-    // continuations: a terminal reply that ends with open todo items is sent back up to its cap.
-    // Plan replies are not gated.
-    if (!launchSwitchOff('XINGULAR_STOP_GATE'))
-        stopGate({
-            state: gateState,
-            active: () => !planRun?.active,
-            sliceEnded: () => sliceState.endedBy !== null,
-            failed: () => Boolean(failure),
-            onEvent: (event) => {
-                void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: stopGateNotice(event) }).catch(() => undefined);
-            }
-        })(pi);
-    // A /goal (ADR-0072): while one is active, a reply that would end continues in place. After the
-    // stop gate, so open todo items are nudged first; its claim check is the only completion check.
+    // The stop gate is gone (ADR-0075): a reply the model ends settles as it ends, and the todo list
+    // is progress, not a gate. A /goal (ADR-0072) is the only layer that continues a reply: while one
+    // is active, a reply that would end continues in place; its claim check is the only completion
+    // check.
     if (goal) {
         for (const spec of goalTools(() => goal))
             pi.registerTool({
@@ -556,8 +543,8 @@ export default async function (pi, planRun, getSession, goal) {
             }
         })(pi);
     }
-    // After the stop gate, which stays silent at a slice boundary: a reply that did work and reached
-    // its budget continues as the next slice of the same run (ADR-0070).
+    // A reply that did work and reached its budget continues as the next slice of the same run
+    // (ADR-0070).
     if (slicePolicy.enabled)
         sliceContinuation({
             policy: slicePolicy,
@@ -566,11 +553,11 @@ export default async function (pi, planRun, getSession, goal) {
             failed: () => Boolean(failure),
             blocked: () => goal?.get()?.status === 'blocked',
             goalActive: () => goal?.active() === true,
-            todo: () => gateState.todo,
-            next: () => handoffFields(gateState, goal?.get() ?? null).next,
+            todo: () => lastTodo,
+            next: () => handoffFields(lastTodo, goal?.get() ?? null).next,
             onContinue: (ended) => {
-                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
-                void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: `Work slice ${ended.slice} reached ${ended.limit ?? 'its limit'}; continuing with slice ${ended.slice + 1} of up to ${slicePolicy.maxSlices}.` }).catch(() => undefined);
+                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: WORK_SLICE_EXTENSION, text: `Work slice ${ended.slice} reached ${ended.limit ?? 'its limit'}; continuing with slice ${ended.slice + 1} of up to ${slicePolicy.maxSlices}.` }).catch(() => undefined);
             }
         })(pi);
     // Reply text as it streams, batched, for a paired phone (remote control). The completed message
@@ -777,16 +764,16 @@ export default async function (pi, planRun, getSession, goal) {
         subagentParent = false;
         // A reply that stopped at its work-slice boundary is not a completed task: the record says so,
         // so a host can offer the continuation instead of treating it as done (PROP-0041).
-        // A reply that ended with open todo items is not completed either (ADR-0069): it stopped for the
-        // person, or the stop gate's nudges ran out. The harness writes its checkpoint from the todo list.
+        // An ordinary reply settles as it ends (ADR-0075); only a goal that was blocked, paused or hit
+        // a limit stops it for the person, and the checkpoint carries what is left.
         const aborted = event.aborted || messageAborted;
-        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? stopOutcome(gateState, goal?.get() ?? null) : null;
+        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? goalStopOutcome(lastTodo, goal?.get() ?? null) : null;
         if (stop) {
-            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
+            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
         }
         else if (sliceState.endedBy && !failure && !aborted) {
             // The guard ended the reply and promised the model the harness would keep its state.
-            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
+            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(lastTodo, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
         }
         const reason = sliceState.endedBy ? 'slice_complete' : stop?.code;
         const code = sliceState.endedBy === 'compaction-thrash' ? 'compaction_thrash' : sliceState.endedBy === 'budget' ? 'slice_budget' : stop?.code;

package/dist/sdk/terminal/terminals.js

@@ -1217,7 +1217,7 @@ export class Terminals {
             const launchSections = profiles ? [...(input.launch?.sections ?? []).filter((section) => section.id !== profiles.id), profiles] : input.launch?.sections;
             // A terminal is a person's own session: the same standard sections a host's session has.
             const standard = input.launch?.standard === null ? null : input.launch?.standard ?? { cwd: input.cwd };
-            const pack = compile(env, caller, { ...input.launch, standard, sections: launchSections, tools: launchTools }, variant && profiles ? { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) } : variant);
+            const pack = compile(env, caller, { ...input.launch, model: input.model ?? input.launch?.model ?? null, standard, sections: launchSections, tools: launchTools }, variant && profiles ? { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) } : variant);
             record(root, pack);
             mkdirSync(this.historyDir(input), { recursive: true });
             saveForSession(input.sessionFolder, pack);

package/dist/sdk/tools/askUser.js

@@ -19,7 +19,7 @@ export function askUserTool(run) {
         name: ASK_USER,
         label: 'Ask the user',
         description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 1–2 word label and aim to keep each question to 25 words or fewer. ' +
-            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision the request and the files do not answer, not for small talk and never to ask permission for work inside the request. If no answer arrives, continue with your best judgment instead of asking again or treating the turn as blocked.',
+            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision the request and the files do not answer, not for small talk and never to ask permission for work inside the request. If no answer arrives, continue with your best judgment instead of asking again or treating the turn as blocked. Never use it to ask for a login, a secret or a credential: give the exact command in the reply instead.',
         parameters: (Type) => Type.Object({
             questions: Type.Array(Type.Object({
                 summary: Type.String({ description: 'A concise label of one or two words' }),

package/dist/sdk/tools/todo.js

@@ -3,9 +3,10 @@
 import { todoItemSchema, MAX_TODO_ITEMS } from "../sessions/contracts.js";
 export const TODO_WRITE = 'todo_write';
 /** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
-export const TODO_GUIDANCE = 'If the work has several distinct steps or will take more than one tool call, call todo_write before your first other tool call with the steps you know so far, and keep the list current as steps start and finish. ' +
-    'The list shows the person your progress; it is not the scope of the work. The request, and any document it points to, is the scope: add steps as the work shows them, list the steps of a handoff or plan instead of folding them into one "remaining work" item, and never stop because the list is short or done. ' +
-    'Keep the list true at all times: mark a step completed only once it is done and checked, and never mark unfinished work completed. An open step is work to do in this reply, not something to report. Before you end the turn, compare the request, not the list, with what is done and checked, and do whatever is still yours to do. ' +
+export const TODO_GUIDANCE = 'If the work has several distinct steps, call todo_write before your first other tool call with the steps you know so far, and keep the list current as steps start and finish. ' +
+    'The list shows the person your progress; it is not the scope of the work. The request, and any document it points to, is the scope: add steps as the work shows them, and list the steps of a handoff or plan instead of folding them into one "remaining work" item. ' +
+    'Keep the list true: mark a step completed only once it is done and checked, and never mark unfinished work completed. Before you end the turn, compare the request, not the list, with what is done and checked; if a step stays open, say why in the reply. ' +
+    'When a login blocks a step, leave it open and give the exact command the person must run in the reply. ' +
     'The person follows your work from it, and a subagent’s todo list shows as its progress in the person’s list of subagents.';
 /** The event a run writes; `checklist.updated` is the pre-rename name, still read for old runs. */
 const TODO_EVENTS = new Set(['todo.updated', 'checklist.updated']);