fix(runner): keep closing tool-call tags and model control tokens out of OpenCode chat (#21761)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner OpenCode driver streams model text into the
chat as progress and selects the final reply
> - DeepSeek v4.1 flash (through OpenRouter) wrote tool-call scaffolding
and tokenizer control tokens as ordinary text
> - #21361 hides tool-call markup, but its detector matched only opening
DSML tags, and nothing recognised control tokens
> - A person saw raw `</|DSML| invoke>` lines in a progress message, and
in another conversation got a degenerate reply instead of an answer
> - This pull request extends the same detector to closing DSML tags and
to model control tokens, on the streaming path and at completion
> - The benefit is that scaffolding never reaches the chat, and a
degenerate reply goes to the existing correction instead of being posted

## Linked Issues or Issue Description

Refs #21361

**What happened?**
Chat-eval cohort 16 (OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master 819f61f1fd)
showed two defects.
1. In `task-coordination.block-on-design`, after a real
`paperclip_finish` call, the model streamed a text part that held only
closing tags (`\r\n</|DSML| invoke>\n</|DSML|
calls>…</invoke>\r\n</parameter>`). The driver emitted it as an
`agentMessage` progress delta, so the chat showed raw markup. The cause:
`SENTINEL_FORMS` matched `<|DSML|` but not `</|DSML|`.
2. In `cases.case-history`, the reply to the second follow-up was
`<|begin▁of▁sentence|><?xml version="1.0" …?>\n<output>\nSearch output
truncated. Let me search more specifically…\n</output>`. The driver took
it as the final text part and posted it. The question was never
answered.

**Expected behavior**
Tool-call scaffolding and model control tokens never appear in progress
or in the reply. A reply made only of them goes to the empty-response
correction, which asks the model for the real answer. Real answers,
including answers about XML, chat templates or tool tags, stay as
written.

**Steps to reproduce**
Feed the recorded text parts above to the OpenCode driver (the new
`closing-markup` and `control-token-reply` cases in
`empty-response.test.ts` do this).

## What Changed

- `tool-call-markup.ts`: closing DSML tags (`</|DSML|`, `</|DSML|`)
count as tool-call markup.
- `tool-call-markup.ts`: new `controlTokenStart` finds DeepSeek, ChatML
and Llama control tokens (for example `<|begin▁of▁sentence|>`,
`<|im_start|>`, `<|eot_id|>`) outside code. A new
`visibleBeforeModelScaffolding` holds back both kinds while text
streams.
- Sentinels inside inline code spans are ignored, as fenced code already
was.
- A per-line fast path skips the sentinel scan when a line has no `<|`,
`<|`, `</|` or `</|`.
- `opencode-server-driver.ts`: prose before a control token stays the
answer, with the token removed (for example a trailing end-of-sentence
token). A part with no prose before the token is discarded with the
`opencode_control_token_reply_discarded` diagnostic. The existing
empty-response correction then asks for the answer, with an opening that
names the control tokens. Unlike tool-call markup, this does not make
earlier prose ineligible.

## Verification

- `pnpm vitest run packages/paperclip-runner/src/drivers/opencode/` (20
files, 296 tests pass).
- Red/green: with master's detector and driver, 9 new detector tests and
the `closing-markup` and `control-token-reply` driver cases fail. With
this change they pass.
- The tests use the recorded cohort 16 text. Negative controls: an XML
answer, an answer that names an `<output>` tag, control tokens in inline
code and in a fence, HTML, and comparison operators are left alone. A
driver case checks that `answer.<|end▁of▁sentence|>` keeps the answer
with no correction.
- Per-message cost (local tsx micro-benchmark, 20k calls, one prose line
with `<`): 500 chars 0.3 → 0.8 µs; 2 KB 2.2 → 2.6 µs; 8 KB about 8–16 µs
before and 7–9 µs after (noise range). The detector runs per text-part
update, as before. Nothing runs before the turn starts.
- Paid narrow eval run: results are added in a PR comment.

## Risks

- A real answer that writes a literal control token outside code is cut
at the token. Prose before it stays. That text is never meaningful
prose.
- Closing DSML tags in plain prose (outside code) now hide the rest of
the part. DSML tags are model-internal, so prose does not contain them.

## Model Used

- Claude, `claude-opus-5-5` (Claude Code agent with tool use and code
execution).

## 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
- [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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-15 08:44:00 -06:00
1 parent 56654adecd
commit 348ed0ae10
4 files changed
+234 -33

No files matched your search

@@ -95,7 +95,7 @@ import {
type OpenCodeMcpBridge,
type OpenCodeMcpBridgeOptions,
} from "./mcp-bridge.js";
import { toolCallMarkupStart, visibleBeforeToolCallMarkup } from "./tool-call-markup.js";
import { controlTokenStart, toolCallMarkupStart, visibleBeforeModelScaffolding } from "./tool-call-markup.js";
import {
materializeNativeRuntimeSkills,
releaseMaterializedNativeRuntimeSkills,
@@ -568,6 +568,7 @@ class OpenCodeHarnessSession implements HarnessSession {
#semanticResultProviderMessageId: string | null = null;
#lastNonTerminalToolSourceSeq = 0;
#lastToolCallMarkupSourceSeq = 0;
#lastControlTokenReplySourceSeq = 0;
#usage: Record<string, unknown> | null = null;
#upstreamServed: UpstreamServed | null = null;
readonly #conversationMode: "task" | "prepared";
@@ -707,6 +708,7 @@ class OpenCodeHarnessSession implements HarnessSession {
this.#semanticResultProviderMessageId = null;
this.#lastNonTerminalToolSourceSeq = 0;
this.#lastToolCallMarkupSourceSeq = 0;
this.#lastControlTokenReplySourceSeq = 0;
this.#completedTextPartIds.clear();
this.#completedReasoningPartIds.clear();
this.#reasoningTexts.clear();
@@ -920,7 +922,9 @@ class OpenCodeHarnessSession implements HarnessSession {
? "Your previous response reached the output limit and was discarded as incomplete."
: this.#lastToolCallMarkupSourceSeq > this.#turnStartSourceSeq
? "Your previous response wrote a tool call as plain text, so the tool did not run. Call tools only through the tool-calling interface, never as text."
: "Your response ended without a user-visible final answer or an accepted completion report.";
: this.#lastControlTokenReplySourceSeq > this.#turnStartSourceSeq
? "Your previous response contained raw model control tokens instead of an answer, so it was discarded."
: "Your response ended without a user-visible final answer or an accepted completion report.";
const prompt = attempt === 1
? `${opening} Continue this same request from the work already done. Give the user a concise final answer and submit paperclip_finish (or paperclip_block when blocked) with the current completion contract. Do not repeat completed actions.`
: "Your last response was empty again. Start this response with a short plain-text final answer for the user that says what you did and what, if anything, is left. After that text, submit paperclip_finish (or paperclip_block when blocked) with the current completion contract. Do not repeat completed actions.";
@@ -2210,12 +2214,16 @@ class OpenCodeHarnessSession implements HarnessSession {
// the start of a completed reasoning part, and release it once it differs.
if (partType === "reasoning" && content.trim()) this.#reasoningTexts.set(partId, content.trim());
const reasoningEcho = partType === "text" && this.#echoesReasoning(content, completed);
// Tool-call markup and model control tokens are never prose: hide them
// from progress as they stream, and keep them out of the reply.
const markupStart = partType === "text" && completed ? toolCallMarkupStart(content) : -1;
const controlStart = partType === "text" && completed ? controlTokenStart(content) : -1;
const cut = Math.min(...[markupStart, controlStart].filter(start => start >= 0), content.length);
const visible = partType !== "text"
? content
: completed
? markupStart < 0 ? content : content.slice(0, markupStart)
: visibleBeforeToolCallMarkup(content);
? content.slice(0, cut)
: visibleBeforeModelScaffolding(content);
if (!reasoningEcho) this.#partText.set(partId, visible);
if (partType === "text" && visible.length > 0 && !reasoningEcho) {
for (const reference of paperclipWorkspaceFileReferencesFromText(
@@ -2330,15 +2338,30 @@ class OpenCodeHarnessSession implements HarnessSession {
);
return;
}
// Prose before a control token is the answer (a trailing end-of-turn
// token, say). With no prose before it, the part is degenerate output,
// so the empty-response correction asks for the real answer. Unlike
// tool-call markup it says nothing about earlier prose, which stays
// eligible as the reply.
const answer = controlStart < 0 ? content : content.slice(0, controlStart).trimEnd();
if (!answer.trim()) {
this.#lastControlTokenReplySourceSeq = this.#sourceSequence;
this.#emit(
"harness.diagnostic",
{ code: "opencode_control_token_reply_discarded", message: "OpenCode returned model control tokens instead of an answer; the text was not used as a response." },
{ turnId },
);
return;
}
this.#completedTextParts.push({
partId,
messageId,
text: content,
text: answer,
item: bounded({
...part,
type: "agentMessage",
phase: "final_answer",
text: content,
text: answer,
}),
observedSourceSeq: this.#sourceSequence,
});