Files
AlexRV12andClaude Opus 5 caa189868c feat(ai-sessions): add plan mode (#10057)
* feat(sessions): let an opener name the artifact version to show

A tab already remembers the version a reader pinned, and re-pointing it keeps
that pin. Plan mode needs the two intents that leaves out: a plan card scrolled
up the transcript wants the version it proposed, and a plan going up for
approval wants the current text with no pin at all.

`ArtifactVersionTarget` is those two alongside the existing one: a number,
`'latest'`, or omitted. Omitted still cannot double as `'latest'` — every
artifact tool re-opens the document it just wrote, so taking that as a request
to move would yank a reader out of the version they chose on every edit the
agent makes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(copilot): add the plan-mode gate and tag plan-mode-safe tools

Plan mode is a read-only posture, so something has to decide which tools it
may still run. `Tool.planModeSafe` is that tag, and processToolCall fails
closed on it: untagged means mutating means blocked. Deriving it from
`requiresConfirmation` was not an option — unconfirmed mutating tools exist,
and a posture that leaks one is not a posture.

The gate runs twice per call. Before `validateBeforeConfirmation`, so a
validator cannot reach out while planning; and again after the confirmation
wait, because plan mode can be entered while a mutating tool's card is
already pending, and that approval must not carry it through.

Arguments are read one field at a time rather than through a parse of the
whole call. `change_note` is optional and cosmetic, and a model that sends it
as `null` would otherwise fail the object parse and take the plan down with
it — the user being told there was no plan to approve, which is false.

Also here, because refusing a call well needs them: a validator may now
return the row the user reads and the result the model gets separately, a
tool may word its own cancellation, and a tool may start work when its card
appears rather than when it is approved. The gate is consulted before any of
them.

`shouldAutoAcceptToolConfirmations` is asked about the tool by name, because
skipping the confirmation wait is itself an answer on the user's behalf and
one tool must not be answered for. Deciding that without the name would put
the exception out of reach of the only path that needs it.

The gate stays inert until a chat supplies `isPlanModeActive`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(copilot): give a session one versioned plan document

The plan the user agrees to has to survive `/clear`, so it belongs to the
session rather than the conversation, and a session holds exactly one. Its id
is the session's, so the primary key is the constraint — there is no second
row to mint, no index to maintain and no schema change at all.

Every write reads the row it is about to replace inside the transaction that
replaces it. Read outside, two tabs both see version N, both stamp N+1, and
the later write silently drops the earlier one's text and its snapshot;
IndexedDB serialises readwrite transactions over a store, so read and write
together cannot interleave. Approval takes the same route but patches only
the pointer: an approval computed while another tab was revising must not
carry this tab's older content back over the newer text.

Approval is `approvedVersion`, a pointer at a version, never a flag. Below
the current version means the newest text is a proposal the user has not
agreed to; absent means nothing here was ever approved. Only exit_plan_mode
can leave the pointer behind, since every write outside plan mode carries it
forward — an amendment the user's posture already trusts is still the agreed
plan. Declining writes nothing at all: the refused proposal stands as the
newest version, with the agreed one still in history.

Nor can create_artifact confer approval. It asks for no confirmation, so the
model writing a plan document is not the user agreeing to one; a plan written
there holds the session's slot as a draft until a decision lands on it.

That is also why the approved version is exempt from pruning. A plan approved
at v1 and then planned against for twenty more rounds would otherwise lose
the very version that stands as agreed, and with it the card that opens it,
the banner offering it back, and read_artifact at that version. It is
excluded from the pruning candidates rather than added on top, so the budget
is unchanged and what survives simply stops being contiguous.

The write reports whether the database took it. Most callers still degrade
like the reads do, but a plan cannot: returning one the database refused
would let the user approve and execute against a document that disappears on
reload — a refused plan write raises instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(copilot): add plan mode — the posture and its two tools

enter_plan_mode asks to hold work; exit_plan_mode hands over a plan and,
on approval, gives the posture back to whatever preceded it. Both carry
`planModeSafe`, since a posture with no exit is a trap. Only the transition
the current posture allows is offered, so there is no tool for leaving a
posture the chat is not in.

A planning round runs from entering plan mode to the proposal the user
decides on. It remembers only the write it made, because nothing it does is
undone — and that write is shared between the card's confirmation hook and
the tool's `fn`, so the plan is on screen while the user is deciding whether
to approve it rather than after.

The round is identified by an epoch bumped on *entering*, not by the
conversation. A chat rotation mid-approval must still let that approval hand
the posture back; a round the user has since left and re-entered must not,
or approving the old plan would drop them out of a read-only posture they
just chose.

Saving a proposal revises the session's plan document and creates one only
when there is none — both halves in a single transaction, so a second tab
proposing at the same moment revises the row this one wrote rather than
racing it.

Persistence failures hold the posture. Approval is reported only once both
the proposal and the approval pointer are durable, so a plan the database
refused cannot unblock mutating tools. The failure is reported from `fn`
and no earlier: the write settles while the card is still waiting to be
confirmed, and clearing that card from underneath the wait would take away
the only control that resolves it.

An auto-accepting posture answers for the user through one predicate, asked
by every path that answers: the pending-card sweep, the confirmation itself,
and the decision to skip the wait at all. enter_plan_mode never qualifies:
YOLO means "stop asking and run it", and a call from a tool set snapshotted
before the switch must not answer that with a read-only posture — whether its
card is already pending or has yet to be registered.

Plan mode lives in its own controller with a narrow view of the chat it runs
in: it reads that autonomy state and asks for the two changes it can cause,
rather than owning any of it.

Plan mode is offered only in a session chat, and a session chat is GLOBAL for
its whole life. The gate reads that mode, so `changeMode` refuses to move one
out of GLOBAL rather than resting the invariant on a picker being hidden.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(copilot): surface plan mode in the chat and the artifact list

Plan mode is the only posture that refuses work, so the composer says so
before the user types the request it is about to turn down: the mode pill is
tinted whole rather than by its icon, and the empty placeholder carries the
constraint in words. Teal, not the house green — green is the transcript's
success colour a few rows up, and a mode signal in it would read as "this
worked" rather than "this is held".

A blocked tool renders as its own lean row naming the tool, not as an error:
the call did what plan mode says it should, and "why can't it edit" is
answered where it is asked.

A plan card names the decision — proposed, approved, or not approved — and
never the button, since a Stop and a posture switch resolve it too. Its
button opens the version that card proposed, so a card far up the transcript
still shows the plan it put forward rather than whatever the document has
become since.

The artifact list and the preview header both label the plan through one
badge helper, so the two cannot disagree about what counts as one: a plan the
user never approved keeps the plan icon and takes the neutral badge, leaving
the teal to mean exactly one thing. In the viewer, an unapproved revision
says so in a bar that cannot be scrolled past, with the version the user did
agree to one click away.

The autonomy picker became a table with one row per posture, so adding one
touches a single place instead of four parallel switch statements.

A version of a plan is read against the one the user approved, not against the newest:
latest is only where the model happened to stop. So the approved version is never stale —
its bar is teal and points forward to the draft rather than warning about it — the version
in front of it is the draft, and anything behind it is history that is neither and takes no
pill at all. The list opens a plan at the approved version for the same reason, which is
what lets its pill say `plan` while an unapproved draft sits at the head.

One helper answers all of it, so the list and the preview header cannot drift apart on what
counts as the plan.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* test(ai-evals): exercise plan mode end to end

A case a unit test cannot stand in for: it starts in plan mode against the
real gate and the real exit_plan_mode, and grades whether the model
researches and hands over a usable plan instead of guessing at one.

The checklist does not grade what the harness does for the model —
exit_plan_mode writes the plan document itself, so "saves the plan as an
artifact" would pass on any run where the tool is called at all.

The eval store seeds artifacts with history and mirrors the store's own
approval rules, so a rename cannot promote a proposal the user turned down.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(ai-evals): import the plan-mode messages from the module that owns them

`PLAN_MODE_MESSAGES` moved to `planModeMessages.ts`; `planMode.ts` imports it
without re-exporting. Under vitest, which runs the frontend adapters, the stale
import resolved to `undefined` rather than failing to link, so
`global-planmode1-hands-over-a-plan` threw on the approval message after the
posture had already been dropped and the tool withdrawn.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(copilot): state plan mode's constraint in neutral text

The composer's two-tone placeholder becomes a plain "Read-only" beside the
autonomy picker, next to where YOLO puts its own warning, and a blocked call's
row drops the mode colour. Teal is left marking what the posture is — the
badge, the version bars, the pill — rather than every call it refuses.

ContextTextarea goes back to main with the accent: `placeholderAccent` had no
other consumer, and the aria-label existed only because the accent blanked the
native placeholder.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(copilot): hold the plan header's verdict until the snapshot lands

Opening a plan at the version its reader approved pins a version behind the
head, and until that read resolves `shownVersion` is still the head — so the
header wore the draft's badge and its orange "not approved" bar over the very
case the pin exists to serve, then flipped.

The header now says nothing while `restoringPin`, as the body already does.
Judging `pinned` instead would print the approved signal over text that is
still the draft, trading a true transient signal for a false one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(copilot): refuse a hand-over once plan mode has ended

A response can carry two exit_plan_mode calls, and the tool list they run
against is snapshotted before the first one restores the posture. The second
then found the tool with plan mode already over: under YOLO every confirmation
is answered for the user, so it wrote its own summary and stamped the user's
approval on a plan no card had shown them.

Refused in `validateBeforeConfirmation` rather than in `fn`, since
`onConfirmationRequested` writes the document too. The maintenance path is
untouched — a plan still gets revised outside the posture with update_artifact,
which is what the tool's own description already tells the model to use.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 14:27:38 +02:00
..