Commit 0a67f9dd39d9df21dcbd56f28c7c56fa5358282e | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-03-04 09:36:02-08:00
committer	Julius Marminge <jmarminge@gmail.com> 2026-03-05 23:00:41-08:00
log	0a67f9dd39d9df21dcbd56f28c7c56fa5358282e
tree	6dcc4df1e5a68a29296200b98a6324ef000ff1bd
parent	df6bb188d477f0e6affb089fc5496ff5ebc425f4

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

docs/plan-mode-deep-dive.md+40-35

 @@ -62,10 +62,15 @@ Cursor protocol decisions should be based on:
 - ACP docs
 - current local ACP probe output
-Confirmed from probe:
+Confirmed from current docs + probe:
 - ACP session modes include `agent`, `plan`, and `ask`
-- currently observed ACP updates do not include native structured plan updates or native structured question prompts comparable to Codex or Claude
+- for product semantics, treat ACP mode as binary: `operatingMode: default | plan`
+- Cursor ACP extension methods include:
+  - `cursor/ask_question` (multiple-choice question prompt)
+  - `cursor/create_plan` (explicit plan approval request)
+  - `cursor/update_todos` (todo-state updates that can drive plan-step UI)
+- probe streams still show standard chunk/update events and may not always emit extension methods in every run
 ---
 @@ -77,13 +82,10 @@ The implementation should separate three concepts that are currently easy to con
 This is the agent runtime mode.
-Canonical operating modes:
+Canonical operating mode:
 - `default`
 - `plan`
