From f393f50131adc5904b4671de70733d8f64c6384b Mon Sep 17 00:00:00 2001
From: acamq <179265037+acamq@users.noreply.github.com>
Date: Fri, 27 Feb 2026 12:58:05 -0700
Subject: [PATCH] fix(hephaestus): add tool call format instructions to prevent
 malformed output

GPT-5.x Codex models occasionally hallucinate malformed tool calls like:
  assistant to=functions.XXX <garbled_unicode>json\n{...}

This is a model-level issue where the model outputs tool calls as text
instead of using the native tool calling mechanism. Add explicit prompt
instructions telling the model to use the tool call interface.

Related: #2190
---
 src/agents/dynamic-agent-prompt-builder.ts | 17 +++++++++++++++++
 src/agents/hephaestus.ts                   |  4 +++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/agents/dynamic-agent-prompt-builder.ts b/src/agents/dynamic-agent-prompt-builder.ts
index 5685431b2..5c0ad5784 100644
--- a/src/agents/dynamic-agent-prompt-builder.ts
+++ b/src/agents/dynamic-agent-prompt-builder.ts
@@ -317,6 +317,23 @@ export function buildAntiPatternsSection(): string {
 ${patterns.join("\n")}`
 }
 
+export function buildToolCallFormatSection(): string {
+  return `## Tool Call Format (CRITICAL)
+
+**ALWAYS use the native tool calling mechanism. NEVER output tool calls as text.**
+
+When you need to call a tool:
+1. Use the tool call interface provided by the system
+2. Do NOT write tool calls as plain text like \`assistant to=functions.XXX\`
+3. Do NOT output JSON directly in your text response
+4. The system handles tool call formatting automatically
+
+**CORRECT**: Invoke the tool through the tool call interface
+**WRONG**: Writing \`assistant to=functions.todowrite\` or \`json\n{...}\` as text
+
+Your tool calls are processed automatically. Just invoke the tool - do not format the call yourself.`
+}
+
 export function buildDeepParallelSection(model: string, categories: AvailableCategory[]): string {
   const isNonClaude = !model.toLowerCase().includes('claude')
   const hasDeepCategory = categories.some(c => c.name === 'deep')
diff --git a/src/agents/hephaestus.ts b/src/agents/hephaestus.ts
index 8a510ecda..53bb7937d 100644
--- a/src/agents/hephaestus.ts
+++ b/src/agents/hephaestus.ts
@@ -16,6 +16,7 @@ import {
   buildOracleSection,
   buildHardBlocksSection,
   buildAntiPatternsSection,
+  buildToolCallFormatSection,
   categorizeTools,
 } from "./dynamic-agent-prompt-builder";
 
@@ -127,7 +128,7 @@ function buildHephaestusPrompt(
   const hardBlocks = buildHardBlocksSection();
   const antiPatterns = buildAntiPatternsSection();
   const todoDiscipline = buildTodoDisciplineSection(useTaskSystem);
-
+  const toolCallFormat = buildToolCallFormatSection();
   return `You are Hephaestus, an autonomous deep worker for software engineering.
 
 ## Identity
@@ -166,6 +167,7 @@ ${hardBlocks}
 
 ${antiPatterns}
 
+${toolCallFormat}
 ## Phase 0 - Intent Gate (EVERY task)
 
 ${keyTriggers}