Files
PaperClipAI/packages
DottaandClaude Opus 5.5 41b0f76d75 fix(runner): tell a provider its accepted result is final when it reports again (#21984)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A native run reports its result with `paperclip_finish` or
`paperclip_block`, and a turn's first accepted report is final
> - When the model reports again with a different result, the Runner
refuses the second report
> - After a committed blocker, the refusal tells the model to stop and
end the turn (#21959)
> - After a committed done, needs_review or yielded result, the refusal
was only "A different semantic result was already committed", so the
model did not know what to do and tried again
> - Each extra call is one more model request, and the turn holds the
agent's slot until it ends; the task's status commits only when the turn
ends
> - This pull request gives every refused later report a clear, final
message: the result is already accepted, stop calling `paperclip_finish`
and `paperclip_block`, put extra notes in the final response, and end
the turn
> - The benefit is that the model ends the turn after one refusal, so
the slot is free sooner and the task completes sooner

## Linked Issues or Issue Description

**What happened?**
In a restart-chaos wave, an OpenCode agent (DeepSeek through OpenRouter)
finished a task, and the Runner accepted its `done` report. The model
then called `paperclip_finish` again with a different report. The Runner
replied only "A different semantic result was already committed". The
model repeated the call about 79 times over 277 seconds. The agent's
slot stayed busy, and the task's completion was late, because the task
status commits when the turn ends.

**Expected behavior**
After a turn commits any result (done, needs_review, yielded or
blocked), each later report with a different result gets a clear and
final instruction: the result is already accepted, so do not call
`paperclip_finish` or `paperclip_block` again, put any extra notes in
the final response, and end the turn. An identical repeat of the
accepted report stays an idempotent success.

**Steps to reproduce**
1. Start a native OpenCode turn that calls `paperclip_finish` with a
done result.
2. In the same turn, call `paperclip_finish` again with a different
summary, or call `paperclip_block`.
3. On master, the tool error is only "A different semantic result was
already committed", with no instruction to stop.

**Paperclip version or commit**
master 54f8068df4

## What Changed

- `packages/paperclip-runner/src/contracts/completion-result.ts`:
replace the bare `PRP_SEMANTIC_RESULT_CONFLICT_MESSAGE` with
`PRP_RESULT_ALREADY_ACCEPTED_MESSAGE`.
`prpSemanticResultConflictMessage` returns it for every committed result
that is not a blocker. The blocker messages share the same stop
instruction, which now names both `paperclip_finish` and
`paperclip_block`, and ask for extra notes in the final response.
- The OpenCode, Codex and Codex ACPX drivers already return
`prpSemanticResultConflictMessage(...)`, so all three get the new text
with no driver change.
- `packages/paperclip-runner/test/fixtures/fake-opencode-server.mjs`:
add a `finish-after-finish` scenario. After the accepted
`paperclip_finish`, the fake provider sends an identical repeat, a
changed `paperclip_finish` and a late `paperclip_block`.
-
`packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.test.ts`:
a new test checks that the identical repeat succeeds, that both
conflicting reports get the final message, that only one result is
proposed, and that the turn completes.
- `packages/paperclip-runner/src/contracts/completion-result.test.ts`:
unit cases for done, needs_review, yielded and a missing committed
result, and a check that both blocker messages name both tools and say
to end the turn.
- Not in this change: a hard bound that ends the turn after N refused
reports. In the OpenCode driver the only way to stop a provider turn is
`/abort`, which the driver reports as `turn.cancelled`, not
`turn.completed`. A safe bound needs a new terminal path in each driver,
so it is not "small". This change fixes the cause (the message) first.

## Verification

- Red: with the old message, the 4 new `completion-result.test.ts` cases
and the new OpenCode driver test fail (the refusal text does not contain
the stop instruction).
- Green: `npx vitest run src/contracts/completion-result.test.ts
src/drivers/opencode/opencode-server-driver.test.ts` in
`packages/paperclip-runner`: 2 files, 123 tests pass.
- `npx vitest run src/drivers/acpx/codex-acpx-driver.test.ts
src/drivers/codex`: 28 files, 563 tests pass.
- `pnpm --filter @paperclipai/paperclip-runner typecheck` passes.
- `pnpm verify` selected broad coverage (exit 2) because the shared
OpenCode fixture changed. Required CI supplies that coverage.

## Risks

- Low risk. Only the text of a tool error changes. Result admission,
fingerprints and idempotent repeats do not change.
- Mixed versions during a deploy: the Runner creates this text and sends
it straight to the model. The server does not read or match it (no
server, Rust or test code matches the old string). An old server with a
new Runner gets the new text. A new server with an old Runner keeps the
old text. Neither case changes a stored record or a protocol shape.
- ACPX: no ACPX profile, pin, schema or `protocol/` file changes, so no
provider `commandDigest` or pack contract changes.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (shell, file edits, test runs).

## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] 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-17 03:53:12 -06:00
..