- The paper introduces a Debug Subagent that encapsulates JDB and PDB operations, letting coding agents inspect runtime state through natural-language questions instead of coordinating low-level debugger tools.
- Debug2Fix raises GitBug-Java pass rates from 60.2% to 73.1% for GPT-5, 71.0% to 82.3% for Claude Haiku, and 75.7% to 85.5% for Claude Sonnet when debugging is enforced before editing.
- The results show that workflow enforcement drives debugger adoption to about 99%, while direct tool exposure leads to minimal use, though build and attachment failures account for 36% of analyzed failures and increase token costs.
Motivation and problem statement
Coding agents resolve GitHub issues primarily through two strategies: static code analysis or iterative print-debugging cycles in which the agent inserts logging statements, re-executes tests, and infers runtime behavior from console output. Both approaches require the agent to guess program state rather than observe it, which is slow (each hypothesis requires a re-run) and unreliable (a single faulty hypothesis can derail an entire session and even produce fixes that pass human-written test suites while being incorrect). Human developers, by contrast, routinely use interactive debuggers—breakpoints, variable inspection, expression evaluation, call-stack examination, and stepping—to diagnose bugs precisely. Despite the ubiquity of debuggers in IDEs and CLI tooling, they have not been adopted by coding agents. The authors attribute this to three factors: debuggers were designed for human interaction; debugger commands are verbose and asynchronous; and naive exposure of debugger tools to an LLM agent leads to brittle orchestration and, empirically, near-total non-use.
Debug2Fix addresses this gap by integrating JDB (Java) and PDB (Python) into a coding agent through a specialized Debug Subagent architecture. The central design claim is that the subagent wrapper—not raw tool exposure—is what makes debugging usable by LLM agents.
Architecture
The Debug Subagent is exposed to the main agent as a single high-level tool invoked with a natural-language runtime question plus a failing test, with optional path, line, and variable hints. It returns a structured answer containing the finding and supporting evidence (variable values, stack frames, source locations). Internally, the subagent operates four tools mirroring developer workflows:
- Debug Start Session: atomically detects the build system, builds the project, launches the test, waits for a debug port, attaches the debugger, and sets initial breakpoints. Atomicity is deliberate: exposing these steps separately caused race conditions and timeouts in early experiments.
- Debug Control: continue / step-over / step-into / step-out via a single enum-parameterized tool.
- Debug Inspect: local variables, arbitrary expression evaluation, call stacks, object fields.
- Debug Breakpoint: set/remove/list line and method breakpoints; method breakpoints are supported because they are less error-prone than line numbers for LLMs.
The subagent also has read-only navigation tools (read file, grep) but no editing tools—its mandate is root-cause identification only. Each subagent trajectory is capped at 25 steps.
Two integration mechanisms address the tool under-utilization problem: (1) only the subagent interface is exposed to the main agent, never the raw debug tools; and (2) in the "w/ Tool Limit" configuration, all file-editing tools are disabled until the Debug Subagent has been called at least once, enforcing a debug-before-edit workflow analogous to expert practice.
Experimental setup
Evaluation covers GPT-5, Claude Sonnet 4.5, and Claude Haiku 4.5 (same model for main and subagent), on GitBug-Java (186 executable instances from 55 Java repos) and a 400-instance Python subset of SWE-Bench-Live's Verified split, chosen to minimize contamination. Metrics are pass rate, subagent call rate, average steps, and token usage.
Main results
On GitBug-Java with tool-limiting enabled, Debug2Fix yields substantial gains across all models:
| Model |
Baseline |
Debug2Fix (w/ Tool Limit) |
Relative gain |
Call rate |
| GPT-5 |
60.2% |
73.1% |
+21.8% |
99.5% |
| Claude Haiku 4.5 |
71.0% |
82.3% |
+15.9% |
98.9% |
| Claude Sonnet 4.5 |
75.7% |
85.5% |
+12.9% |
98.9% |
Without tool-limiting, call rates drop to 60–70% and gains shrink accordingly. On SWE-Bench-Live (Python), evaluated without tool-limiting to study natural adoption: GPT-5 achieves a 61.4% call rate and +16.0% relative improvement; Haiku 33.2% call rate and +12.2%; Sonnet only 8.1% call rate and +2.0%. This model-dependent adoption gap is a notable finding: Claude Sonnet 4.5, the strongest model, is the most reluctant to invoke the new capability, and its performance suffers correspondingly. Call rates also diverge by language for the same model, suggesting that models' confidence in their Python print-debugging habits suppresses debugger use.
Tooling closes the model gap. With Debug2Fix, GPT-5 (73.1%) nearly matches baseline Sonnet 4.5 (75.7%), and Haiku 4.5 with Debug2Fix (82.3%) exceeds baseline Sonnet 4.5 by 6.6 points. The paper argues this shows better tool design can be as impactful as upgrading to a more expensive model—a consequential claim for cost-sensitive deployments.
Ablation analysis
Exposing debug tools directly to the main agent ("Debug Tools Only") is ineffective or harmful: pass rates are flat for GPT-5 and Haiku and drop ~18% relative for Sonnet. Manual inspection found the main agent used debug tools in only 17 of 186 instances (9%), and those debugging subsequences were shallow (≤4 tool calls). When it did debug, success was high (~82% vs. ~64% baseline on those instances), indicating the tools themselves are valuable but unusable without the subagent encapsulation. The subagent alone without tool-limiting produces inconsistent adoption across models, motivating the enforced debug-before-edit policy, which raises call rates to ~99%.
A cost consideration accompanies these gains: total tokens increase modestly for GPT-5 (+86% under tool-limiting) and Haiku (+13%), while Sonnet actually reduces main-agent tokens by ~20%, with the subagent adding roughly 33 steps and 400k tokens per instance.
Qualitative analysis
Sampling 50 trajectories from the GPT-5 run, question taxonomy shows Exception Diagnosis (27.8%) and Root Cause Analysis (25.3%) dominate, followed by local-variable and attribute inspection (~30% combined)—mirroring real developer debugger usage. Trajectory analysis reveals a consistent workflow: Start Session first, then alternating Inspect/Control calls, with most trajectories resolving within 10–15 steps.
Failure analysis of 50 failed-but-invoked instances identifies five modes: debugger session failure (36%, typically build/attach failures), wrong fix despite correct debugging (34%), high-complexity bugs requiring >3 sessions (16%), subagent API errors (8%), and the subagent falling back to static analysis (6%). Notably, over a third of failures stem from infrastructure rather than reasoning—the approach presupposes a buildable project with runnable tests.
Limitations
The authors concede several constraints. Coverage is limited to Java and Python with one benchmark each; C/C++/C#/Rust and harder benchmarks (SWE-Bench Pro, Multi-SWE-bench) remain untested. Buildability is a hard prerequisite, accounting for 36% of observed failures. All experiments pair identical main/subagent models; heterogeneous or fine-tuned specialized debugger models are unexplored. The tool-limiting strategy imposes a rigid workflow that may over-complicate trivial bugs—an adaptive gating mechanism is needed for production use. Finally, the computational cost of running the debugger itself is not measured, and debugging may be infeasible in some environments.
Conclusion
Debug2Fix demonstrates that interactive debugging, properly encapsulated behind a subagent abstraction and enforced via workflow constraints, improves bug-fixing performance by 12.9–21.8% relative across three frontier models on GitBug-Java and generalizes to Python on SWE-Bench-Live. Two findings carry particular weight: direct tool exposure fails where subagent encapsulation succeeds, and tool quality can substitute for model scale. The open questions left by the work concern adaptive enforcement of the debug-first workflow, heterogeneous model pairing, extension to additional languages, and improving instruction-following so that strong models adopt novel tools without coercion.