Nudge once when assistants print tool-call markup as text

Models sometimes emit <tool_call><function=...> wrappers as
assistant text instead of real tool_call blocks. Catch that narrow
shape, give one corrective nudge per no-real-tool epoch without
counting it as incomplete-report narration, then fall through to the
existing report policy. Thinking blocks and arbitrary XML stay out of
scope; the epoch resets only on genuine tool activity or a parent
follow-up.

Author: TheGreatAxios

src/subagent/nudge-director.test.ts

@@ -84,13 +84,20 @@ function inferenceDone(
 }
 
 function inferenceDoneText(text: string, inputTokens = 0): ReactorInboundEvent {
+  return inferenceDoneContent([{ type: "text", text }], inputTokens);
+}
+
+function inferenceDoneContent(
+  content: readonly Record<string, unknown>[],
+  inputTokens = 0,
+): ReactorInboundEvent {
   return {
     type: "inference.done",
     turn: {
       role: "assistant",
       model: "test",
       timestamp: 0,
-      content: [{ type: "text", text }],
+      content,
     },
     usage: {
       input: inputTokens,
@@ -419,6 +426,107 @@ const REPORT_ENVELOPE = [
   "src/gate.ts",
 ].join("\n");
 
+describe("SubAgentDirector verbatim tool markup recovery", () => {
+  const verbatimToolCall =
+    '<tool_call><function=read_file>{"path":"src/index.ts"}</function></tool_call>';
+
+  test("nudges once for explicit tool-call wrapper text before report policy", async () => {
+    const director = new SubAgentDirector("system", [], undefined, 30);
+    const caps = capabilities();
+
+    const correction = actions(
+      await director.decide(inferenceDoneText(verbatimToolCall), state, caps),
+    );
+    expect(correction).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-verbatim-tool-call-nudge",
+    });
+    expect(ephemeralTexts(inferAction(correction))?.[0]).toContain(
+      "real tool call",
+    );
+
+    const reportNudge = actions(
+      await director.decide(inferenceDoneText(verbatimToolCall), state, caps),
+    );
+    expect(reportNudge).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-incomplete-report-nudge",
+    });
+
+    const stopped = actions(
+      await director.decide(inferenceDoneText(verbatimToolCall), state, caps),
+    );
+    expect(stopped).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-incomplete-report",
+    });
+  });
+
+  test("does not treat arbitrary XML or thinking as verbatim tool calls", async () => {
+    const caps = capabilities();
+    const arbitraryXML = new SubAgentDirector("system", [], undefined, 30);
+    const arbitraryResult = actions(
+      await arbitraryXML.decide(
+        inferenceDoneText("<read_file>src/index.ts</read_file>"),
+        state,
+        caps,
+      ),
+    );
+    expect(arbitraryResult).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-incomplete-report-nudge",
+    });
+
+    const thinkingOnly = new SubAgentDirector("system", [], undefined, 30);
+    const thinkingResult = actions(
+      await thinkingOnly.decide(
+        inferenceDoneContent([
+          { type: "thinking", thinking: verbatimToolCall },
+        ]),
+        state,
+        caps,
+      ),
+    );
+    expect(thinkingResult).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-incomplete-report-nudge",
+    });
+  });
+
+  test("resets correction only after genuine tool activity or parent follow-up", async () => {
+    const director = new SubAgentDirector("system", [], undefined, 30);
+    const caps = capabilities();
+
+    await director.decide(inferenceDoneText(verbatimToolCall), state, caps);
+    const narration = actions(
+      await director.decide(inferenceDoneText("Still working"), state, caps),
+    );
+    expect(narration).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-incomplete-report-nudge",
+    });
+
+    await director.decide(inferenceDone(["read-1"]), state, caps);
+    await director.decide(toolDone("read-1"), state, caps);
+    const afterTool = actions(
+      await director.decide(inferenceDoneText(verbatimToolCall), state, caps),
+    );
+    expect(afterTool).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-verbatim-tool-call-nudge",
+    });
+
+    await director.decide(messageReceived("Try again"), state, caps);
+    const afterFollowup = actions(
+      await director.decide(inferenceDoneText(verbatimToolCall), state, caps),
+    );
+    expect(afterFollowup).toContainEqual({
+      type: "checkpoint",
+      message: "subagent-verbatim-tool-call-nudge",
+    });
+  });
+});
+
 describe("SubAgentDirector incomplete-report wiring", () => {
   test("tool-less narration after tools gets one wrap-up nudge, not a complete", async () => {
     const director = new SubAgentDirector("system", [], undefined, 30);

src/subagent/nudge-director.ts

@@ -47,6 +47,20 @@ const TOOL_FAILURE_RECOVERY_NUDGE =
 const INCOMPLETE_REPORT_NUDGE =
   "Write your final report now using ## Summary, ## Findings, ## Blockers, and ## Paths. Do not narrate status. No more tools unless one lookup is required to cite a line.";
 
+const VERBATIM_TOOL_CALL_NUDGE =
+  "You wrote tool-call markup as assistant text. Invoke the real tool call instead of printing its markup, or write your final report if no tool is needed.";
+
+function hasVerbatimToolCallMarkup(
+  content: readonly { type: string; text?: string }[],
+): boolean {
+  return content.some(
+    (block) =>
+      block.type === "text" &&
+      typeof block.text === "string" &&
+      /<tool_call>\s*<(?:function|tool)=[A-Za-z_][\w.-]*>/.test(block.text),
+  );
+}
+
 function ephemeralNudgeTurn(text: string): ConversationTurn {
   return {
     role: "user",
@@ -128,6 +142,10 @@ export class SubAgentDirector extends DefaultDirector {
   // narration without the envelope salvages as incomplete-report
   // (MAX_TOOLLESS_NARRATION_CYCLES = 2).
   private toolLessNarrationCycles = 0;
+  // One corrective nudge per no-real-tool epoch when the assistant prints
+  // explicit tool-call markup as text instead of issuing a real tool_call.
+  // Cleared only by genuine tool activity or a non-empty parent follow-up.
+  private verbatimToolCallNudgeFired = false;
 
   // Once this leaf has replied with a terminal report (complete envelope or
   // salvage), empty continuations from idle-compact / stall must not fall
@@ -227,6 +245,7 @@ export class SubAgentDirector extends DefaultDirector {
     // A real parent follow-up re-opens the brief; empty continuations do not.
     if (isNonEmptyParentMessage(event)) {
       this.reportReplied = false;
+      this.verbatimToolCallNudgeFired = false;
     }
 
     const afterCompact = this.compaction.resumeAfterCompact(event);
@@ -288,9 +307,28 @@ export class SubAgentDirector extends DefaultDirector {
       this.lastAssistantText = lastText(content);
       const hasToolCalls = content.some((block) => block.type === "tool_call");
       if (hasToolCalls) {
+        this.verbatimToolCallNudgeFired = false;
         this.thrashState = nextThrashState(this.thrashState, content);
       }
 
+      if (
+        !hasToolCalls &&
+        !this.verbatimToolCallNudgeFired &&
+        hasVerbatimToolCallMarkup(content)
+      ) {
+        this.verbatimToolCallNudgeFired = true;
+        this.interventions({
+          id: "verbatim-tool-call",
+          class: "nudge",
+          state: this.interventionState(),
+          detail: "assistant emitted explicit tool-call markup as text",
+        });
+        return [
+          capabilities.checkpoint("subagent-verbatim-tool-call-nudge"),
+          inferWithSubAgentNudge(capabilities, VERBATIM_TOOL_CALL_NUDGE),
+        ];
+      }
+
       const stop = evaluateSubAgentStop({
         hasToolCalls,
         thrashState: this.thrashState,