Files
PaperClipAI/packages/paperclip-runner/src
DottaandClaude Opus 5.5 681af53fa6 fix(runner): ask once more for a text answer when a turn that did tool work ends empty twice (#21359)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner drives OpenCode turns and decides when a turn has a final
answer
> - A turn can do real tool work and then end with no text and no
completion call
> - The driver asks once for a final response. That request can also
come back empty, and then the run fails
> - The person then sees a failed run, although the requested work was
saved
> - This pull request adds one bounded request, text answer first, for a
turn that already did tool work
> - The benefit is that finished work gets a reply instead of a failed
run

## Linked Issues or Issue Description

**What happened?**
An agent saved a requested document with a tool. Its next response had
no text and no completion call. The driver asked once for a final
response, and that response was empty too. The run failed with
`opencode_empty_response` and showed a failure message to the person.

**Expected behavior**
When the work is done, the person gets a short final answer. An empty
response is a recoverable state, not a hard failure.

**Steps to reproduce**
1. Use an OpenCode agent on an OpenRouter model.
2. Ask it to write and save a plan document.
3. Let the provider host return an empty response after the save, and
again for the correction.
4. See the run fail although the document exists.

**Paperclip version or commit**
`master` at ff971149c2.

**Agent adapter(s) involved**
OpenCode through the native Runner.

**Additional context**
The model answered with only a completion tool call, and the serving
host returned no text and no tool call. The correction asked for the
same tool call, so it was lost again. The turn had no other recovery.

## What Changed

- `OpenCodeServerDriver`: when a turn already did tool work and the
correction comes back empty, the driver sends one more request. That
request asks for a short plain-text answer first and the completion call
after it. The text does not depend on tool-call delivery, so a chat
reply arrives even if the host drops the call again. An execution task
still gets its completion call.
- A turn makes at most two correction requests. A turn without tool work
keeps the existing single correction.
- Only tool work that the active turn reports counts. A late tool update
from an earlier turn does not earn an extra request.
- The final failure message now says how many corrections ran.
- The driver emits a separate diagnostic,
`opencode_empty_response_text_correction`, for the second request.
- `empty-response.test.ts`: two new cases from the recorded failure. One
case answers on the plain-text request and completes. One case stays
empty and fails after exactly three prompts. One case sends a late tool
update from an earlier turn and keeps the single correction.

## Verification

- `cd packages/paperclip-runner && npx vitest run
src/drivers/opencode/empty-response.test.ts
src/drivers/opencode/interrupt-empty-response.test.ts
src/drivers/opencode/interrupt-pending-tool-call.test.ts
src/drivers/opencode/output-limit.test.ts` passes. All 19 OpenCode
driver test files pass (241 tests).
- Red/green: with the driver change removed, `tool-work-text` and
`tool-work-empty` fail. With a gate that counts any tool update,
`stale-tool-work` fails. With the change, both pass.
- The existing `empty-again` case (no tool work) still fails after two
prompts, so the bound is unchanged for that case.
- `npx tsc --noEmit -p packages/paperclip-runner` passes.

Latency:
- The change runs only after an empty response. It adds no work before
the turn starts and no work on a turn with a normal answer. Boot time
and time to first token do not change.
- On the recovery path, it adds one short model request. In the recorded
failure, one correction request took about 2.4 s.

## Risks

- Low risk. The extra request is bounded to one per turn and only after
tool work.
- In a chat, a text answer without a completion call uses the existing
chat-reply path.
- An execution task needs its completion call. If the host drops that
call again, the run fails as it did before this change, and the existing
failed-turn continuation resumes it. This change does not make that case
worse.

> 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, model ID `claude-opus-5-5`, used through Claude Code
with tool use (shell, file edits) and extended reasoning.

## 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-13 06:57:33 -06:00
..
…