Code localization

Overview

Before a behavior can be changed, every code location that produces it has to be found. Repository maps, code search and long-context editing find pieces of code, but they do not show how those pieces produce a behavior or whether every affected site was found 2607.13285 §1 2607.13285 §2.3. The paper calls this behavior localization and names it the central bottleneck when an agent harness (the program that runs an agent) is evolved 2607.13285 §1.

The approach the paper proposes rests on one shared idea. Precompute a map of the code that is organized by behavior: stages first, then units of code, then source-linked entries. At request time, navigate the map from the top down, then check each candidate against the current repository 2607.13285 §3.1 2607.13285 §3.3.1. The map is called a Harness Handbook Harness Handbook.

The invariant is that every entry's locator must still resolve in the current repository. An entry that fails is frozen and left out of localization until it is refreshed 2607.13285 §3.1 2607.13285 app. A.3. Coverage can therefore shrink without any error, so frozen entries need checking after each code change.

Reported results: on 30 requests per harness, plans written with the handbook won more often than plans written without it (Codex 38.3% vs 28.3%; Terminus-2 45.6% vs 26.7%), and planner tokens fell by 8.6 to 12.7% 2607.13285 §4.2.1. Against reference plans, all 24 recall, precision and F1 comparisons favored the handbook, with F1 gains of 5.0 to 18.8 points 2607.13285 §4.2.2. These numbers come from the authors' own runs, with language-model judges and reference plans written by language models.

Variants

Behavior-guided progressive disclosure over a handbook

The map has three levels plus a side view. L1 is a system overview, L2 is a component overview for each stage, and L3 holds source-grounded entries, each with a locator. A state-register view records data that crosses stage boundaries 2607.13285 §3.1. The map is built in three phases: static extraction of the call graph with no model calls, LLM-assisted grouping of code into stages, and top-down or bottom-up synthesis of summaries 2607.13285 §3.2 2607.13285 app. A. Localization selects stages by their behavior, adds stages linked to them through shared registers, selects entries, follows call edges, and keeps only the sites that resolve and are relevant 2607.13285 §3.3.1. Card: Harness Handbook.

Function-as-leaf

Entries are individual functions, or regions of a function. This mode needs a trustworthy seed skeleton of stages and registers, and the function-level entries have to fit the budget 2607.13285 §3.2 2607.13285 app. A.2.1. The paper uses it for Terminus-2, a Python terminal agent 2607.13285 §4.1.

File-as-leaf

Entries are files. No seed is needed: the stage skeleton is inferred from short file descriptions. The paper uses it when no seed exists or when function-level organization would exceed the budget 2607.13285 §3.2 2607.13285 app. A.2.2. The paper uses it for Codex, a Rust coding agent 2607.13285 §4.1. The stage draft has three variants: oneshot (the default), doctor and agent 2607.13285 app. A.2.2.

The leaf mode is fixed for the life of a map, so the choice is made once at build time 2607.13285 §3.2.

Repository-only exploration (baseline)

The comparison arm used by the paper. The same planner and read-only tools work directly on the repository, with no map 2607.13285 §4.1. It is the reference point for every number above. The paper does not propose it as a method.

When to use which

The paper's results support the choices below. Most rows rest on the paper's own conditions, which are narrow: two harnesses, one snapshot of each, and 30 requests per harness.

The gains are win rates from language-model judges. Treat them as a hypothesis to test on your own repository before relying on them.

Implementation sketch

The core is the same in every variant: build a behavior map from the code once, then localize each request against it and verify against the live source. The steps below are in our own words; the paper's full algorithm is in 2607.13285 alg. 1 and 2607.13285 §3.3.1.

# Build the map once per repo snapshot  [arxiv:2607.13285 §3.2]
def build_map(repo, leaf_mode):
    # Parse code; log unresolved calls, never guess a target
    graph = extract_call_graph(repo)
    # Group code into behavior stages, with LLM review
    stages = organize_by_behavior(graph, leaf_mode)
    # Summaries: top-down (function mode) or bottom-up (file mode)
    handbook = synthesize(stages, graph)
    # Freeze entries whose locator no longer resolves  [arxiv:2607.13285 §3.1]
    return freeze_unresolved(handbook, repo)

# Localize a request, then check each site in the live source
def localize(request, handbook, repo):
    # Pick stages whose behavior matches the request  [arxiv:2607.13285 §3.3.1]
    stages = pick_stages(request, handbook.overview)
    # Add stages that share a state register with them
    stages += stages_sharing_state(stages, handbook.registers)
    entries = pick_entries(request, stages, handbook.entries)
    # Follow call edges; boundary nodes give context only
    entries = expand_calls(entries, handbook.call_graph)
    sites = [resolve(e, repo) for e in entries]
    return [s for s in sites if s is not None and relevant(s, request)]

Contradictions

There is only one card so far, so no disagreement between papers is known. The points below concern the single paper and matter for anyone who reimplements it.

Paper against its released repository

• The paper's planner is DeepSeek-V4-Pro 2607.13285 §4.1. The released planner defaults to gpt-4o-mini unless an environment variable overrides it, and its default temperature and output cap are set in code. The paper does not state these values, so which settings the authors ran is unknown [see the card's Paper vs code section].
• The released repository does not contain the evaluation, scoring or judge code. The score weights, the tie margin and the judge prompts are therefore paper-only 2607.13285 §4.1 2607.13285 app. D.3.
• Two shipped prompts for the cross-cutting rule differ. One matches the paper's rule. The other says a function that only calls a utility is not cross-cutting 2607.13285 app. D.1.
• The file-assignment budgets (25 files per call, 6 rounds) are code defaults. The paper does not state them [see the card's Paper vs code section].

Reported numbers that cannot be checked

• The judges include DeepSeek-V4-Pro, which is also the planner 2607.13285 §4.1. The paper does not discuss self-preference.
• The score is stated on a 0 to 100 scale, but judges output 0.0 to 5.0 per dimension. How the two are mapped is not stated, so the 3-point tie margin has no clear unit 2607.13285 app. D.3 2607.13285 eq. 1.
• The win rates are multiples of 1/60 for Codex and of 1/90 for Terminus-2. That fits 60 and 90 valid comparisons, but the paper does not say how many were valid 2607.13285 §4.2.1.
• In the localization table, the Terminus-2 symbol-level Wrong values equal the file-level values for both reference plans. The paper does not explain this, so these rows should not be counted as independent evidence 2607.13285 §4.2.2 2607.13285 tab. 1.
• Reference plans come from Opus 4.8 and GPT-5.5 and are not checked against the code 2607.13285 §4.1.
• The cost of building the map and of resyncing it is not reported 2607.13285 §4.1.
• Unresolved calls are logged, not guessed, and the paper does not report how many there are in either harness. Expansion along call edges can miss sites reached only through them 2607.13285 app. A.1.
• Only two harnesses and 60 requests were tested. Both are open source, and one is in Rust 2607.13285 §4.1.

Papers

• Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable: builds a behavior-organized map of an agent harness's code and localizes change requests against it with progressive disclosure, then re-checks each site in the live repository.