Read tools lists built by an expression in diff --application (#909)

[pengfei-threemoonslab]

Why

On the 49-PR development corpus (#908), the most common reason diff --application produced no row was "uses a dynamic tools expression". An agent whose tools= was [*FINANCE_TOOLS, *([handoff] if wanted else [])], base + (extra or []), a filter, or another module's list had none of its bindings compared, even when every member was a plain tool the reader already understood. A reviewer got partial and nothing to review.

What changes

One resolver both readers share (src/agents_shipgate/inputs/list_expressions.py). The OpenAI Agents SDK reader (tools=, handoffs=) and the Google ADK reader (tools=, sub_agents=) read these expressions member by member:

• list and tuple literals with * spreads;
• a + b;
• a if c else b and a or b;
• a comprehension that keeps its elements, and filter(...);
• list(...), tuple(...) and sorted(...);
• a name bound once to any of these, in the builder, at module level, or in another module reached through a repository-local import.

Nothing is imported or run.

• A part the reader cannot read is named where it is, on its agent. Examples: a call, a builder's parameter, self.tools, a name changed in place, a name bound twice. The agent stays incomplete, so the answer is never compared, and the members that were read are still compared. The Google ADK dynamic-tools limit now names its file, line and agent instead of covering the whole file.
• Conditions are shown, never evaluated. A member held only under a condition carries bound_when on its row's side: one entry per way in, each the condition's whole source text. A change to the condition alone is a changed row whose why names both conditions and says the direction is not established. It is not_established when an unread part of the list could hold the tool another way.
• application_comparison_schema_version 0.2 → 0.3. The text output prints bound only when ….
• Fixed on the way:
  • an imported handoffs= list no longer reads as one handoff named after the list;
  • an ADK starred element the reader cannot read no longer leaves the agent's list marked complete.
• OpenAI Agents SDK: resolve bounded literal tool-list concatenation in static binding evidence #584 (literal-list concatenation) is subsumed. Its recovery reason sdk_literal_tool_list_concatenation_unsupported is retired because that form is now read.

scan

• Tool proof is unchanged. Google ADK's high extraction confidence is a proven-surface claim, and a list read through a name is checked for changes only in its own module, the modules its import passes through and the packages above it. So an ADK tools= or sub_agents= list that came through a name, or from another module, keeps the module at medium, and no scan decision moves. A literal spread into a literal ([a] + [b]) stays proven.
• The binding graph now trusts an expression-built sub-agent list. It already trusted the SDK's handoff lists the same way since Resolve repository-local imported tools for Google ADK and OpenAI Agents SDK (#864) #879. Please check this choice.

Measured

• Development corpus (49 PRs, Q2 measurement: commit the acceptance corpus, freeze a holdout, and report Q1/Q2 on every advisory release #908's runner): statuses are unchanged (1 compared, 42 partial, 6 not_established).

  • Pull requests with any row: 9 → 11. Rows: added 8 → 9, changed 60 → 65, not_established 230 → 232.
  • Pull requests still carrying a tools-list limit: 28 → 24 (23 of the 42 with no stated row).
  • MIS_TALENT#5, [codex] Harden scanner trust and report stability #7 and [codex] Harden post-v0.2 scanner edge cases #8 now report Finance_Agent's rows.
  • [codex] Harden scanner trust and report stability #7, the issue's worked example, now meets Q1 and Q2 by my hand check. Its three binding changes all appear, nothing is false, the answer stays partial, and each changed row names where reading stopped.
  • Update pytest requirement from <9,>=8 to >=8,<10 #5 shows its handoff tool's condition changing from handoffs to want_handoff_tool = bool(handoffs) or include_handoff_tool. No reader could show that before.
  • Domkniecie zamowienia w module wycen i szesc rund napraw Debusia kkmiecik-coder/CRM#5 goes from no row to four.
  • What still blocks most PRs without rows: a builder's parameter (30 parts, Application diff: resolve tool lists passed into agent-building functions and constructors #874), a call (18) and a name changed in place (10).
  • Every score in the 2026-09-30 ledger is stale against this build, because the schema version is part of each answer. The next release ledger re-scores them, per Q2 measurement: commit the acceptance corpus, freeze a holdout, and report Q1/Q2 on every advisory release #908.

• No new false row on the 134-PR corpus. Its pins were lost to the /tmp cleanup, so it was re-pinned at today's PR heads (131 of 134; 3 PRs are gone). Every status is identical (91 partial, 39 not_established, 1 compared). Two PRs gain rows and none loses any:

  • feat(knowledge-agent): implement unified multi-modal KnowledgeAgent subsystem dandye/agentic_soc_gemini_enterprise#110: +4, a new agent's literal tools before an unread + skill_tools;
  • Add the AIDA-MATE codebase Praatosh/AIDAMate#1: +12, four new agents built with tools=[*tool_set].

  I checked all 16 rows against source; each is correct.

• Speed: within about 4% of main on 7,500-line modules, and 0.33 s against 0.21 s for 40 agent files importing one module.

Review

Five reviewers, each verifying with fixtures:

• line-by-line review of the resolver;
• removed behavior and cross-file callers;
• fail-open hunting through diff --application;
• tests, docs and conventions;
• reuse and efficiency.

They found about 40 confirmed problems, 15 after merging overlaps; all are fixed and each has a regression test in tests/test_list_expressions.py. The ones that mattered:

• Changes the change index missed:
  • an import inside a function changed in place;
  • mod.LIST.append through the module's own spelling;
  • a package __init__ that re-exports the list and changes it;
  • a change through an agent built with the list (helper.tools.append), in its own file or another;
  • defaults, decorators and class bodies scoped as Python evaluates them;
  • walrus and match-capture rebinding;
  • a wildcard import after the list;
  • a list passed after a * spread to a helper;
  • decorated helpers;
  • a user-defined replace or a non-agent .clone;
  • another module's own Agent class.
• Condition text was cut at 160 characters before comparison. Conditions are now compared whole.
• No bound on work: a list spread into itself many times grew exponentially (44 s, 1,000,000 members). Members are now deduplicated and memoized, with caps on members and visits.
• A quadratic slowdown on large files (5.6 s → 349 s): callee verdicts are cached, and one cache is shared per load.
• ADK:
  • sub_agents= lists read from expressions had let scan pass;
  • twins differing only in what they hold unconditionally were merged;
  • a partly read list blocked other agents' rows in the file.
• SDK:
  • hosted tools lost their recovery evidence;
  • another module's unresolved member was bound by name to a local tool (a false row);
  • a handoff spelled like a local agent was taken for it.
• A with block was treated as conditional, which regressed a list the old reader read.

Left as a follow-up: ADK's #865 reader for builder-local tools.append(...) uses its own rules beside this resolver. Folding it in changes documented behavior, so it is proposed separately.

Surface discipline

• What it moves: Application-agent PR review without prior setup: exact-ref comparison, tool bindings, and 10 verified cases #868's Q1/Q2 on the development and holdout corpora. It extends the existing readers and the one binding engine and adds no command.
• Surface touched: a field on an existing row side (bound_when) and its schema version, both registered in docs/distribution-surfaces.md, with the parity note in tests/test_distribution_surface_parity.py.

Closes #909. Closes #584.

🤖 Generated with Claude Code