authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-03-04 09:36:02-08:00
committergravatar for jmarminge@gmail.comJulius Marminge <jmarminge@gmail.com> 2026-03-05 23:00:41-08:00
log0a67f9dd39d9df21dcbd56f28c7c56fa5358282e
tree6dcc4df1e5a68a29296200b98a6324ef000ff1bd
parentdf6bb188d477f0e6affb089fc5496ff5ebc425f4

Clarify Cursor plan-mode semantics and ACP extension mapping

- Define Cursor operating mode as binary `default | plan` - Document mapping for `cursor/ask_question`, `cursor/create_plan`, and `cursor/update_todos` - Update capability and fallback guidance based on docs plus probe evidence

1 files changed, 40 insertions(+), 35 deletions(-)

docs/plan-mode-deep-dive.md+40-35
......@@ -62,10 +62,15 @@ Cursor protocol decisions should be based on:
6262- ACP docs
6363- current local ACP probe output
6464
65Confirmed from probe:
65Confirmed from current docs + probe:
6666
6767- ACP session modes include `agent`, `plan`, and `ask`
68- currently observed ACP updates do not include native structured plan updates or native structured question prompts comparable to Codex or Claude
68- for product semantics, treat ACP mode as binary: `operatingMode: default | plan`
69- Cursor ACP extension methods include:
70 - `cursor/ask_question` (multiple-choice question prompt)
71 - `cursor/create_plan` (explicit plan approval request)
72 - `cursor/update_todos` (todo-state updates that can drive plan-step UI)
73- probe streams still show standard chunk/update events and may not always emit extension methods in every run
6974
7075---
7176
......@@ -77,13 +82,10 @@ The implementation should separate three concepts that are currently easy to con
7782
7883This is the agent runtime mode.
7984
80Canonical operating modes:
85Canonical operating mode:
8186
8287- `default`
8388- `plan`
84- `ask`
85- `execute`
86- `unknown`
8789
8890This should be represented at runtime independently of plan content or prompt cards.
8991
......@@ -188,7 +190,6 @@ Required additions:
188190```ts
189191interface ProviderInteractiveCapabilities {
190192 supportsPlanMode: boolean;
191 supportsAskMode: boolean;
192193 supportsStructuredPlanUpdates: boolean;
193194 supportsPlanTextStreaming: boolean;
194195 supportsStructuredUserInput: boolean;
......@@ -329,7 +330,6 @@ Implementation requirements:
329330
3303315. Publish capabilities:
331332- `supportsPlanMode = true`
332- `supportsAskMode = false` unless Codex exposes a distinct ask mode separately
333333- `supportsStructuredPlanUpdates = true`
334334- `supportsPlanTextStreaming = true`
335335- `supportsStructuredUserInput = true`
......@@ -384,7 +384,7 @@ Implementation requirements:
384384
3853851. Publish native operating mode:
386386- `permissionMode: 'plan'` -> canonical mode `plan`
387- if future values map cleanly, publish `ask` or `default` accordingly
387- all other values -> canonical mode `default`
388388
3893892. Detect `AskUserQuestion` tool uses:
390390- inspect `tool_use` blocks in assistant messages / stream events
......@@ -418,7 +418,6 @@ Implementation requirements:
418418
4194197. Publish capabilities:
420420- `supportsPlanMode = true`
421- `supportsAskMode = false` unless explicit Claude mode is observed
422421- `supportsStructuredPlanUpdates = partial/false initially`
423422- `supportsPlanTextStreaming = partial`
424423- `supportsStructuredUserInput = true`
......@@ -448,13 +447,17 @@ Implementation default:
448447
449448### Summary
450449
451Cursor should initially ship with degraded plan-mode support: native mode awareness, but no claim of structured prompt cards or structured plan steps until protocol evidence exists.
450Cursor should ship with binary plan-mode semantics (`default | plan`) and implement documented ACP extension methods when present. If extension methods are absent in a given session, it should degrade cleanly to mode + streamed assistant text.
452451
453452### Real native evidence
454453
455From the ACP probe:
454From the Cursor ACP docs + current probe:
456455
457456- available modes include `agent`, `plan`, and `ask`
457- Cursor ACP docs define extension methods:
458 - `cursor/ask_question`
459 - `cursor/create_plan`
460 - `cursor/update_todos`
458461- observed updates include:
459462 - `available_commands_update`
460463 - `agent_thought_chunk`
......@@ -464,11 +467,11 @@ From the ACP probe:
464467- observed request type:
465468 - `session/request_permission`
466469
467Not observed:
470Current caveats:
468471
469- native structured plan update events
470- native plan text delta event distinct from normal message chunks
471- native structured ask-user-question event
472- no standard ACP event equivalent to Codex `turn/plan/updated`
473- no standard ACP event equivalent to Codex `item/plan/delta`
474- extension-method payload shapes should be fixture-captured from live sessions before locking parser assumptions
472475
473476### Adapter implementation
474477
......@@ -482,18 +485,18 @@ Implementation requirements:
482485
4834861. Publish native operating mode:
484487- map ACP `plan` mode -> canonical `plan`
485- map ACP `ask` mode -> canonical `ask`
486- map ACP `agent` mode -> canonical `default` or `execute` depending product semantics
488- map ACP `agent` and `ask` modes -> canonical `default`
489- preserve raw ACP mode in native metadata for debugging
487490
4882. Do not claim unsupported structured capabilities:
489- no native `turn.plan.updated`
490- no native `user-input.requested`
491- no native `ExitPlanMode` equivalent confirmed
4912. Implement documented Cursor extension methods:
492- `cursor/ask_question` -> canonical `user-input.requested`
493- `cursor/update_todos` -> canonical `turn.plan.updated` when payload is parseable into stable step ids/text/status
494- `cursor/create_plan` -> canonical final-plan handoff / approval-request surface
492495
4934963. Use graceful fallback behavior:
494497- render plan mode as mode state + assistant text stream
495- render ask mode as conversational mode + normal user composer
496- do not render structured question cards for Cursor initially
498- if no `cursor/ask_question` event is emitted, fall back to normal conversational input
499- if no parseable `cursor/update_todos` event is emitted, fall back to text-only plan rendering
497500
4985014. Preserve room for future enrichment:
499502- keep raw ACP notifications available in native event logs
......@@ -501,18 +504,19 @@ Implementation requirements:
501504
5025055. Publish capabilities:
503506- `supportsPlanMode = true`
504- `supportsAskMode = true`
505- `supportsStructuredPlanUpdates = false`
506- `supportsPlanTextStreaming = false` initially
507- `supportsStructuredUserInput = false`
507- `supportsStructuredPlanUpdates = true` when `cursor/update_todos` is available, otherwise false
508- `supportsPlanTextStreaming = false` initially (no distinct plan-text channel)
509- `supportsStructuredUserInput = true` when `cursor/ask_question` is available, otherwise false
508510- `supportsFreeformUserInput = false` via structured prompt path
509511- `supportsExitPlanMode = false`
510512
511513### Cursor-specific tests
512514
513- ACP mode metadata maps correctly into canonical mode
515- ACP mode metadata maps to `plan` vs `default` correctly
516- `cursor/ask_question` maps into canonical structured prompt schema
517- `cursor/update_todos` maps into canonical structured plan state when parseable
518- `cursor/create_plan` maps into final-plan handoff / approval surface
514519- `agent_thought_chunk` and `agent_message_chunk` still render normally in plan mode
515- UI does not try to open structured prompt cards for Cursor
516520- fallback conversational flow remains functional
517521
518522### Cursor-specific follow-up probe work
......@@ -520,9 +524,9 @@ Implementation requirements:
520524Add dedicated probes for:
521525
522526- mode-switching during an active session
523- ask-mode prompt behavior
527- real payload shapes for `cursor/ask_question`, `cursor/create_plan`, and `cursor/update_todos`
524528- any request types besides `session/request_permission`
525- whether specific built-in skills or prompt styles trigger structured question surfaces
529- whether extension methods are always emitted or only for specific prompt styles
526530
527531---
528532
......@@ -543,7 +547,7 @@ Render plan mode through a single UI model driven by canonical events and provid
543547
544548### Rendering rules
545549
5461. Show operating mode indicator whenever current mode is `plan` or `ask`
5501. Show operating mode indicator whenever current mode is `plan`
5475512. Show structured question card only when a pending `user-input.requested` exists
5485523. Show structured plan step list when a current `turn.plan.updated` snapshot exists
5495534. Append `plan_text` streaming content beneath or alongside structured steps when both exist
......@@ -631,7 +635,8 @@ Add coverage for:
631635
632636- Codex is the reference provider for full structured plan/question UX.
633637- Claude supports structured prompts via tool adaptation, but incremental structured plan updates are not assumed initially.
634- Cursor supports plan and ask modes, but not structured prompt cards or structured plan step updates initially.
638- Cursor transport exposes `agent|plan|ask`, but product semantics collapse this to `operatingMode: default | plan`.
639- Cursor structured prompts/plan steps are driven by ACP extension methods when present, with fallback when absent.
635640- Product/UI should degrade gracefully rather than invent unsupported provider behavior.
636641- Raw provider payloads should always be retained where feasible to support future adapter refinement.
637642
......@@ -643,6 +648,6 @@ Add coverage for:
6436482. Wire capabilities/mode through orchestration and web socket projections
6446493. Finish Codex end-to-end plan mode implementation first
6456504. Implement Claude `AskUserQuestion` and `ExitPlanMode` adapter mapping
6465. Add Cursor degraded plan/ask mode support
6515. Add Cursor binary (`default|plan`) mode support + ACP extension-method mapping
6476526. Build capability-driven frontend rendering and answer submission
6486537. Add reconnect/history coverage and transcript/protocol fixtures