feat: visualize ordinary-session plan execution

docs/design/ordinary-session-plan-execution.md

@@ -0,0 +1,96 @@
+# Ordinary Session Plan Execution
+
+## Goal
+
+Show an ordinary session's Todo plan as a dependency graph and connect each
+node to the Agent executions that implement it. Reuse the existing ACP plan
+stream, session task snapshot, and subagent detail session.
+
+This feature is observational. It does not schedule, retry, unblock, or
+complete work.
+
+## Data contract
+
+`todo_write` accepts optional `blockedBy` Todo IDs. The runtime validates that
+IDs are unique, references exist, dependencies are not duplicated or
+self-referential, and the graph is acyclic.
+
+The Todo sidecar stores a runtime-generated `planId` with the current snapshot.
+The ID remains stable while an active plan is revised. Clearing a plan, or
+starting non-empty work after the prior plan completed, starts a new plan.
+
+Todo result displays carry the `planId`, so live ACP projection and the
+ordinary transcript replay path preserve the same plan metadata:
+
+- plan update `_meta.qwenTodoPlan.id`: stable plan identity
+- plan update `_meta.qwenTranscript.planToolCallId`: source Todo tool call
+- plan entry `_meta.qwenTodo.id`: original Todo ID
+- plan entry `_meta.qwenTodo.blockedBy`: dependency IDs when present
+
+Clients that ignore `_meta` continue to receive standard ACP plan entries.
+
+The Agent tool accepts optional `todo_id`. It is guidance, not a runtime gate:
+top-level Agent calls should provide it when an active Todo graph exists.
+Existing `AgentTask.toolUseId` joins the Agent tool call to live task status, so
+the task API needs no additional field.
+
+## UI flow
+
+The active Todo pill continues to render the existing compact list. Clicking
+it opens the existing Tasks dialog. When plan metadata is present, that dialog
+adds a native CSS plan-execution section above the existing task tree:
+
+1. Topologically layer nodes from `blockedBy`.
+2. Group top-level Agent tool calls by `args.todo_id`.
+3. Join live task rows through `task.toolUseId === tool.callId`.
+4. Keep nested Agent rows under the root via `parentAgentId`.
+5. Select a workflow node to inspect its full Todo content, status,
+   dependencies, and linked Agent executions below the graph.
+6. Open the existing live subagent detail panel from a linked Agent execution;
+   it remains the source for streamed progress, tool calls, and final output.
+7. Put missing or unknown `todo_id` bindings in an Unassigned group.
+
+No graph library is added. Plans without dependency metadata keep list-style
+presentation.
+
+## Plan Mode approval
+
+Plan Mode is the opt-in execution gate for users who want to review a workflow
+before work begins. When `exit_plan_mode` requests permission, Web Shell shows
+the authoritative ACP plan body followed by the active Todo workflow in the
+existing approval panel. The Todo view is supplemental because its snapshot can
+differ from the submitted plan text. A dependency-aware workflow is rendered as
+the same DAG used by the Tasks dialog; a workflow without dependencies keeps the
+list presentation.
+
+The existing permission lifecycle remains authoritative: approving exits Plan
+Mode and starts execution, while rejecting keeps the session in Plan Mode. If
+there is no active Todo snapshot, the approval keeps its existing text-only
+presentation using the plan body carried by ACP. Sessions that do not enter
+Plan Mode are unchanged.
+
+## Status composition
+
+Todo status remains the business source of truth. Agent state is an execution
+overlay:
+
+1. Any linked execution running: Running
+2. Otherwise, any linked execution paused: Paused
+3. Todo completed: Completed
+4. Any dependency Todo incomplete: Blocked
+5. Todo in progress: In progress
+6. Otherwise: Ready
+
+A failed or cancelled execution adds a Needs attention badge without changing
+the Todo status.
+
+## Compatibility and boundaries
+
+- Old Todo snapshots without IDs or dependencies remain readable.
+- Agent calls without `todo_id` remain valid.
+- Empty Todo snapshots must clear active state immediately.
+- Full subagent results stay out of the three-second task polling response.
+- Todo nodes do not invent step output; execution detail comes from linked
+  Agent tool calls and the existing subagent detail session.
+- Strict plan-first enforcement for every session remains out of scope because
+  a session-level existence check could accept a stale plan.

docs/plans/2026-07-23-session-workflow-approval.md

