Review Activity (chat and terminal) against current provider docs #144

Summary

Review the Activity feature (the Subagents and Background tasks surfaces, the dock, and targeted Stop) for structured chats and provider terminals across Claude, Codex, OpenCode and Cursor. Compare each provider adapter with that provider's current official docs, fix what drifted, and file follow-ups for improvements.

A first pass on 2026-10-19 is recorded below. It checked the official docs and the locally installed CLIs: Claude Code 2.1.303, Codex 0.163.0 (app-server schema generated locally), OpenCode 2.0.32, and Cursor Agent 2026.10.16. Line numbers are at 0b98d0a4 (v0.10.1).

Scope

• Server: apps/server/src/activity/, apps/server/src/provider/{claude,codex,opencode,cursor}/, and apps/server/src/provider_terminal/.
• Client: packages/client-runtime/src/state/activity*.ts and apps/web/src/components/activity/.
• Docs: docs/architecture/activity-observation.md (the provider matrix at :441-444), docs/providers/*.md, and docs/user/workspace-ui.md ("Activity and targeted Stop").
• UI follow-up already filed: Activity dock: always visible, opens the Activity panel on click #143 (dock always visible, opens the panel on click).

Findings from the first pass

Claude Code

1. The activity probe trusts --help. Hook activity is enabled only when --help lists --include-hook-events and --forward-subagent-text (docs/providers/claude.md, "Activity observation"). The CLI reference now warns that "claude --help does not list every flag, so a flag's absence from --help does not mean it is unavailable." Version 2.1.303 still lists both, but a help-text change would silently turn Activity off.

   • Consider documented minimum versions instead: --forward-subagent-text needs v2.1.211, and forwarding at every nesting depth needs v2.1.219.
   • system/init capabilities (v2.1.205+) is the documented feature-detection channel, but it lists no capability for these flags today.

2. Claude background work is not shown. Claude Code now reports:

   • background Bash commands and Monitor watches as tasks with task_type: "local_bash";
   • background subagents with is_backgrounded;
   • the full live set in system/background_tasks_changed (v2.1.203+);
   • task_updated with pending, running, completed, failed or killed;
   • task_notification with completed, failed or stopped.

   BiBCode reads these only to track turn follow-ups (apps/server/src/provider/claude/runtime.rs:1477-1510). Activity declares "No background-work capability" for Claude, and the controller fails closed on any task_type other than local_agent or remote_agent. Candidate: a Claude Background tasks section, with Stop through the existing stop_task path.

3. Lineage and repeated runs.

   • parent_task_id names the subagent that launched a task, and spawn_depth gives the nesting level (Agent SDK v0.3.292+ and v0.3.238+).
   • run_id separates runs of one task. A resumed subagent keeps its task_id, gets a new run_id and a new tool_use_id, and its messages keep the original parent_tool_use_id. The docs say to match messages to task events by agent_id, not by tool-use IDs.
   • BiBCode reads none of run_id, parent_task_id or spawn_depth. It correlates on the tool_use_id chain plus hooks.
   • Check how a resumed subagent appears and whether it stays controllable. Consider replacing the nested-reparenting fallback with the documented parent_task_id.

4. Ambient tasks. Tasks with ambient: true "aren't part of the session's work" and should be left out of activity indicators. Only the follow-up tracker filters them today. Confirm the Activity projection never shows them.

5. Forked skills run like subagents. A skill started with the Skill tool reports parent_tool_use_id set to the Skill call. A /skill passed as the prompt uses a forked-command- prefix and arrives after it finishes. Correlation recognises only Agent and legacy Task invocations. Decide whether forked skills should appear, and how.

6. Agent teams. Hook agent_id also identifies in-process teammates. Tasks launched by a teammate have no parent_task_id. New hook events include TeammateIdle, TaskCreated, TaskCompleted and PostToolBatch. Make sure teammates are not misreported as subagents, and decide whether to show them.

Codex (app-server 0.163.0)

7. Every method BiBCode calls exists in the 0.163 schema. However, thread/backgroundTerminals/list and the subAgentActivity item appear only in the experimental schema (generate-json-schema --experimental). Confirm BiBCode always negotiates the experimental API, and that Activity degrades truthfully if a release drops them.
8. New in 0.163 (experimental): thread/backgroundTerminals/terminate and thread/backgroundTerminals/clean. Activity offers no Stop for Codex background terminals today, so this is a candidate for targeted Stop. Also review thread/items/list, thread/items/read and thread/loaded/list for recovery.
9. docs/providers/codex.md notes that 0.146 omitted spawned children from thread/list. Recheck with 0.163, since thread/list now filters by source and cwd.

OpenCode (2.0.32)

10. The endpoints BiBCode uses are documented on the server page:

    • GET /session/:id/children;
    • GET /session/status;
    • GET and POST /session/:id/message;
    • POST /session/:id/abort;
    • GET /event.

    The page doesn't describe OpenCode 2 changes, so verify them against the OpenAPI spec (/doc) of the installed 2.0.x. The matrix also says the terminal path skips later child, status and message failures without downgrading its full claim. Confirm that is intended.

Cursor (Agent 2026.10.16)

11. Activity is "Unsupported in v2" for Cursor (activity-observation.md:444). Cursor has since added two things:

    • The ACP server sends a cursor/task notification on subagent task completion, with description, prompt, subagentType, an optional agentId and durationMs.
    • CLI subagents can run in the background (is_background), writing their state under ~/.cursor/subagents/.

    BiBCode handles cursor/ask_question, cursor/create_plan and cursor/update_todos, but not cursor/task (apps/server/src/provider/cursor/runtime.rs). Candidate: Cursor subagents in structured chat, with completion-only records to start. Provider terminals stay unsupported until Cursor documents a live signal.

Cross-cutting (from activity-observation.md)

12. Terminal-state monotonicity differs between the Codex tracker, the repository and the client reducer. The client can keep showing a terminal summary until a later snapshot replaces it. Decide whether to align them.
13. Teardown differs: the Claude terminal observer marks active records interrupted, while Codex and OpenCode observers rely on cancellation and startup cleanup. Check that the UI shows the same thing for each.

Deliverables

• A provider × {chat, terminal} table of the signals used, the doc each relies on, the minimum version, and the status (current, drifted or unused). Store it in docs/architecture/activity-observation.md, replacing the version-free matrix.
• Each finding above confirmed or rejected with evidence: a test, a captured fixture, or a doc quote.
• One follow-up issue per confirmed change, each with focused tests, ranked by user impact.
• Any probe or contract fix that is small and safe (finding 1) done here, with tests.
• docs/providers/*.md and docs/user/workspace-ui.md updated, and the docs/testing/ runbooks reviewed.

Validation

• Capture real stream-json, App Server and ACP fixtures from the versions above, and replay them in the adapters' tests: background Bash and Monitor, a resumed subagent, a forked skill, a Codex background terminal, and a Cursor subagent.
• Run cargo fmt --all --check, Clippy with warnings denied, the affected Rust tests, vp check and vp run typecheck.
• Profiler coverage: any new provider request is registered and, if it waits on the provider, added to is_long_running. Activity payloads stay out of profiler records.

References

• Claude Code: CLI reference, hooks, headless / Follow subagent messages, Agent SDK TypeScript reference (SDKTaskStartedMessage, SDKTaskUpdatedMessage, SDKTaskNotificationMessage, SDKBackgroundTasksChangedMessage)
• Codex: app-server README; codex app-server generate-json-schema --experimental (0.163.0)
• OpenCode: server API
• Cursor: CLI ACP, subagents