mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-10 11:46:36 +01:00
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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed
1 parent
1b0f78100d
commit
22281d4b3a
51 files changed
+2015
-116
No files matched your search
@@ -1593,6 +1593,35 @@ export function continuingPendingInteractionIds(
|
||||
.map((response) => response.interactionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* A planning run can synchronize its completed checklist before the harness's
|
||||
* full proposal arrives. The proposal then supersedes that same-run revision
|
||||
* (its pending review expires as stale); a revision written by anyone else
|
||||
* since the pinned base still fails the revision check.
|
||||
*/
|
||||
async function proposalBaseRevisionId(input: {
|
||||
db: Db;
|
||||
issueId: string;
|
||||
runId: string;
|
||||
pinnedRevisionId: string | null;
|
||||
proposal: boolean;
|
||||
}): Promise<string | null> {
|
||||
if (!input.proposal) return input.pinnedRevisionId;
|
||||
const latest = await documentService(input.db).getIssueDocumentByKey(input.issueId, "plan");
|
||||
if (!latest?.latestRevisionId || latest.latestRevisionId === input.pinnedRevisionId) {
|
||||
return input.pinnedRevisionId;
|
||||
}
|
||||
const latestRevision = await input.db
|
||||
.select({ createdByRunId: documentRevisions.createdByRunId })
|
||||
.from(documentRevisions)
|
||||
.where(eq(documentRevisions.id, latest.latestRevisionId))
|
||||
.limit(1)
|
||||
.then((rows) => rows[0] ?? null);
|
||||
return latestRevision?.createdByRunId === input.runId
|
||||
? latest.latestRevisionId
|
||||
: input.pinnedRevisionId;
|
||||
}
|
||||
|
||||
export async function synchronizeCompletedProviderPlan(input: {
|
||||
db: Db;
|
||||
execution: NativeExecutionInput;
|
||||
@@ -1603,25 +1632,55 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
payload: Record<string, unknown>;
|
||||
};
|
||||
}): Promise<PlanSynchronization | null> {
|
||||
if (
|
||||
input.event.eventType !== "plan.updated" ||
|
||||
input.event.payload.complete !== true
|
||||
)
|
||||
return null;
|
||||
if (
|
||||
!("executionMode" in input.execution) ||
|
||||
input.execution.executionMode !== "plan"
|
||||
)
|
||||
return null;
|
||||
const planningContext = input.execution.planningContext;
|
||||
if (!planningContext) return null;
|
||||
const planId =
|
||||
typeof input.event.payload.planId === "string"
|
||||
const planMode =
|
||||
"executionMode" in input.execution &&
|
||||
input.execution.executionMode === "plan";
|
||||
// A harness's own proposed-plan document (Codex plan item, Claude
|
||||
// ExitPlanMode) asks for approval in any work mode: in Planning it is the
|
||||
// planning deliverable, and in Standard the agent opted to stop and ask.
|
||||
// A within-turn checklist only stands in for the plan in Planning mode.
|
||||
const proposal =
|
||||
input.event.eventType === "plan.proposed" &&
|
||||
input.event.payload.status === "completed";
|
||||
const completedChecklist =
|
||||
input.event.eventType === "plan.updated" &&
|
||||
input.event.payload.complete === true;
|
||||
if (!proposal && !(completedChecklist && planMode)) return null;
|
||||
// Only plan-capable work modes may write the Plan document. Ask and skill
|
||||
// test runs answer in the thread; a proposal there must not become a plan.
|
||||
const workMode = input.execution.task.workMode;
|
||||
if (proposal && workMode !== "standard" && workMode !== "planning") return null;
|
||||
const planningContext =
|
||||
"executionMode" in input.execution && input.execution.executionMode === "plan"
|
||||
? input.execution.planningContext
|
||||
: null;
|
||||
if (planMode && !planningContext) return null;
|
||||
const baseRevisionId = planningContext
|
||||
? await proposalBaseRevisionId({
|
||||
db: input.db,
|
||||
issueId: input.execution.binding.issueId,
|
||||
runId: input.execution.binding.runId,
|
||||
pinnedRevisionId: planningContext.baseRevisionId,
|
||||
proposal,
|
||||
})
|
||||
: ((
|
||||
await documentService(input.db).getIssueDocumentByKey(
|
||||
input.execution.binding.issueId,
|
||||
"plan",
|
||||
)
|
||||
)?.latestRevisionId ?? null);
|
||||
const planId = proposal
|
||||
? typeof input.event.payload.proposalId === "string"
|
||||
? input.event.payload.proposalId
|
||||
: ""
|
||||
: typeof input.event.payload.planId === "string"
|
||||
? input.event.payload.planId
|
||||
: "";
|
||||
const providerRevision = Number.isSafeInteger(input.event.payload.revision)
|
||||
? Number(input.event.payload.revision)
|
||||
: 0;
|
||||
const providerRevision = proposal
|
||||
? 1
|
||||
: Number.isSafeInteger(input.event.payload.revision)
|
||||
? Number(input.event.payload.revision)
|
||||
: 0;
|
||||
const body = providerPlanMarkdown(input.event.payload);
|
||||
const digest = createHash("sha256").update(body).digest("hex");
|
||||
if (!planId || providerRevision < 1 || !body) {
|
||||
@@ -1630,7 +1689,7 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
planId,
|
||||
providerRevision,
|
||||
status: "invalid",
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
digest,
|
||||
documentRevision: null,
|
||||
currentRevisionId: null,
|
||||
@@ -1693,7 +1752,7 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
title: "Plan",
|
||||
format: "markdown",
|
||||
body,
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
changeSummary: provenance,
|
||||
createdByAgentId: input.execution.binding.agentId,
|
||||
createdByRunId: input.execution.binding.runId,
|
||||
@@ -1714,7 +1773,7 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
planId,
|
||||
providerRevision,
|
||||
status: "conflict",
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
digest,
|
||||
documentRevision: latest?.latestRevisionNumber ?? null,
|
||||
currentRevisionId: latest?.latestRevisionId ?? null,
|
||||
@@ -1731,7 +1790,7 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
planId,
|
||||
providerRevision,
|
||||
status: "conflict",
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
digest,
|
||||
documentRevision: current?.latestRevisionNumber ?? null,
|
||||
currentRevisionId: current?.latestRevisionId ?? null,
|
||||
@@ -1739,7 +1798,6 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
};
|
||||
}
|
||||
let confirmationId: string;
|
||||
let confirmationPending = false;
|
||||
try {
|
||||
const confirmation = await issueThreadInteractionService(input.db).create(
|
||||
{
|
||||
@@ -1779,62 +1837,29 @@ export async function synchronizeCompletedProviderPlan(input: {
|
||||
},
|
||||
);
|
||||
confirmationId = confirmation.id;
|
||||
confirmationPending = confirmation.status === "pending";
|
||||
} catch {
|
||||
return {
|
||||
eventId: input.event.sourceEventId,
|
||||
planId,
|
||||
providerRevision,
|
||||
status: "approval_failed",
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
digest,
|
||||
documentRevision: revision.revisionNumber,
|
||||
currentRevisionId: revision.id,
|
||||
confirmationId: null,
|
||||
};
|
||||
}
|
||||
if (confirmationPending) {
|
||||
try {
|
||||
const currentIssue = await input.db
|
||||
.select({ status: issues.status })
|
||||
.from(issues)
|
||||
.where(eq(issues.id, input.execution.binding.issueId))
|
||||
.limit(1)
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (currentIssue && currentIssue.status !== "in_review") {
|
||||
await issueService(input.db).update(input.execution.binding.issueId, {
|
||||
status: "in_review",
|
||||
actorAgentId: input.execution.binding.agentId,
|
||||
});
|
||||
}
|
||||
} catch {
|
||||
const settledIssue = await input.db
|
||||
.select({ status: issues.status })
|
||||
.from(issues)
|
||||
.where(eq(issues.id, input.execution.binding.issueId))
|
||||
.limit(1)
|
||||
.then((rows) => rows[0] ?? null);
|
||||
if (settledIssue?.status !== "in_review") {
|
||||
return {
|
||||
eventId: input.event.sourceEventId,
|
||||
planId,
|
||||
providerRevision,
|
||||
status: "approval_failed",
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
digest,
|
||||
documentRevision: revision.revisionNumber,
|
||||
currentRevisionId: revision.id,
|
||||
confirmationId,
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
// Synchronization runs while the native run still owns the task. Changing
|
||||
// the task status here would revoke the run's execution lease; the pending
|
||||
// confirmation is a governance gate that the run finalizer turns into the
|
||||
// review wait.
|
||||
return {
|
||||
eventId: input.event.sourceEventId,
|
||||
planId,
|
||||
providerRevision,
|
||||
status,
|
||||
baseRevisionId: planningContext.baseRevisionId,
|
||||
baseRevisionId: baseRevisionId,
|
||||
digest,
|
||||
documentRevision: revision.revisionNumber,
|
||||
currentRevisionId: revision.id,
|
||||
|
||||
Reference in new issue
Block a user