@@ -0,0 +1,30 @@
+# Session Workflow Approval Implementation
+
+## Scope
+
+Show the current Todo workflow inside the existing `exit_plan_mode` permission
+panel so a user can review the dependency graph before execution starts.
+
+## Implementation
+
+1. Add an optional Todo snapshot to `ToolApproval` and render
+   `PlanExecutionView` only for Plan Mode exit approvals.
+2. Pass the active Todo snapshot from both the main session view and split
+   session panes.
+3. Preserve the ACP plan body as the text-only fallback when no Todo snapshot
+   exists and leave non-Plan-Mode approvals unchanged.
+4. Make workflow nodes selectable and show the selected Todo's full content,
+   status, dependencies, and linked Agent executions below the graph.
+5. Reuse the existing subagent detail panel for live progress and final output;
+   do not add execution output to Todo snapshots or task polling.
+
+## Verification
+
+- Component test: Plan Mode approval renders a Todo dependency workflow.
+- Component test: Plan Mode approval without Todos preserves its text content.
+- Adapter test: ACP exit-plan content reaches the approval request.
+- Wiring tests: main and split session approvals receive their own active Todo
+  snapshot.
+- Workflow test: selecting a node exposes its details and linked subagent opens
+  the existing detail callback.
+- Run the focused Web Shell tests, typecheck, and build.

packages/acp-bridge/src/transcript-replay.test.ts

@@ -543,15 +543,30 @@ describe('createTranscriptReplayMachine', () => {
           callId: 'todo-call',
           resultDisplay: {
             type: 'todo_list',
-            todos: [{ content: 'Ship it', status: 'completed' }],
+            planId: 'plan-1',
+            todos: [
+              {
+                id: 'ship',
+                content: 'Ship it',
+                status: 'completed',
+                blockedBy: ['test'],
+              },
+            ],
           },
         },
       }),
     );
     expect(plan[0]).toMatchObject({
       sessionUpdate: 'plan',
       entries: [
-        { content: 'Ship it', priority: 'medium', status: 'completed' },
+        {
+          content: 'Ship it',
+          priority: 'medium',
+          status: 'completed',
+          _meta: {
+            qwenTodo: { id: 'ship', blockedBy: ['test'] },
+          },
+        },
       ],
       _meta: {
         stats: {
@@ -560,6 +575,11 @@ describe('createTranscriptReplayMachine', () => {
           cachedTokens: 0,
           apiTimeMs: 0,
         },
+        qwenTodoPlan: { id: 'plan-1' },
+        qwenTranscript: {
+          planToolCallId: 'todo-call',
+          sourceRecordIds: ['todo-result'],
+        },
       },
     });
   });

packages/acp-bridge/src/transcript-replay.ts

@@ -92,6 +92,7 @@ interface UpdateMetaOptions {
   readonly timestamp?: string | number;
   readonly sourceRecordIds?: readonly string[];
   readonly planToolCallId?: string;
+  readonly todoPlanId?: string;
   readonly extra?: Readonly<Record<string, unknown>>;
 }
 
@@ -125,6 +126,12 @@ export interface TranscriptTodoItem {
   readonly id?: string;
   readonly content: string;
   readonly status: 'pending' | 'in_progress' | 'completed';
+  readonly blockedBy?: readonly string[];
+}
+
+export interface TranscriptTodoPlan {
+  readonly planId?: string;
+  readonly todos: TranscriptTodoItem[];
 }
 
 export interface TranscriptUsageUpdateOptions extends UpdateMetaOptions {
@@ -315,6 +322,9 @@ export function createTranscriptPlanUpdate(
     ...options,
     extra: {
       ...(cumulativeUsage ? { stats: { ...cumulativeUsage } } : {}),
+      ...(options.todoPlanId
+        ? { qwenTodoPlan: { id: options.todoPlanId } }
+        : {}),
       ...(options.extra ?? {}),
     },
   });
@@ -324,6 +334,16 @@ export function createTranscriptPlanUpdate(
       content: todo.content,
       priority: 'medium' as const,
       status: todo.status,
+      ...(todo.id || todo.blockedBy
+        ? {
+            _meta: {
+              qwenTodo: {
+                ...(todo.id ? { id: todo.id } : {}),
+                ...(todo.blockedBy ? { blockedBy: [...todo.blockedBy] } : {}),
+              },
+            },
+          }
+        : {}),
     })),
     ...(meta ? { _meta: meta } : {}),
   } as SessionUpdate;
@@ -333,10 +353,18 @@ export function extractTranscriptTodos(
   resultDisplay: unknown,
   args?: Readonly<Record<string, unknown>>,
 ): TranscriptTodoItem[] | null {
-  const fromDisplay = extractTodosFromDisplay(resultDisplay);
+  return extractTranscriptTodoPlan(resultDisplay, args)?.todos ?? null;
+}
+
+export function extractTranscriptTodoPlan(
+  resultDisplay: unknown,
+  args?: Readonly<Record<string, unknown>>,
+): TranscriptTodoPlan | null {
+  const fromDisplay = extractTodoPlanFromDisplay(resultDisplay);
   if (fromDisplay) return fromDisplay;
+  if (resultDisplay !== null && resultDisplay !== undefined) return null;
   return args && Array.isArray(args['todos'])
-    ? normalizeTodos(args['todos'])
+    ? { todos: normalizeTodos(args['todos']) }
     : null;
 }
 
