Files
PaperClipAI/ui/src/components/task-chat/task-protocol-surfaces.ts
T
DottaandClaude Opus 5.5 22281d4b3a feat(task-chat): approve harness-proposed plans (Codex plan mode, Claude ExitPlanMode) (#19291)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run through the native runner. Codex and Claude Code each
have their own plan mode, and each produces a proposed-plan document.
> - Paperclip already has a planning work mode, an issue `plan`
document, and a `request_confirmation` approval gate for plans.
> - These parts were not connected. The Codex proposed-plan item was
transcript text only. The server path never put Codex into plan mode.
Claude was never put into plan mode, and its ExitPlanMode plan was
dropped. A planning run could close its task as done with no approval.
> - This pull request turns a harness's own proposed plan into the
issue's Plan document and the existing approval gate, for Codex and
Claude.
> - The benefit is that users approve or send back the agent's real plan
from the task chat. Approve resumes the agent. Request changes sends the
reason back to the agent.

## Linked Issues or Issue Description

Refs #19252

**Subsystem affected**
Native runner provider events (Codex and ACPX Claude), the runner Codex
provider (Rust), server native plan synchronization, and the task chat
UI.

**Problem or motivation**
Codex and Claude both produce a proposed-plan document in their native
plan mode. Paperclip did not use it. In live tests on the server path, a
Codex planning run was not in Codex plan mode, saved its own
`implementation-plan` document, and marked the task done without
approval. Claude planning runs were not in Claude plan mode, and the
ExitPlanMode plan text never reached Paperclip.

**Proposed solution**
Add a canonical `plan.proposed` event for a harness's proposed plan. Put
Codex and Claude into their native plan mode for planning runs. Save a
completed proposal as the issue `plan` document with the existing
`request_confirmation` gate. Agents can also propose a plan on a
standard task; the work mode stays standard.

**Alternatives considered**
Reuse `plan.updated`. Its schema is the within-turn checklist and is not
the durable Plan document, so a separate event keeps the two clear.
Stronger prompt text without native plan mode. Live tests showed that
the model kept its own document workflow.

**Roadmap alignment**
This reuses the issue plan document, planning work mode and approval
gate that already exist. It adds one canonical provider event.

## What Changed

- `packages/paperclip-runner/protocol/schemas/*`: add the
`plan.proposed` event (`paperclip.plan.proposed.v1`: `proposalId`,
`status`, `markdown` up to 60k characters, `source`). Regenerate the
schema bundle, validators and manifest.
- `packages/paperclip-runner/src/provider-events.ts`: map the Codex
`plan` item and a `<proposed_plan>` block in a completed Codex message
to `plan.proposed`. Add `claudePlanProposalEvent`.
-
`packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs`:
send Codex's native `collaborationMode: plan` on `turn/start` for a
read-only (planning) Codex run. Before this change the server path never
sent it.
- `runner-core/src/acpx_event_payload.rs`: admit `plan.proposed` as ACPX
rich display activity.
- `drivers/acpx/codex-runtime-adapter.ts`: set Claude Code to native
plan mode for a read-only run. Capture Claude's ExitPlanMode plan from
its permission request, record it, and decline the native "Ready to
code?" prompt.
- `drivers/acpx/codex-acpx-driver.ts`, `cli/acpx-runtime-sidecar.ts`:
emit the captured proposal as a rich event. Complete that turn instead
of reporting it as cancelled.
- `backends/codex-native-backend.ts`: per-harness plan-mode
instructions, and a short opt-in hint for Claude on standard tasks.
- `server/src/services/native-runtime/native-session-executor.ts`:
synchronize a completed `plan.proposed` into the `plan` document and a
`request_confirmation` in planning and standard mode. Do not change the
issue status during the run (that revoked the run's lease). The run
finalizer turns the pending confirmation into the review wait.
- `server/src/services/heartbeat-run-summary.ts`: keep a
`<proposed_plan>` block out of the posted reply.
- UI: new `plan_proposal` provider family. The task chat shows a live
"Writing plan" card while a proposal streams and a one-line record when
it completes. Resolved plan reviews keep a receipt ("Approved Plan v1",
"Requested changes to Plan v1: reason"). Plan previews skip section
headings.
- Storybook: `Tasks and conversations/.../Task chat/Proposed plan
approval` shows the journey.
- `doc/SPEC-implementation.md`: describe harness-proposed plan approval.

## Verification

- `cargo test -p paperclip-runner-core --lib` (new:
`read_only_codex_turns_use_native_plan_collaboration_mode`)
- `cd packages/paperclip-runner && npx vitest run
src/provider-events.test.ts
src/drivers/acpx/codex-runtime-adapter.test.ts`
- `cd server && npx vitest run
src/__tests__/native-plan-proposal-sync.test.ts
src/__tests__/heartbeat-run-summary.test.ts`
- `cd ui && npx vitest run
src/components/transcript/native-run-events.test.ts
src/components/task-chat`
- Live test on a local worktree instance with real harnesses:
- Codex (`gpt-5.6-sol`), planning task: Codex asked one question, then
produced a native plan item. The task showed Plan v1 with Approve plan /
Request changes and moved to in review. Approve changed the work mode to
standard. Codex then implemented the plan and its tests passed.
- Codex, Request changes with a reason: Codex woke in planning mode and
produced Plan v2 that includes the change.
- Claude (`claude-opus-5-5`), planning task: Claude was in plan mode.
ExitPlanMode became Plan v1 and the turn completed. Approve resumed
Claude in standard mode, and Claude implemented the plan.
- Claude, standard task that asks for a plan first: Claude stopped
before code changes and asked for plan approval. The work mode stayed
standard.
- Storybook: open `Proposed plan approval` and check each stage.

## Risks

- Codex planning runs now really use Codex plan mode on the server path.
Codex can ask a clarifying question before it proposes. This matches
Codex plan mode.
- Claude planning runs now use Claude plan mode. A declined ExitPlanMode
ends the Claude turn; the runner reports it as completed. Claude's tool
row for that request records a rejection from Claude's side.
- Codex does not stream the proposed plan on the server path yet, so the
live card shows a placeholder until the plan completes.
- A `<proposed_plan>` block in any completed Codex message on a standard
task now asks for approval. This is the documented opt-in path.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with
tool use (shell, file edits, browser). Long context. No extended
thinking mode was used.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 20:53:33 +00:00

146 lines
9.1 KiB
TypeScript

/**
* Exhaustive product disposition for Paperclip Runner Protocol surfaces.
*
* This is intentionally separate from the renderer: adding a protocol event
* must be a conscious product decision even when the decision is to fold it
* into an existing turn or keep it in DevTools. The contract test compares
* these keys with the canonical JSON schemas.
*/
export type TaskProtocolDisposition = "inline" | "folded" | "debug-only";
export interface TaskProtocolSurfaceRegistration {
disposition: TaskProtocolDisposition;
surface: string;
story: string | null;
rationale: string;
}
const inline = (surface: string, story: string, rationale: string): TaskProtocolSurfaceRegistration => ({
disposition: "inline",
surface,
story,
rationale,
});
const folded = (surface: string, rationale: string): TaskProtocolSurfaceRegistration => ({
disposition: "folded",
surface,
story: null,
rationale,
});
const debugOnly = (surface: string, rationale: string): TaskProtocolSurfaceRegistration => ({
disposition: "debug-only",
surface,
story: null,
rationale,
});
const providerEvents = [
"plan.updated", "plan.proposed",
"tool.execution.started", "tool.execution.progressed", "tool.execution.completed",
"research.started", "research.progressed", "research.completed",
"delegation.started", "delegation.updated", "delegation.completed",
"model.route.changed", "model.verification.updated", "context.compacted",
"artifact.viewed", "artifact.generated", "review.mode.changed",
"hook.started", "hook.completed", "memory.citation.referenced",
"safety.review.started", "safety.review.completed", "terminal.input.sent",
"wait.started", "wait.completed", "provider.notice.recorded",
] as const;
const runnerLifecycleEvents = [
"runner.connected", "runner.reconnected", "runner.reconciled", "runner.disconnected",
"runner.draining", "runner.backpressure", "runner.suspending", "runner.suspended", "runner.stopped",
"runtime.phase.changed", "workspace.ready",
"harness.starting", "harness.ready", "harness.exited",
"session.starting", "session.started", "session.resuming", "session.resumed",
"session.reconciled", "session.updated", "session.closed",
"turn.submitted", "turn.accepted", "turn.started", "turn.completed",
"run.attached", "run.detached",
] as const;
const diagnosticEvents = [
"runner.diagnostic", "harness.diagnostic", "session.failed", "turn.failed",
"turn.interrupted", "turn.cancelled", "item.failed",
] as const;
const itemEvents = ["item.started", "item.delta", "item.completed", "usage.reported"] as const;
const mcpLifecycleEvents = [
"mcp_app.discovered", "mcp_app.resource.resolved", "mcp_app.initializing", "mcp_app.ready",
"mcp_app.host_context.changed", "mcp_app.failed", "mcp_app.teardown",
] as const;
const interactionLifecycleEvents = [
"interaction.request.proposed", "interaction.request.materialized", "interaction.request.rejected",
"interaction.response.progressed", "interaction.response.resolved", "interaction.response.delivered",
] as const;
const governanceEvents = [
"attention.request.proposed", "attention.request.routed", "attention.request.resolved",
"attention.request.expired", "attention.request.superseded", "work.assessment.recorded",
"issue.status.decision.recorded", "issue.status.decision.applied", "issue.status.decision.rejected",
"issue.status.decision.superseded",
] as const;
export const TASK_PROTOCOL_EVENT_SURFACE_REGISTRY: Readonly<Record<string, TaskProtocolSurfaceRegistration>> = Object.freeze({
...Object.fromEntries(providerEvents.map((eventType) => [eventType, inline("provider_activity", "Task Page/Runner Protocol/Provider semantics", "Provider-neutral semantic activity is readable in the task turn.")])),
"workspace.change.updated": inline("workspace_change", "Task Page/Runner Protocol/Workspace changes", "In-progress workspace changes update one diff card."),
"workspace.diff.recorded": inline("workspace_change", "Task Page/Runner Protocol/Workspace changes", "The runner-verified final diff replaces the in-progress revision."),
"workspace.file.referenced": inline("workspace_file", "Task Page/Runner Protocol/File references", "Verified references open a bounded preview and the production file viewer."),
"semantic_tool.input": folded("tool", "Semantic operations reuse the production tool row."),
"semantic_tool.result": folded("tool", "Semantic operation outcomes update the matching tool row."),
"semantic_tool.reconciled": folded("tool", "Recovered semantic operation outcomes update the matching tool row without duplicating it."),
"mcp_app.tool_input": folded("tool", "MCP inputs reuse the production tool row."),
"mcp_app.tool_result": folded("tool", "MCP outcomes update the matching tool row."),
"mcp_app.action.requested": folded("interaction", "Action requests materialize as authoritative issue-thread interactions."),
"mcp_app.action.resolved": folded("interaction", "Action resolution is shown on the authoritative interaction card."),
"runtime_request.created": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Pending provider runtime requests remain visible and actionable when a resolver is available."),
"runtime_request.resolved": folded("runtime_request", "Resolution updates the existing request card."),
"runtime_request.expired": folded("runtime_request", "Expiry updates the existing request card."),
"runtime_request.cancelled": folded("runtime_request", "Cancellation updates the existing request card."),
...Object.fromEntries(interactionLifecycleEvents.map((eventType) => [eventType, folded("interaction", "The control-plane interaction record is canonical and owns rendering." )])),
"run.result.proposed": inline("run_result", "Task Page/Runner Protocol/Results and terminal states", "Structured completion, evidence, verification, blockers, and artifacts remain inspectable."),
"run.result.accepted": folded("run_result", "Acceptance updates the existing result without duplicating it."),
"run.result.rejected": folded("run_result", "Rejected results remain part of run governance rather than a second completion card."),
"run.terminal": inline("run_terminal", "Task Page/Runner Protocol/Results and terminal states", "Terminal outcome and stop reason remain visible."),
...Object.fromEntries(runnerLifecycleEvents.map((eventType) => [eventType, folded("turn", "Routine lifecycle transitions are summarized by the run turn and composer state.")])),
...Object.fromEntries(diagnosticEvents.map((eventType) => [eventType, folded("system_notice", "Actionable failure text is folded into the run or system notice.")])),
...Object.fromEntries(itemEvents.map((eventType) => [eventType, folded("conversation_or_tool", "Item payloads normalize into messages, reasoning, tools, diffs, or usage." )])),
"runtime.activity.recorded": folded("task_panel", "The activated plugin view appears in the task side panel."),
"auth.credentials.updated": debugOnly("run_debug", "Credential updates notify the host and remain in run details."),
"sandbox.metric": debugOnly("run_debug", "Sandbox telemetry is available in run details, not the primary task thread."),
...Object.fromEntries(mcpLifecycleEvents.map((eventType) => [eventType, debugOnly("run_debug", "MCP application transport lifecycle remains in run details unless it produces an actionable failure.")])),
...Object.fromEntries(governanceEvents.map((eventType) => [eventType, folded("governance", "Authoritative task status, attention, and interaction records own this state." )])),
});
export const TASK_PROTOCOL_REQUEST_SURFACE_REGISTRY = Object.freeze({
"runtime.permission": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Permission choices render on the runtime request card."),
"runtime.input": inline("runtime_request", "Task Page/Runner Protocol/Runtime requests", "Structured runtime input renders on the runtime request card."),
"issue_thread.request_confirmation": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production confirmation card."),
"issue_thread.request_checkbox_confirmation": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production bounded checkbox card."),
"issue_thread.request_item_verdicts": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production per-item verdict card."),
"issue_thread.ask_user_questions": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production typed question controls."),
"issue_thread.suggest_tasks": inline("interaction", "Task Page/Runner Protocol/Interactions", "Uses the production task suggestion tree."),
});
export const TASK_PROTOCOL_RESULT_DISPOSITION_REGISTRY = Object.freeze({
done: "run_result",
blocked: "run_result",
needs_review: "run_result",
yielded: "run_result",
} as const);
export const TASK_PROTOCOL_TURN_TERMINAL_REGISTRY = Object.freeze({
completed: "run_terminal",
failed: "run_terminal",
interrupted: "run_terminal",
cancelled: "run_terminal",
} as const);
export const TASK_PROTOCOL_RUN_TERMINAL_REGISTRY = Object.freeze({
succeeded: "run_terminal",
failed: "run_terminal",
cancelled: "run_terminal",
} as const);