@cspeach/cli 1.0.0 → 1.1.0

package/dist/tools/subagent/agent_run.js

@@ -28,6 +28,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { registerTool } from '../index.js';
+import { isPlanPhaseActive, notePlanPhaseSubagentDispatch, } from '../../commands/plan-gate.js';
 import { runTurn } from '../../agent/loop.js';
 import { collectTurnAssistantText } from '../../agent/turn-assistant-text.js';
 export const MAX_AGENT_DEPTH = 3;
@@ -98,12 +99,20 @@ export async function agentRunHandler(args, ctx) {
         // not parent's start time. Avoids surprising file timestamps.
         started_at: new Date().toISOString(),
         last_turn_at: new Date().toISOString(),
+        // Task 5 (ux-wave2): a fresh subagent has no task list — without this
+        // the spread above would leak the PARENT's todos into the child's
+        // session file.
+        todos: undefined,
     };
     // Build an isolated child ctx. Crucial differences vs parent ctx:
     //   - session: the fresh child session above (independent usage counters)
     //   - previewHook: undefined — subagent must NOT auto-approve writes
     //   - pendingDispatch / currentTransport: cleared — subagent doesn't
     //     mutate parent REPL state
+    //   - todoEmitter: omitted (Task 5) — todo_set emits via
+    //     ctx.todoEmitter?.emit, so a child's todo_set updates only
+    //     childSession.todos and never repaints the PARENT's Ctrl+T panel /
+    //     turn-status strip. Same seam as chunkEmitter suppression.
     // chunkEmitter is passed via the RunTurn params (not the ctx) as a
     // null-sink EventEmitter — see I2 fix below.
     const childCtx = {
@@ -113,7 +122,8 @@ export async function agentRunHandler(args, ctx) {
         cwd: ctx.cwd,
         provider: ctx.provider,
         skillSource: ctx.skillSource,
-        // previewHook + pendingDispatch + currentTransport intentionally omitted.
+        // previewHook + pendingDispatch + currentTransport + todoEmitter
+        // intentionally omitted.
     };
     // I2 fix: a null-sink EventEmitter suppresses all subagent output. Every
     // stdout-write site in loop.ts is guarded by `if (params.chunkEmitter)`,
@@ -128,9 +138,23 @@ export async function agentRunHandler(args, ctx) {
     // mutating tool from the subagent's tool list. Saves tokens on the
     // sub-agent invocation (smaller tools array = less input cost) AND
     // hard-prevents accidental writes from the subagent.
-    const toolFilter = args.read_only
+    //
+    // Task 7 (agentic-flow, 2026-07-03) — inside a plan phase the filter is
+    // FORCED regardless of args.read_only: subagents can read, never write,
+    // and the model cannot opt out (read_only:false is ignored). Outside plan
+    // phases the opt-in behaviour above is byte-identical to before.
+    const planPhase = isPlanPhaseActive();
+    const readOnly = planPhase || Boolean(args.read_only);
+    const toolFilter = readOnly
         ? (t) => !t.isMutating
         : undefined;
+    if (planPhase)
+        notePlanPhaseSubagentDispatch();
+    // Task 7 — per-dispatch announce on the PARENT's emitter (childCtx
+    // deliberately omits chunkEmitter, so this is the one line the user sees
+    // for each dispatch). 'info' renders dim in both the Ink and classic REPLs.
+    const taskPreview = args.task.length > 60 ? `${args.task.slice(0, 60)}…` : args.task;
+    ctx.chunkEmitter?.emit('info', `↳ subagent: ${args.skill}${readOnly ? ' — read-only' : ''} — ${taskPreview}`);
     try {
         await runTurn({
             provider: ctx.provider,
@@ -189,7 +213,7 @@ registerTool({
             },
             read_only: {
                 type: 'boolean',
-                description: 'When true, the subagent only sees read-only tools (no sap_set_source, no file-write, no shell_exec, etc.). Use this for research / analysis subagents that should not make changes — e.g. spawning a subagent to read code, run greps, or summarise findings. Smaller tools array = lower per-call cost; also a hard guard against accidental writes.',
+                description: 'When true, the subagent only sees read-only tools (no sap_set_source, no file-write, no shell_exec, etc.). Use this for research / analysis subagents that should not make changes — e.g. spawning a subagent to read code, run greps, or summarise findings. Smaller tools array = lower per-call cost; also a hard guard against accidental writes. NOTE: during plan phases the read-only filter is ALWAYS enforced regardless of this argument.',
             },
         },
         required: ['skill', 'task'],

package/dist/tools/todo.js

@@ -0,0 +1,144 @@
+/**
+ * todo_set — UX Wave 2 / Task 4. CC's TodoWrite adapted for CSPeach: the
+ * model maintains a visible task list on long multi-step jobs (RAP stacks,
+ * upgrade batches, plan phases). Task 5 renders it (Ctrl+T panel +
+ * turn-status strip) via todoEmitter; /compact appends it to the summary
+ * block so the plan survives compaction (commands/compact.ts).
+ *
+ * Semantics: FULL-LIST REPLACE on every call — never a delta. 1..20 items.
+ *
+ * Transcript render (CC-style, 2026-07): on every successful set the
+ * handler also emits the FULL checklist as a scrollback block via
+ * ctx.chunkEmitter (renderer/todo-block.ts). The raw ⏺/⎿ todo_set rows are
+ * widget-suppressed (renderer/tool-widget.ts) so the block is the sole
+ * visible representation — the transcript now shows the whole plan
+ * advancing, not a raw `⏺ todo_set({"todos":[…])` JSON line. This is the
+ * Claude-Code parity the owner asked for; the turn-status strip (single ▶
+ * row) and Ctrl+T panel stay exactly as they were.
+ *
+ * Session-write route (chosen with evidence, 2026-07-05): the tool mutates
+ * `ctx.session.todos` directly. ToolContext.session IS the live
+ * SessionState object (tools/index.ts) — the same instance repl.tsx /
+ * one-shot.ts construct the ctx from — and agent/loop.ts already calls
+ * saveSession(session) end-of-turn (and session/pending.ts saves per
+ * mutating-tool WAL entry), so no extra save call is needed here. The
+ * emitter-plus-repl-side-subscriber alternative was rejected: it would
+ * add a second writer for state the tool already owns, and headless /
+ * one-shot paths (no subscriber mounted) would silently lose persistence.
+ *
+ * Validation discipline: structured error results (is_error: true), never
+ * throws — caps at 20 items, rejects empty lists, empty text, unknown
+ * status. MULTIPLE in_progress items are a WARNING in the result, not an
+ * error: blocking the model mid-job over a presentation nit would stall
+ * long workflows, and the list is still coherent and renderable — the
+ * warning text steers the model to fix it on its next call instead.
+ *
+ * isMutating: false — writes CLI-side session state only, never SAP.
+ * Headless: identical behaviour (session write + emitter absent/no-op;
+ * no prompt involved).
+ *
+ * Emitter seam (Task 5, 2026-07-05): the panel channel arrives via
+ * `ctx.todoEmitter` — NOT a module-level import — mirroring how
+ * chunkEmitter is ctx-carried. agent_run's child ctx omits it, so a
+ * subagent's todo_set updates only the CHILD session and can never
+ * clobber the parent's Ctrl+T panel.
+ */
+import { registerTool } from './index.js';
+import { formatTodoChecklistBlock } from '../renderer/todo-block.js';
+/** Hard cap on list length — past this the list stops being a glanceable plan. */
+export const TODO_MAX_ITEMS = 20;
+const VALID_STATUSES = new Set(['pending', 'in_progress', 'completed']);
+function errorResult(message) {
+    return { content: `error: ${message}`, is_error: true };
+}
+export async function todoSetHandler(args, ctx) {
+    const raw = args?.todos;
+    if (!Array.isArray(raw)) {
+        return errorResult("todos must be an array of { text, status } items (status: 'pending' | 'in_progress' | 'completed').");
+    }
+    if (raw.length === 0) {
+        return errorResult('todos must contain at least 1 item — this is a full-list replace, never call it with an empty list.');
+    }
+    if (raw.length > TODO_MAX_ITEMS) {
+        return errorResult(`todos exceeds the ${TODO_MAX_ITEMS}-item cap (got ${raw.length}). Collapse completed work or group related steps into one item.`);
+    }
+    // Validate + normalise BEFORE touching session state — a rejected call
+    // must leave the previous list fully intact.
+    const todos = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        const text = typeof item?.text === 'string' ? item.text.trim() : '';
+        if (!text) {
+            return errorResult(`todos[${i}].text must be a non-empty string.`);
+        }
+        if (typeof item?.status !== 'string' || !VALID_STATUSES.has(item.status)) {
+            return errorResult(`todos[${i}].status must be one of 'pending' | 'in_progress' | 'completed' (got ${JSON.stringify(item?.status ?? null)}).`);
+        }
+        todos.push({ text, status: item.status });
+    }
+    const inProgress = todos.filter((t) => t.status === 'in_progress');
+    // Full-list replace on the LIVE session object — persisted by the loop's
+    // existing end-of-turn saveSession (see module doc for the evidence).
+    ctx.session.todos = todos;
+    // UI fan-out (Task 5) — via the ctx-carried emitter (absent on subagent
+    // ctxs → suppressed; absent listener → harmless no-op). Emit a defensive
+    // copy so a consumer mutating the payload can never corrupt the
+    // persisted session state.
+    ctx.todoEmitter?.emit('update', todos.map((t) => ({ ...t })));
+    // Transcript render (CC-style, 2026-07): drop the FULL checklist into
+    // scrollback on every successful set. The raw ⏺/⎿ todo_set rows are
+    // widget-suppressed (renderer/tool-widget.ts), so this block is the sole
+    // visible representation — mirroring ask_question. ctx.chunkEmitter routes
+    // to Ink Static scrollback AND the classic 'chunk'→stdout path
+    // (renderer/notices.ts). Subagent ctxs deliberately omit chunkEmitter
+    // (tools/subagent/agent_run.ts), so a child turn's todo_set can never
+    // print its checklist into the PARENT transcript — same seam as the
+    // todoEmitter suppression above.
+    ctx.chunkEmitter?.emit('chunk', formatTodoChecklistBlock(todos));
+    const result = {
+        count: todos.length,
+        in_progress: inProgress[0]?.text ?? null,
+    };
+    if (inProgress.length > 1) {
+        result.warning =
+            `${inProgress.length} items are in_progress — exactly one item should be in_progress at a time. ` +
+                'Mark the others pending or completed on your next todo_set call.';
+    }
+    return { content: JSON.stringify(result) };
+}
+registerTool({
+    name: 'todo_set',
+    // Model-behavior lever — this exact framing is binding (task-4 brief).
+    description: 'Maintain your task list for multi-step work. Call with the FULL updated list whenever you ' +
+        'complete a step, start a new one, or discover new work. Exactly one item should be ' +
+        'in_progress at a time. The user sees this list — keep items short and outcome-shaped.',
+    isMutating: false,
+    category: 'session',
+    input_schema: {
+        type: 'object',
+        properties: {
+            todos: {
+                type: 'array',
+                minItems: 1,
+                maxItems: TODO_MAX_ITEMS,
+                description: 'The full task list — replaces the previous list entirely.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        text: {
+                            type: 'string',
+                            description: 'Short, outcome-shaped item, e.g. "Activate ZCL_ORDER_API".',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed'],
+                        },
+                    },
+                    required: ['text', 'status'],
+                },
+            },
+        },
+        required: ['todos'],
+    },
+    handler: (args, ctx) => todoSetHandler(args, ctx),
+});