-- `ask`
-- `execute`
-- `unknown`
 This should be represented at runtime independently of plan content or prompt cards.
 @@ -188,7 +190,6 @@ Required additions:
 ```ts
 interface ProviderInteractiveCapabilities {
   supportsPlanMode: boolean;
-  supportsAskMode: boolean;
   supportsStructuredPlanUpdates: boolean;
   supportsPlanTextStreaming: boolean;
   supportsStructuredUserInput: boolean;
 @@ -329,7 +330,6 @@ Implementation requirements:
 5. Publish capabilities:
 - `supportsPlanMode = true`
-- `supportsAskMode = false` unless Codex exposes a distinct ask mode separately
 - `supportsStructuredPlanUpdates = true`
 - `supportsPlanTextStreaming = true`
 - `supportsStructuredUserInput = true`
 @@ -384,7 +384,7 @@ Implementation requirements:
 1. Publish native operating mode:
 - `permissionMode: 'plan'` -> canonical mode `plan`
-- if future values map cleanly, publish `ask` or `default` accordingly
+- all other values -> canonical mode `default`
 2. Detect `AskUserQuestion` tool uses:
 - inspect `tool_use` blocks in assistant messages / stream events
 @@ -418,7 +418,6 @@ Implementation requirements:
 7. Publish capabilities:
 - `supportsPlanMode = true`
-- `supportsAskMode = false` unless explicit Claude mode is observed
 - `supportsStructuredPlanUpdates = partial/false initially`
 - `supportsPlanTextStreaming = partial`
 - `supportsStructuredUserInput = true`
 @@ -448,13 +447,17 @@ Implementation default:
 ### Summary
-Cursor 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.
+Cursor 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.
 ### Real native evidence
-From the ACP probe:
+From the Cursor ACP docs + current probe:
 - available modes include `agent`, `plan`, and `ask`
+- Cursor ACP docs define extension methods:
+  - `cursor/ask_question`
+  - `cursor/create_plan`
+  - `cursor/update_todos`
 - observed updates include:
   - `available_commands_update`
   - `agent_thought_chunk`
 @@ -464,11 +467,11 @@ From the ACP probe:
 - observed request type:
   - `session/request_permission`
-Not observed:
+Current caveats:
-- native structured plan update events
+- no standard ACP event equivalent to Codex `turn/plan/updated`
-- native plan text delta event distinct from normal message chunks
+- no standard ACP event equivalent to Codex `item/plan/delta`
-- native structured ask-user-question event
+- extension-method payload shapes should be fixture-captured from live sessions before locking parser assumptions
 ### Adapter implementation
 @@ -482,18 +485,18 @@ Implementation requirements:
 1. Publish native operating mode:
 - map ACP `plan` mode -> canonical `plan`
-- map ACP `ask` mode -> canonical `ask`
+- map ACP `agent` and `ask` modes -> canonical `default`
-- map ACP `agent` mode -> canonical `default` or `execute` depending product semantics
+- preserve raw ACP mode in native metadata for debugging
-2. Do not claim unsupported structured capabilities:
+2. Implement documented Cursor extension methods:
-- no native `turn.plan.updated`
+- `cursor/ask_question` -> canonical `user-input.requested`
-- no native `user-input.requested`
+- `cursor/update_todos` -> canonical `turn.plan.updated` when payload is parseable into stable step ids/text/status
-- no native `ExitPlanMode` equivalent confirmed
+- `cursor/create_plan` -> canonical final-plan handoff / approval-request surface
 3. Use graceful fallback behavior:
 - render plan mode as mode state + assistant text stream
-- render ask mode as conversational mode + normal user composer
+- if no `cursor/ask_question` event is emitted, fall back to normal conversational input
-- do not render structured question cards for Cursor initially
+- if no parseable `cursor/update_todos` event is emitted, fall back to text-only plan rendering
 4. Preserve room for future enrichment:
 - keep raw ACP notifications available in native event logs
 @@ -501,18 +504,19 @@ Implementation requirements:
 5. Publish capabilities:
 - `supportsPlanMode = true`
-- `supportsAskMode = true`
+- `supportsStructuredPlanUpdates = true` when `cursor/update_todos` is available, otherwise false
-- `supportsStructuredPlanUpdates = false`
+- `supportsPlanTextStreaming = false` initially (no distinct plan-text channel)
-- `supportsPlanTextStreaming = false` initially
+- `supportsStructuredUserInput = true` when `cursor/ask_question` is available, otherwise false
-- `supportsStructuredUserInput = false`
 - `supportsFreeformUserInput = false` via structured prompt path
 - `supportsExitPlanMode = false`
 ### Cursor-specific tests
-- ACP mode metadata maps correctly into canonical mode
+- ACP mode metadata maps to `plan` vs `default` correctly
+- `cursor/ask_question` maps into canonical structured prompt schema
+- `cursor/update_todos` maps into canonical structured plan state when parseable
+- `cursor/create_plan` maps into final-plan handoff / approval surface
 - `agent_thought_chunk` and `agent_message_chunk` still render normally in plan mode
-- UI does not try to open structured prompt cards for Cursor
 - fallback conversational flow remains functional
 ### Cursor-specific follow-up probe work
 @@ -520,9 +524,9 @@ Implementation requirements:
 Add dedicated probes for:
 - mode-switching during an active session
-- ask-mode prompt behavior
+- real payload shapes for `cursor/ask_question`, `cursor/create_plan`, and `cursor/update_todos`
 - any request types besides `session/request_permission`
-- whether specific built-in skills or prompt styles trigger structured question surfaces
+- whether extension methods are always emitted or only for specific prompt styles
 ---
 @@ -543,7 +547,7 @@ Render plan mode through a single UI model driven by canonical events and provid
 ### Rendering rules
-1. Show operating mode indicator whenever current mode is `plan` or `ask`
+1. Show operating mode indicator whenever current mode is `plan`
 2. Show structured question card only when a pending `user-input.requested` exists
 3. Show structured plan step list when a current `turn.plan.updated` snapshot exists
 4. Append `plan_text` streaming content beneath or alongside structured steps when both exist
 @@ -631,7 +635,8 @@ Add coverage for:
 - Codex is the reference provider for full structured plan/question UX.
 - Claude supports structured prompts via tool adaptation, but incremental structured plan updates are not assumed initially.
-- Cursor supports plan and ask modes, but not structured prompt cards or structured plan step updates initially.
+- Cursor transport exposes `agent|plan|ask`, but product semantics collapse this to `operatingMode: default | plan`.
+- Cursor structured prompts/plan steps are driven by ACP extension methods when present, with fallback when absent.
 - Product/UI should degrade gracefully rather than invent unsupported provider behavior.
 - Raw provider payloads should always be retained where feasible to support future adapter refinement.
 @@ -643,6 +648,6 @@ Add coverage for:
 2. Wire capabilities/mode through orchestration and web socket projections
 3. Finish Codex end-to-end plan mode implementation first
 4. Implement Claude `AskUserQuestion` and `ExitPlanMode` adapter mapping
-5. Add Cursor degraded plan/ask mode support
+5. Add Cursor binary (`default|plan`) mode support + ACP extension-method mapping
 6. Build capability-driven frontend rendering and answer submission
 7. Add reconnect/history coverage and transcript/protocol fixtures