@@ -777,12 +805,13 @@ class DefaultTranscriptReplayMachine implements TranscriptReplayMachine {
 
     const resultDisplay = result?.['resultDisplay'];
     if (toolName === 'todo_write') {
-      const todos = extractTranscriptTodos(resultDisplay);
-      if (todos) {
+      const plan = extractTranscriptTodoPlan(resultDisplay);
+      if (plan) {
         yield emit(
-          createTranscriptPlanUpdate(todos, this.usage, {
+          createTranscriptPlanUpdate(plan.todos, this.usage, {
             ...meta,
             planToolCallId: callId,
+            todoPlanId: plan.planId,
           }),
         );
       }
@@ -1334,10 +1363,15 @@ function extractToolResultCallId(
   return undefined;
 }
 
-function extractTodosFromDisplay(value: unknown): TranscriptTodoItem[] | null {
+function extractTodoPlanFromDisplay(value: unknown): TranscriptTodoPlan | null {
   if (isObjectRecord(value) && value['type'] === 'todo_list') {
     return Array.isArray(value['todos'])
-      ? normalizeTodos(value['todos'])
+      ? {
+          ...(typeof value['planId'] === 'string'
+            ? { planId: value['planId'] }
+            : {}),
+          todos: normalizeTodos(value['todos']),
+        }
       : null;
   }
   if (typeof value !== 'string') return null;
@@ -1346,7 +1380,12 @@ function extractTodosFromDisplay(value: unknown): TranscriptTodoItem[] | null {
     return isObjectRecord(parsed) &&
       parsed['type'] === 'todo_list' &&
       Array.isArray(parsed['todos'])
-      ? normalizeTodos(parsed['todos'])
+      ? {
+          ...(typeof parsed['planId'] === 'string'
+            ? { planId: parsed['planId'] }
+            : {}),
+          todos: normalizeTodos(parsed['todos']),
+        }
       : null;
   } catch {
     return null;
@@ -1370,6 +1409,10 @@ function normalizeTodos(values: readonly unknown[]): TranscriptTodoItem[] {
         ...(typeof value['id'] === 'string' ? { id: value['id'] } : {}),
         content: value['content'],
         status,
+        ...(Array.isArray(value['blockedBy']) &&
+        value['blockedBy'].every((dependency) => typeof dependency === 'string')
+          ? { blockedBy: value['blockedBy'] as string[] }
+          : {}),
       },
     ];
   });

packages/cli/src/acp-integration/session/Session.test.ts

@@ -16392,6 +16392,50 @@ describe('Session', () => {
       };
     }
 
+    it('publishes a persisted Todo plan when cancellation races completion', async () => {
+      const controller = new AbortController();
+      const execute = vi.fn().mockImplementation(async () => {
+        controller.abort();
+        return {
+          llmContent: 'updated',
+          returnDisplay: {
+            type: 'todo_list',
+            planId: 'plan-1',
+            todos: [{ id: '1', content: 'Ship', status: 'pending' }],
+          },
+        };
+      });
+      mockToolRegistry.getTool.mockReturnValue(
+        mockAllowedTool(core.ToolNames.TODO_WRITE, execute),
+      );
+
+      await (session as unknown as ToolCallInternals).runToolCalls(
+        controller.signal,
+        'prompt-cancelled-todo',
+        [
+          {
+            id: 'todo-call',
+            name: core.ToolNames.TODO_WRITE,
+            args: { todos: [{ id: '1', content: 'Ship', status: 'pending' }] },
+          },
+        ],
+      );
+
+      expect(mockClient.sessionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: 'plan',
+            entries: [
+              expect.objectContaining({
+                content: 'Ship',
+                _meta: { qwenTodo: { id: '1' } },
+              }),
+            ],
+          }),
+        }),
+      );
+    });
+
     it('lets normalized tool images select a full-turn model', async () => {
       const execute = vi.fn().mockResolvedValue({
         llmContent: [
@@ -19390,6 +19434,26 @@ describe('Session', () => {
       ).toBe(false);
     });
 
+    it('does not publish rejected Todo arguments as a live plan', async () => {
+      const execute = installPendingTodoTool();
+      execute.mockResolvedValue({
+        llmContent: 'Failed to modify todos',
+        returnDisplay:
+          'Error writing todos: Todo dependency graph contains a cycle',
+      });
+      queuePendingTodoThenNaturalStops();
+
+      await runGuardPrompt();
+
+      expect(
+        vi
+          .mocked(mockClient.sessionUpdate)
+          .mock.calls.some(
+            ([params]) => params.update.sessionUpdate === 'plan',
+          ),
+      ).toBe(false);
+    });
+
     it('preserves feature-off Stop hook loop reporting before token rejection', async () => {
       mockConfig.getSessionTokenLimit = vi.fn().mockReturnValue(100);
       mockConfig.getStopHookBlockingCap = vi.fn().mockReturnValue(3);