Files
PaperClipAI/ui/src/components/task-chat/TaskChatPlanPreviewCard.tsx
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

198 lines
8.1 KiB
TypeScript

import type { IssueDocument } from "@paperclipai/shared";
import { FileText, Lightbulb, Maximize2 } from "lucide-react";
import { cn } from "@/lib/utils";
import { SidebarDocumentLink } from "@/components/SidebarDocumentLink";
import { buildDocumentAnnotationHash } from "@/lib/document-annotation-hash";
import { useCoordinatorPresentation } from "@/components/coordinator/CoordinatorPresentation";
import { useTaskChatShimmer } from "./TaskChatShimmer";
import type { TaskChatProviderActivityItem } from "./task-chat-model";
const PLAN_PREVIEW_LINE_COUNT = 3;
export function planPreviewContent(markdown: string) {
const lines = markdown
.split("\n")
.map((line) => line.trim())
.filter(Boolean);
const headingIndex = lines.findIndex((line) => /^#\s+/.test(line));
const title = headingIndex >= 0
? lines[headingIndex]!.replace(/^#\s+/, "").trim()
: "Plan";
const preview = lines
// Section headings ("## Steps") are structure, not plan content.
.filter((line, index) => index !== headingIndex && !/^#{1,6}\s+/.test(line) && !/^(```|~~~|---+$|\*\*\*+$|___+$)/.test(line))
.map((line) => line
.replace(/^#{1,6}\s+/, "")
.replace(/^[-*+]\s+/, "")
.replace(/^\d+[.)]\s+/, "")
.replace(/^>\s*/, "")
.replace(/`([^`]+)`/g, "$1")
.replace(/\*\*([^*]+)\*\*/g, "$1")
.replace(/__([^_]+)__/g, "$1")
.replace(/\[([^\]]+)]\([^)]*\)/g, "$1")
.trim())
.filter(Boolean)
.slice(0, PLAN_PREVIEW_LINE_COUNT);
return { title, preview };
}
export type TaskChatPlanPreviewSource =
| {
kind: "saved";
document?: IssueDocument | null;
revision?: number | null;
fallbackTitle?: string | null;
}
| {
kind: "live";
activity: TaskChatProviderActivityItem;
};
export interface TaskChatPlanPreviewCardProps {
source: TaskChatPlanPreviewSource;
href?: string | null;
ariaLabel?: string;
testId?: string;
className?: string;
}
function livePlanContent(activity: TaskChatProviderActivityItem) {
// A proposed-plan document streams as markdown; a checklist streams as steps.
if (activity.output?.trim()) {
const fromMarkdown = planPreviewContent(activity.output);
if (fromMarkdown.title !== "Plan" || fromMarkdown.preview.length > 0) return fromMarkdown;
}
const title = activity.title.trim() && activity.title.trim().toLowerCase() !== "plan"
? activity.title.trim()
: "Plan";
const preview = activity.steps
.map((step) => step.label.trim())
.filter(Boolean)
.slice(0, PLAN_PREVIEW_LINE_COUNT);
if (preview.length === 0 && activity.summary?.trim()) preview.push(activity.summary.trim());
return { title, preview };
}
function planRevision(source: TaskChatPlanPreviewSource): number | null {
if (source.kind === "saved") {
return source.revision ?? source.document?.latestRevisionNumber ?? null;
}
const detail = source.activity.details.find(({ label }) =>
label === "Revision" || label === "Document Revision",
);
if (!detail) return null;
const revision = Number.parseInt(detail.value, 10);
return Number.isFinite(revision) ? revision : null;
}
export function TaskChatPlanPreviewCard({
source,
href = source.kind === "saved" ? "#document-plan" : null,
ariaLabel,
testId = "task-chat-plan-preview",
className,
}: TaskChatPlanPreviewCardProps) {
const coordinator = useCoordinatorPresentation();
const shimmer = useTaskChatShimmer(source.kind === "live" ? source.activity.id : "saved-plan");
const revision = planRevision(source);
const content = source.kind === "saved" && source.document
? planPreviewContent(source.document.body)
: source.kind === "saved"
? { title: source.fallbackTitle?.trim() || "Plan", preview: [] as string[] }
: livePlanContent(source.activity);
const live = source.kind === "live";
if (coordinator) {
const document = source.kind === "saved" ? source.document : null;
const targetHref = href === "#document-plan" && document
? `/issues/${document.issueId}${buildDocumentAnnotationHash({ documentKey: document.key,
revisionId: document.latestRevisionId ?? undefined, threadId: null, commentId: null })}`
: href;
const compactClassName = cn("inline-flex max-w-full items-center gap-2 rounded-lg border border-border bg-muted/25 px-3 py-2.5 text-sm text-muted-foreground",
targetHref && "transition-colors hover:bg-muted/40 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className);
const compactBody = <><FileText className="size-4 shrink-0" aria-hidden /><span className="shrink-0">{live ? "Writing" : "Open"}</span>{" "}
<span className={cn("min-w-0 truncate text-foreground", targetHref && "underline underline-offset-4", live && shimmer && "shimmer-text shimmer-text-muted")}>{content.title}</span>
{targetHref ? <span className="hidden shrink-0 sm:inline">{" "}in the sidebar</span> : null}</>;
return targetHref ? <SidebarDocumentLink href={targetHref} testId={testId}
ariaLabel={ariaLabel ?? `Open ${content.title}${revision == null ? "" : ` revision ${revision}`} in task sidebar`} className={className}>
<span className="shrink-0">Open</span>{" "}<span className="min-w-0 truncate text-foreground underline underline-offset-4">{content.title}</span>
<span className="hidden shrink-0 sm:inline">{" "}in the sidebar</span>
</SidebarDocumentLink>
: <section data-testid={testId} aria-label={ariaLabel ?? "Writing plan"} className={compactClassName}>{compactBody}</section>;
}
const headerDetail = revision == null
? null
: `rev ${revision}`;
const body = (
<>
<div className="flex items-center gap-2 border-b border-border/70 px-3 py-2.5 text-sm text-muted-foreground">
<Lightbulb
aria-hidden
className={cn("h-4 w-4 shrink-0", live && "text-(--status-agent-running)")}
/>
<span className={cn("font-medium", live && shimmer && "shimmer-text shimmer-text-muted")} data-testid={live ? "task-chat-plan-streaming-status" : undefined}>
{live ? "Writing plan" : "Plan"}
</span>
{headerDetail ? (
<span
className="text-xs"
>
· {headerDetail}
</span>
) : null}
{href ? (
<Maximize2
aria-hidden
className="ml-auto h-4 w-4 transition-transform group-hover:scale-105 group-hover:text-foreground"
/>
) : null}
</div>
<div className="relative max-h-36 overflow-hidden px-4 py-3">
<h3 className="text-base font-semibold leading-6 text-foreground">{content.title}</h3>
{content.preview.length > 0 ? (
<ul className="mt-2 space-y-1.5 text-sm leading-5 text-muted-foreground">
{content.preview.map((line, index) => (
<li key={`${index}-${line}`} className="flex gap-2">
<span aria-hidden className="shrink-0 text-muted-foreground/60">•</span>
<span className="line-clamp-1">{line}</span>
</li>
))}
</ul>
) : (
<p className="mt-1 text-sm text-muted-foreground">
{live ? "Waiting for the first plan step…" : "Open the synchronized plan to review it."}
</p>
)}
<div className="pointer-events-none absolute inset-x-0 bottom-0 h-8 bg-linear-to-b from-transparent to-card/95" />
</div>
</>
);
const sharedClassName = cn(
"group block w-full overflow-hidden rounded-md border border-border bg-muted/25 text-left",
href && "transition-colors hover:border-foreground/25 hover:bg-muted/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
className,
);
if (href) {
return (
<a
href={href}
data-testid={testId}
aria-label={ariaLabel ?? `Open Plan${revision == null ? "" : ` revision ${revision}`}`}
className={sharedClassName}
>
{body}
</a>
);
}
return (
<section
aria-label={ariaLabel ?? "Streaming Plan preview"}
data-testid={testId}
className={sharedClassName}
>
{body}
</section>
);
}