copilot-operator 0.1.41 → 0.1.42

package/dist/src/api/operator.controller.js

@@ -69,12 +69,14 @@ function startsFrom(raw) {
         const x = c;
         const branch = typeof x.branch === 'string' ? x.branch : '';
         const onBranch = x.onBranch === true ? { onBranch: true } : {};
+        // Another start for a session that has run: see `StartChoice.rechoose`.
+        const rechoose = x.rechoose === true ? { rechoose: true } : {};
         if (x.from === 'previous-session')
-            out[id] = { from: 'previous-session' };
+            out[id] = { from: 'previous-session', ...rechoose };
         else if (x.from === 'local' && branch)
-            out[id] = { from: 'local', branch, ...onBranch };
+            out[id] = { from: 'local', branch, ...onBranch, ...rechoose };
         else if (x.from === 'remote' && branch && typeof x.remote === 'string' && x.remote)
-            out[id] = { from: 'remote', remote: x.remote, branch, ...onBranch };
+            out[id] = { from: 'remote', remote: x.remote, branch, ...onBranch, ...rechoose };
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
@@ -187,8 +189,10 @@ let OperatorController = class OperatorController {
      * already ran keeps the text it ran with, and the next one uses the new text.
      */
     /** A task that stopped at the runner's limit carries on in its own conversation and branch. */
-    continueTask(id, taskId) {
-        return this.ops.continueTask(id, taskId).catch(fail);
+    continueTask(id, taskId, body = {}) {
+        // The operator's new prompt, when one is given: see `TaskContinuation.instruction`.
+        const instruction = typeof body?.instruction === 'string' ? body.instruction : undefined;
+        return this.ops.continueTask(id, taskId, instruction).catch(fail);
     }
     rerunTask(id, taskId, body) {
         const { buildOnFinished, ...patch } = body ?? {};
@@ -537,6 +541,15 @@ let OperatorController = class OperatorController {
         }
         return this.ops.decide(id, body.action);
     }
+    /** A plan waiting for approval (plan mode): approve it, with a note or not; ask for another; or stop the task. */
+    decidePlan(id, body) {
+        if (!['approve', 'revise', 'stop'].includes(body?.action ?? ''))
+            throw new BadRequestException('action must be approve, revise or stop');
+        const result = this.ops.decidePlan(id, body.action, typeof body?.note === 'string' ? body.note : undefined);
+        if (!result.ok)
+            throw new BadRequestException(result.problem);
+        return result;
+    }
     /** Turns asking on or off in the middle of a run. */
     setMode(id, body) {
         if (body?.mode !== 'confirm' && body?.mode !== 'unattended') {
@@ -798,8 +811,9 @@ __decorate([
     Post('sessions/:id/tasks/:taskId/continue'),
     __param(0, Param('id')),
     __param(1, Param('taskId')),
+    __param(2, Body()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:paramtypes", [String, String, Object]),
     __metadata("design:returntype", Promise)
 ], OperatorController.prototype, "continueTask", null);
 __decorate([
@@ -1140,6 +1154,14 @@ __decorate([
     __metadata("design:paramtypes", [String, Object]),
     __metadata("design:returntype", Object)
 ], OperatorController.prototype, "decide", null);
+__decorate([
+    Post('approvals/:id/plan'),
+    __param(0, Param('id')),
+    __param(1, Body()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Object)
+], OperatorController.prototype, "decidePlan", null);
 __decorate([
     Post('sessions/:id/mode'),
     __param(0, Param('id')),

package/dist/src/api/operator.service.js

@@ -20,7 +20,7 @@ import { join, resolve } from 'node:path';
 import { installLayout } from '../config/layout.js';
 import { SessionStore, DEFAULT_VCS, DEFAULT_REVIEW, applyDefaultProject, applyTaskPatch } from '../session/store.js';
 import { EventBus } from '../session/events.js';
-import { freshRetriesOfLatestRun, isContinuable, newId } from '../session/model.js';
+import { freshRetriesOfLatestRun, isContinuable, MAX_INSTRUCTION_CHARS, newId } from '../session/model.js';
 import { runSession, openBrowser, queuedToRun } from '../orchestrator/taskRunner.js';
 import { buildExport } from '../session/exportRecord.js';
 import { buildDebugExport } from '../session/debugExport.js';
@@ -436,6 +436,12 @@ let OperatorService = class OperatorService {
             }
             if (patch.projectDir !== undefined)
                 s.projectDir = patch.projectDir.trim();
+            if (patch.planMode !== undefined) {
+                if (patch.planMode === 'off' || patch.planMode === 'auto' || patch.planMode === 'approve')
+                    s.planMode = patch.planMode;
+                else
+                    delete s.planMode;
+            }
             if (patch.vcs) {
                 const merged = { ...DEFAULT_VCS, ...s.vcs, ...patch.vcs };
                 // A prefix is what makes the bot's branches recognisable in `git branch`, so an empty
@@ -574,7 +580,12 @@ let OperatorService = class OperatorService {
      * the old attempt's summary sitting under a question that was never asked.
      */
     /** "Continue" on a task that stopped before it finished — a limit from the settings, the bot stopping, the operator: same chat, same branch, fresh count. */
-    async continueTask(sessionId, taskId) {
+    async continueTask(sessionId, taskId, 
+    /**
+     * The operator's new prompt: what carries a task that failed on from where it got to, in its chat and
+     * on its branch (2026-10-13); optional with any other Continue. See `TaskContinuation.instruction`.
+     */
+    instruction) {
         await this.init();
         /*
          * An attempt the operator stopped: which of its last steps ran, and what they printed, read from its
@@ -584,15 +595,21 @@ let OperatorService = class OperatorService {
         const before = (await this.store.getSession(sessionId))?.tasks.find((t) => t.id === taskId);
         const cfg = await this.settings.load();
         const stoppedAt = before?.status === 'aborted' && !before.interruption && before.runId ? await readInterruption(join(cfg.resolved.runsDir, before.runId)).catch(() => null) : null;
-        const task = await this.store.continueTask(sessionId, taskId, stoppedAt);
-        await appendSessionLog(cfg.resolved.runsDir, sessionId, { type: 'continue', message: `"${task.title}" queued to continue as attempt ${task.attempt ?? 1}`, data: { taskId, attempt: task.attempt } }).catch(() => undefined);
+        const task = await this.store.continueTask(sessionId, taskId, stoppedAt, instruction);
+        const after = task.continuing?.how === 'failed' ? ` after it ended ${task.continuing.ended?.status ?? 'failed'}` : '';
+        const withPrompt = task.continuing?.instruction ? ', with a new prompt' : '';
+        await appendSessionLog(cfg.resolved.runsDir, sessionId, {
+            type: 'continue',
+            message: `"${task.title}" queued to continue as attempt ${task.attempt ?? 1}${after}${withPrompt}`,
+            data: { taskId, attempt: task.attempt, ...(task.continuing?.instruction ? { instruction: task.continuing.instruction } : {}) },
+        }).catch(() => undefined);
         this.bus.publish({
             sessionId,
             taskId,
             type: 'task-requeued',
             level: 'info',
-            message: `"${task.title}" is queued to continue where it stopped (attempt ${task.attempt ?? 1})`,
-            data: { attempt: task.attempt, continuing: true },
+            message: `"${task.title}" is queued to continue where it ${after ? 'ended' : 'stopped'}${after}${withPrompt} (attempt ${task.attempt ?? 1})`,
+            data: { attempt: task.attempt, continuing: true, ...(task.continuing?.instruction ? { instruction: true } : {}) },
         });
         return task;
     }
@@ -1130,8 +1147,16 @@ let OperatorService = class OperatorService {
                     x.vcsBaseCommit = undefined;
                     x.vcsStart = undefined;
                 }
+                // Chosen again after the session ran: a re-run starts from it too, and a per-session line goes on under a new name.
+                if (applied.restart) {
+                    x.startRechosenAt = new Date().toISOString();
+                    if (applied.restart.freshBranch) {
+                        x.vcs.branchName = applied.restart.freshBranch;
+                        x.vcs.branchNameExact = true;
+                    }
+                }
             });
-            const message = `${applied.said}${applied.note ? `; ${applied.note}` : ''}${applied.clearStart ? '; the start prepared before (a starting snapshot) no longer applies' : ''}`;
+            const message = `${applied.said}${applied.note ? `; ${applied.note}` : ''}${applied.clearStart && !applied.restart ? '; the start prepared before (a starting snapshot) no longer applies' : ''}`;
             entries.push({ at: new Date().toISOString(), type: 'start-chosen', message, data: { session: id, choice: starts[id], ...(applied.note ? { note: applied.note } : {}) } });
             this.bus.publish({ sessionId: id, type: 'start-chosen', level: 'info', message, data: { runId, choice: starts[id] } });
             await appendSessionLog(cfg.resolved.runsDir, id, { type: 'start-chosen', message, data: { runId, choice: starts[id] } }).catch(() => undefined);
@@ -1323,6 +1348,8 @@ let OperatorService = class OperatorService {
                     await this.store.saveModels({ options, current: current ?? undefined, readAt: new Date().toISOString() });
                 },
             },
+            // Plan mode `approve`: the plan is put to the operator on the approvals card.
+            approvePlan: (ask) => this.askPlanApproval(ask, controller.signal),
         })
             .then(async (outcome) => {
             const tally = { ...(await this.tally(sessionId, queuedIds)), paused: outcome.paused, ...(outcome.refused ? { refused: outcome.refused } : {}) };
@@ -2196,6 +2223,54 @@ let OperatorService = class OperatorService {
                 message: `choose "${ask.asked}" in the Copilot window, then answer on the card`, data: { approvalId: approval.id, model: approval.model } });
         });
     }
+    /**
+     * A task's plan, put to the operator (plan mode `approve`, in a run that asks before each command): it
+     * waits on the approvals card, on every page, until it is approved, sent back for another, or the task
+     * is stopped. See `PlanMode`.
+     */
+    askPlanApproval(ask, signal) {
+        return new Promise((resolveAnswer) => {
+            if (signal.aborted) {
+                resolveAnswer({ decision: 'stop' });
+                return;
+            }
+            const approval = {
+                id: newId('a-'),
+                sessionId: ask.sessionId,
+                taskId: ask.taskId,
+                stepId: 0,
+                description: `The plan of "${ask.title}" (version ${ask.plan.version})`,
+                createdAt: new Date().toISOString(),
+                plan: { title: ask.title, plan: ask.plan },
+            };
+            this.waiting.set(approval.id, {
+                approval,
+                resolve: (d) => resolveAnswer(d.action === 'run' ? { decision: 'approve' } : { decision: 'stop' }),
+                resolvePlan: resolveAnswer,
+            });
+            this.bus.publish({ sessionId: ask.sessionId, taskId: ask.taskId, type: 'approval-requested', level: 'warn',
+                message: `the plan of "${ask.title}" (version ${ask.plan.version}) is waiting for you to approve it`, data: { approvalId: approval.id, plan: true } });
+        });
+    }
+    /**
+     * Answers a plan waiting for approval: approve it (with a note the chat is given beside it), ask for
+     * another (saying what to change), or stop the task.
+     */
+    decidePlan(approvalId, action, note) {
+        const w = this.waiting.get(approvalId);
+        if (!w || !w.resolvePlan)
+            return { ok: false, problem: 'That plan is not waiting any more.' };
+        const text = (note ?? '').trim();
+        if (action === 'revise' && !text)
+            return { ok: false, problem: 'Say what to change in the plan, so the chat knows what the next one must do differently.' };
+        if (text.length > MAX_INSTRUCTION_CHARS)
+            return { ok: false, problem: `The note is ${text.length} characters; it can be at most ${MAX_INSTRUCTION_CHARS}.` };
+        this.waiting.delete(approvalId);
+        w.resolvePlan({ decision: action, ...(text ? { note: text } : {}) });
+        this.bus.publish({ sessionId: w.approval.sessionId, taskId: w.approval.taskId, type: 'approval-decided', level: 'info',
+            message: `plan: ${action}${text ? ' (with a note)' : ''}`, data: { approvalId, action, plan: true } });
+        return { ok: true };
+    }
     pendingApprovals(sessionId) {
         return [...this.waiting.values()].map((w) => w.approval).filter((a) => !sessionId || a.sessionId === sessionId);
     }

package/dist/src/config/schema.js

@@ -149,6 +149,13 @@ export const RunConfigSchema = z.object({
          * there, a fetch included, is put in front of a person anyway.
          */
         networkFetch: z.enum(['ask', 'refuse', 'run']).default('ask'),
+        /**
+         * Plan mode, for every session that does not set its own (see `PlanMode` in session/model.ts): a
+         * task's chat first looks at the project read-only and replies with a plan, and the work begins once
+         * the plan is approved — by the runner (`auto`), or by the operator (`approve`, in a run that asks
+         * before each command; a run without asking approves it itself). Off by default: it costs messages.
+         */
+        planMode: z.enum(['off', 'auto', 'approve']).default('off'),
         /**
          * The shell a step or a check runs in when it names none of its own.
          *

package/dist/src/orchestrator/planMode.js

@@ -0,0 +1,102 @@
+/** Planning rounds after which the chat is reminded that a plan is what ends the phase. */
+export const PLAN_NUDGE_AFTER = 12;
+/** What the opening message says about the phase, for a task in plan mode. */
+export function planModeNote(mode, enforced, asks) {
+    return [
+        '## Plan first (plan mode)',
+        '',
+        'Before you change anything in this task, look at the project and make a plan. In this phase you only',
+        'read: list the folders, open the files the task touches, read the git log, search for what the task',
+        'names — find what is already implemented, what is missing and what a change would affect.',
+        enforced
+            ? 'Change nothing yet: the runner puts back any change made in this phase, and tells you.'
+            : 'Change nothing yet: nothing in this phase may change a file.',
+        'When you have seen enough, reply with status "plan" and no steps:',
+        '',
+        '```json',
+        '{"status": "plan", "notes": "…", "plan": {"existing": "what is already there that the task touches: files, functions, behaviour", "approach": "how you will do it", "steps": ["first stage", "second stage"], "files": ["the files you will create or change"], "verification": "how you will show the result works", "risks": "risks and open questions"}}',
+        '```',
+        '',
+        mode === 'approve' && asks
+            ? 'The operator reads the plan, and approves it or asks for another with what to change.'
+            : 'The runner approves the plan and tells you so.',
+        'Begin the work only once you are told the plan is approved. Then carry it out; when it has to change,',
+        'say so in `notes` and why. The independent review checks the work against the approved plan.',
+    ].join('\n');
+}
+/** The plan as the chat gave it, recorded. */
+export function planFrom(reply, version, revisions = []) {
+    return {
+        existing: reply.existing.trim(),
+        approach: reply.approach.trim(),
+        steps: reply.steps.map((x) => x.trim()).filter(Boolean),
+        files: reply.files.map((x) => x.trim()).filter(Boolean),
+        verification: reply.verification.trim(),
+        ...(reply.risks?.trim() ? { risks: reply.risks.trim() } : {}),
+        version,
+        at: new Date().toISOString(),
+        ...(revisions.length > 0 ? { revisions } : {}),
+    };
+}
+/** The plan in words: for the record, the reviewer and the approval card's plain-text form. */
+export function describePlan(plan) {
+    return [
+        `What is already there: ${plan.existing}`,
+        `Approach: ${plan.approach}`,
+        'Stages:',
+        ...plan.steps.map((x, i) => `${i + 1}. ${x}`),
+        ...(plan.files.length > 0 ? [`Files it will create or change: ${plan.files.join(', ')}`] : []),
+        `Verification: ${plan.verification}`,
+        ...(plan.risks ? [`Risks and open questions: ${plan.risks}`] : []),
+    ].join('\n');
+}
+/** Approved: the work begins. */
+export function planApprovedMessage(approval) {
+    const by = approval.by === 'operator'
+        ? 'The operator approved your plan.'
+        : `Your plan is approved by the runner${approval.why ? ` (${approval.why})` : ''}.`;
+    return [
+        by,
+        ...(approval.note?.trim() ? ['', 'With this from the operator, which wins where it and the plan disagree:', '', approval.note.trim()] : []),
+        '',
+        'Carry it out now: reply with status "continue" and the steps of its first stage. Keep to the plan; when it',
+        'has to change, say so in `notes` and why — a change the plan did not foresee is declared, not hidden.',
+        'Verify the result as the plan says before you report done. Step numbering restarts at 1.',
+    ].join('\n');
+}
+/** The operator asked for another plan. */
+export function planReviseMessage(comment, version) {
+    return [
+        `The operator read version ${version} of your plan and asks for another. What to change:`,
+        '',
+        comment.trim(),
+        '',
+        'You are still in the planning phase: change nothing. Look at what you need to, then reply with status',
+        '"plan" and the whole revised plan — not only what changed.',
+    ].join('\n');
+}
+/** A plan sent when none is asked for: the phase is over, or the session is not in plan mode. */
+export const PLAN_NOT_NOW = 'No plan is asked for now: the planning phase is over and the plan stands. Carry on with the work — reply with status ' +
+    '"continue" and steps, or end the task. When the plan has to change, say so in `notes` and why.';
+/** "done" in the planning phase: nothing has been done yet. */
+export const PLAN_FIRST = 'Not yet: this task is in the planning phase, and nothing has been changed. Reply with status "plan" and the plan; ' +
+    'the work begins once it is approved.';
+/** Said after many planning rounds. */
+export function planNudge(rounds) {
+    return `You have read the project for ${rounds} rounds in the planning phase. Send the plan now, with status "plan"; what you have not looked at yet can go under "risks".`;
+}
+/** The plan section of the reviewer's brief. */
+export function planForReviewer(plan) {
+    return [
+        '## The plan the work was to follow',
+        '',
+        `The implementer made this plan before it changed anything, and it was approved${plan.approved?.by === 'operator' ? ' by the operator' : ''}.`,
+        'Check that the work follows it: a stage left out, a file changed that the plan does not name, or another',
+        'approach — none of them declared in the implementer\'s notes or deviations with a reason — is a finding',
+        'with "about": "work". A departure the implementer declared and justified is not a fault in itself; judge',
+        'whether the reason holds. The work is still judged against the task as written first.',
+        ...(plan.approved?.note ? ['', `The operator added: ${plan.approved.note}`] : []),
+        '',
+        describePlan(plan),
+    ].join('\n');
+}

package/dist/src/orchestrator/review.js

@@ -31,6 +31,7 @@ import { writeReport } from '../exec/reportFile.js';
 import { mergeRedactions } from '../exec/redaction.js';
 import { trackedRepoOf } from '../vcs/taskVcs.js';
 import { buildCoveringMessage, assertSendable } from '../protocol/reporter.js';
+import { planForReviewer } from './planMode.js';
 import { inScope } from '../vcs/scope.js';
 /** The sentence both sides get when a review left something listening. */
 function leftoverNote(leftovers) {
@@ -52,7 +53,9 @@ export function deliverableFor(task, summary, tracked, changedFiles) {
         return { summary: text, why: 'no-files-changed' };
     return undefined;
 }
-export function reviewBrief(session, task, changedFiles, cwd, deviations = [], previous, disputes = [], derivedFailing = [], earlier = [], deliverable) {
+export function reviewBrief(session, task, changedFiles, cwd, deviations = [], previous, disputes = [], derivedFailing = [], earlier = [], deliverable, 
+/** The approved plan, in plan mode: see `planForReviewer`. */
+plan) {
     // The same repository the runner branched and read the changed files from, however it is named.
     const repo = trackedRepoOf(session);
     // Each file marked against the task's scope, and the scope said: the reviewer was shown side effects as
@@ -75,6 +78,7 @@ export function reviewBrief(session, task, changedFiles, cwd, deviations = [], p
         '## The project instructions that applied',
         '',
         task.level2.trim() || '(none)',
+        ...(plan ? ['', planForReviewer(plan)] : []),
         ...(earlier.length > 0
             ? [
                 '',
@@ -257,14 +261,14 @@ export async function runReview(transport, session, task, deps) {
         // The machine's shells, when they are not what the contract's example assumes — the same note
         // the implementer's conversation opens with, for a conversation working to the same example.
         const machineNote = shellNote(undefined, defaultShell);
-        let before = await transport.sendAndConfirm(machineNote ? `${contract}
-
+        let before = await transport.sendAndConfirm(machineNote ? `${contract}
+
 ${machineNote}` : contract);
         await transport.waitForReply(before);
         await pacer.throttleSend();
         // The brief is saved as sent. Until it was, whether a later round had been told what the
         // earlier one found could not be checked from the run folder at all.
-        const brief = reviewBrief(session, task, deps.changedFiles, deps.cwd, deps.deviations, deps.previous, deps.disputes, deps.derivedFailing, deps.earlier, deps.deliverable);
+        const brief = reviewBrief(session, task, deps.changedFiles, deps.cwd, deps.deviations, deps.previous, deps.disputes, deps.derivedFailing, deps.earlier, deps.deliverable, deps.plan);
         await saveReply('00-brief', brief);
         await deps.record(`REVIEW ${round} BRIEF`, brief);
         before = await transport.sendAndConfirm(brief);

package/dist/src/orchestrator/taskRunner.js

@@ -42,6 +42,7 @@ import { RunLog } from '../log/runLog.js';
 import { composeOpening, readOnlyNote } from '../session/compose.js';
 import { MIN_TRIED_APPROACHES } from '../protocol/replySchema.js';
 import { enforceScope, scopeMessage, scopeNote } from '../vcs/scope.js';
+import { PLAN_FIRST, PLAN_NOT_NOW, PLAN_NUDGE_AFTER, describePlan, planApprovedMessage, planFrom, planModeNote, planNudge, planReviseMessage } from './planMode.js';
 import { composeHandoff } from '../session/handoff.js';
 import { ProgressWatch } from './progress.js';
 import { contractConflicts, readsTreeClean } from './contract.js';
@@ -650,6 +651,14 @@ async function withOperatorHand(transport, wanted, first, hooks, sessionId, bus,
     return { result, goOnAsItIs: false };
 }
 /** Runs one task to completion inside an already-open transport. */
+/** The approved plan a task works to: its own attempt's, else, for a continuation, the latest one before it. */
+function approvedPlanOf(task) {
+    if (task.plan?.approved)
+        return task.plan;
+    if (!task.continuing)
+        return undefined;
+    return [...(task.attempts ?? [])].reverse().find((a) => a.plan?.approved)?.plan;
+}
 export async function runTask(transport, session, task, deps) {
     const { cfg, store, bus, authorizer, signal } = deps;
     // Every attempt gets its own folder. The first keeps the original name, so nothing that
@@ -1256,6 +1265,23 @@ export async function runTask(transport, session, task, deps) {
         const scopeEnforced = (scope.length > 0 || !!task.readOnly) && onOwnBranch;
         if (scopeEnforced)
             enforcement = { scope, readOnly: !!task.readOnly };
+        /*
+         * Plan mode (2026-10-13): the session's own, else Settings. A continuation carries on under the plan
+         * its attempt already has — it is in the conversation — so only a task that starts anew plans; a new
+         * prompt on finished work is a new instruction, and plans. The planning phase is read-only, enforced
+         * the way a read-only task is wherever the task has a branch of its own.
+         */
+        const planMode = session.planMode ?? cfg.execution.planMode ?? 'off';
+        let planning = planMode !== 'off' && !task.continuing;
+        const planEnforced = planning && onOwnBranch;
+        let planVersion = 0;
+        let planningRounds = 0;
+        const planRevisions = [];
+        /*
+         * The approved plan the work follows, for the reviewer: one approved in this attempt, or the earlier
+         * attempt's for a task carried on. Kept here, because `task` is the record as it was when the attempt began.
+         */
+        let planInForce = approvedPlanOf(task);
         if (watchesTree)
             startState = await treeState(repoDirOf(session));
         // The operator's input files, read-only on a branch of the task's own; see `vcs/inputs.ts`.
@@ -1384,6 +1410,8 @@ export async function runTask(transport, session, task, deps) {
             contractAlreadySent: session.contractSent && !!session.chat,
             continuing,
             buildsOn,
+            // The operator's new prompt goes out whether or not the attempt it follows reached a conversation.
+            ...(task.continuing?.instruction ? { instruction: { text: task.continuing.instruction, fromAttempt: task.continuing.fromAttempt, ended: task.continuing.ended } } : {}),
             workDirNote: workingDirNote(work),
             vcsNote: prepared.note,
             // What is said about a commit is true only where one happens (live run 2026-10-03: promised with commits off).
@@ -1409,6 +1437,9 @@ export async function runTask(transport, session, task, deps) {
                     `each listed in "tried". With fewer, the runner asks you for another approach instead of accepting it.`
                 : undefined,
             shellNote: shellNote(shells, defaultShell),
+            ...(planning && planMode !== 'off'
+                ? { planNote: planModeNote(planMode, planEnforced, planMode === 'approve' && !!deps.approvePlan && (deps.currentMode?.() ?? cfg.execution.mode) === 'confirm') }
+                : {}),
         });
         await setTask((t) => {
             t.firstMessage = opening.firstMessage;
@@ -1857,6 +1888,11 @@ export async function runTask(transport, session, task, deps) {
                     deliverable,
                     deviations,
                     disputes,
+                    /*
+                     * The approved plan, for the review to hold the work to (plan mode, 2026-10-13): this attempt's, or —
+                     * carried on in its chat — the one the attempt it continues worked to.
+                     */
+                    ...(planInForce ? { plan: planInForce } : {}),
                     /*
                      * Each earlier finding with its evidence, the correction the implementer reports, and what the
                      * finding's own check came to at the last gate: the next reviewer judges the finding on the evidence,
@@ -2202,7 +2238,9 @@ export async function runTask(transport, session, task, deps) {
             await setTask((t) => {
                 t.iterations = iterations;
             });
-            const { reply, done, blocked } = parsed;
+            const { reply, blocked } = parsed;
+            // Nothing is done while the plan is being made: the stop word in a planning round ends nothing.
+            const done = parsed.done && !planning;
             sink.event('reply-parsed', { iteration: iterations, status: reply.status, steps: reply.steps.length, notes: reply.notes }, `iteration ${iterations}: ${reply.steps.length} step(s)${reply.notes ? ` — ${reply.notes}` : ''}`);
             /*
              * A deviation is recorded the moment it is declared, not when the task ends.
@@ -2262,6 +2300,81 @@ export async function runTask(transport, session, task, deps) {
              * what the reply said, at greater length and one message later. The reason carries the
              * approaches that were tried, and that is what the register shows.
              */
+            /*
+             * Plan mode: the reply that ends the planning phase — put to the operator or approved by the runner —
+             * and the two that do not belong in it. Answered here, in a message of its own, as a repair of the
+             * format is: no step runs and nothing is committed in between.
+             */
+            if (reply.status === 'plan' || (planning && reply.status === 'done')) {
+                let message;
+                let tag;
+                if (reply.status === 'done') {
+                    message = PLAN_FIRST;
+                    tag = 'plan-first';
+                    sink.event('plan-first', { iteration: iterations }, '"done" in the planning phase: nothing has been changed yet; the chat was asked for the plan', 'warn');
+                }
+                else if (!planning || !reply.plan) {
+                    message = PLAN_NOT_NOW;
+                    tag = 'plan-not-asked';
+                    sink.event('plan-not-asked', { iteration: iterations }, 'a plan arrived when none is asked for; the chat was told to carry on', 'warn');
+                }
+                else {
+                    planVersion += 1;
+                    tag = `plan-${planVersion}`;
+                    const plan = planFrom(reply.plan, planVersion, [...planRevisions]);
+                    await setTask((t) => {
+                        t.plan = plan;
+                    });
+                    await record(`PLAN ${planVersion}`, describePlan(plan));
+                    sink.event('plan-received', { version: planVersion, steps: plan.steps.length, files: plan.files }, `plan ${planVersion} received: ${plan.steps.length} stage(s)${plan.files.length > 0 ? `, ${plan.files.length} file(s)` : ''}`);
+                    // Asked of the operator only in a run that asks before each command: one that does not, approves it itself.
+                    const asks = planMode === 'approve' && !!deps.approvePlan && (deps.currentMode?.() ?? cfg.execution.mode) === 'confirm';
+                    let answer = { decision: 'approve' };
+                    if (asks) {
+                        sink.event('plan-waiting', { version: planVersion }, `plan ${planVersion} is waiting for the operator`, 'warn');
+                        answer = await deps.approvePlan({ sessionId: session.id, taskId: task.id, title: task.title, plan });
+                    }
+                    if (signal?.aborted || answer.decision === 'stop') {
+                        return await finish('aborted', answer.decision === 'stop' ? 'stopped by the operator at its plan' : 'stopped by the operator', undefined, lastMarkdown);
+                    }
+                    if (answer.decision === 'revise') {
+                        const comment = (answer.note ?? '').trim() || 'Make the plan more concrete: name the files and the stages.';
+                        planRevisions.push({ version: planVersion, comment, at: new Date().toISOString() });
+                        await setTask((t) => {
+                            if (t.plan)
+                                t.plan.revisions = [...planRevisions];
+                        });
+                        sink.event('plan-revise', { version: planVersion, comment }, `the operator asked for another plan: ${comment}`);
+                        message = planReviseMessage(comment, planVersion);
+                    }
+                    else {
+                        // Who approved it, and why the operator was not asked when they were not.
+                        const why = asks ? undefined : planMode === 'auto' ? 'plan mode approves plans automatically' : 'the run does not ask before each command';
+                        const approved = {
+                            by: asks ? 'operator' : 'auto',
+                            at: new Date().toISOString(),
+                            ...(answer.note?.trim() ? { note: answer.note.trim() } : {}),
+                            ...(why ? { why } : {}),
+                        };
+                        await setTask((t) => {
+                            if (t.plan)
+                                t.plan.approved = approved;
+                        });
+                        planInForce = { ...plan, approved };
+                        sink.event('plan-approved', { version: planVersion, by: approved.by, ...(approved.note ? { note: approved.note } : {}) }, `plan ${planVersion} approved ${asks ? 'by the operator' : `by the runner — ${why}`}${approved.note ? `, with a note` : ''}`);
+                        planning = false;
+                        message = planApprovedMessage(approved);
+                    }
+                }
+                await record(tag.toUpperCase().replace(/-/g, ' '), message);
+                await pacer.throttleSend();
+                const before = await transport.sendAndConfirm(message);
+                const next = await transport.waitForReply(before);
+                await saveReply(tag, next);
+                lastMarkdown = next.markdown;
+                await pacer.settle();
+                continue;
+            }
             if (!blocked && reply.steps.length > 0)
                 earlyBlocks = 0;
             /*
@@ -2279,8 +2392,12 @@ export async function runTask(transport, session, task, deps) {
                  * usually lost the assignment, said "above": it is given again rather than told nothing ran (live run 2026-10-04).
                  */
                 const message = task.continuing
-                    ? 'Not yet: this task is being continued, and nothing has run since. The assignment is this one, unchanged:\n\n' +
+                    ? `Not yet: this task is being continued, and nothing has run since. The assignment is this one${task.continuing.instruction ? '' : ', unchanged'}:\n\n` +
                         `${task.prompt.length > 6000 ? `${task.prompt.slice(0, 6000)}…` : task.prompt}\n\n` +
+                        // With the operator's new prompt, when there is one: the reason the task is being carried on at all.
+                        (task.continuing.instruction
+                            ? `With the operator's new instruction, which wins where the two disagree:\n\n${task.continuing.instruction.length > 6000 ? `${task.continuing.instruction.slice(0, 6000)}…` : task.continuing.instruction}\n\n`
+                            : '') +
                         'Carry on from where it stopped: send your next step now with status "continue", for example a command that shows ' +
                         'the state of the files the task works on. A task may end "blocked" only after steps that ran.'
                     : 'Not yet: nothing has been run in this task. You do not need to operate anything yourself — this runner executes ' +
@@ -2522,6 +2639,24 @@ export async function runTask(transport, session, task, deps) {
                     });
                 }
             }
+            /*
+             * The planning phase changes nothing: what a round changed is put back before the chat reads the
+             * results, as for a read-only task, and the chat is told. A reminder after many rounds that the
+             * plan is what ends the phase.
+             */
+            if (planning) {
+                planningRounds += 1;
+                if (planEnforced) {
+                    const check = await enforceScope(repoDirOf(session), [], true).catch(() => null);
+                    if (check && (check.outside.length > 0 || check.failed.length > 0)) {
+                        sink.event('plan-change-reverted', { iteration: iterations, reverted: check.reverted, failed: check.failed }, `changed in the planning phase, put back: ${check.reverted.join(', ') || '(none)'}`, 'warn');
+                        runnerNotes.push(`This is the planning phase, and nothing may change yet: the runner put back ${check.reverted.length > 0 ? check.reverted.join(', ') : 'nothing it could'}` +
+                            `${check.failed.length > 0 ? ` and could not put back ${check.failed.map((f) => f.path).join(', ')}` : ''}. Read, then send the plan.`);
+                    }
+                }
+                if (planningRounds === PLAN_NUDGE_AFTER)
+                    runnerNotes.push(planNudge(planningRounds));
+            }
             await guardInputs(iterations);
             // --- report back ---------------------------------------------------------------
             const report = await writeReport(results, {

package/dist/src/plan/brief.js

@@ -309,6 +309,12 @@ const FIELD_ROWS_EN = [
         'no',
         'Overrides the setting above for this one session: give the same name to the sessions that should share a chat, and leave it "" for a session that should have its own.',
     ],
+    [
+        'planMode',
+        'session',
+        'no',
+        'Plan first: "auto" — each task looks at the code read-only and makes a plan, approved by the runner, before it changes anything; "approve" — the same, approved by the operator in a run that asks before each command; "off". Leave it out to follow Settings. Ask when the work is large or the code base is new to the chat.',
+    ],
     [
         'projectDir',
         'session',
@@ -380,6 +386,12 @@ const FIELD_ROWS_BG = [
         'не',
         'Отменя настройката горе само за тази сесия: дай едно и също име на сесиите, които да споделят чат, и остави "" на онази, която да е сама.',
     ],
+    [
+        'planMode',
+        'сесия',
+        'не',
+        'Първо план: "auto" — всяка задача разглежда кода само с четене и прави план, одобрен от runner-а, преди да промени нещо; "approve" — същото, одобрено от оператора при пускане с питане преди всяка команда; "off". Пропусни го, за да следва Настройките. Питай, когато работата е голяма или кодът е непознат за чата.',
+    ],
     [
         'projectDir',
         'сесия',

package/dist/src/plan/importPlan.js

@@ -231,6 +231,8 @@ defaultProjectDir = '') {
             // the standing default, else the session's own.
             s.review = { enabled: planned.review?.enabled !== false, model: (planned.review?.model || defaultReviewModel).trim() };
             s.conversationGroup = group || undefined;
+            if (planned.planMode)
+                s.planMode = planned.planMode;
             s.model = (planned.model || defaultModel).trim() || undefined;
             // The plan's models are kept, and marked as the plan's: Settings outrank them (see `effectiveModels`).
             if (planned.model?.trim())

package/dist/src/plan/schema.js

@@ -348,6 +348,16 @@ const SessionInput = z.object({
      * the same name. Empty means it gets a conversation of its own.
      */
     conversationGroup: z.string().trim().default(''),
+    /**
+     * Plan mode for the session's tasks (see `PlanMode` in session/model.ts): "auto" plans first and goes
+     * on, "approve" plans first and waits for the operator in a run that asks before each command, "off"
+     * does not plan apart. Absent follows Settings.
+     */
+    planMode: z
+        .enum(['off', 'auto', 'approve'], {
+        error: 'planMode must be "off", "auto" (plan first, approved by the runner) or "approve" (plan first, approved by the operator in a run that asks before each command).',
+    })
+        .optional(),
     vcs: VcsInput,
     review: ReviewInput.optional(),
     /**