[yzxcj797]

Summary

• Bound every response list from the four remaining query tools, including impact-radius changed files, changed nodes, impacted nodes, impacted files, and edges.
• Expose max_results on the impact-radius MCP tool and validate all caller-supplied bounds, rejecting booleans and values below 1.
• Add detail-aware hard ceilings, preserve untruncated totals, mark truncation, and report "showing N of M" in summaries.
• Cap traversal at a hard approximate-token ceiling while still computing and reporting the complete bounded-depth node count.

Regression coverage

• Removed all four tools from the deferred unbounded set and enabled their worst-case token assertions.
• Added fixture checks for per-list truncation, exact omitted counts, detail-level ceilings, bound validation, and a one-token traversal that emits no entry beyond its budget.

Validation

• pytest tests/test_token_budget.py tests/test_tools.py tests/test_main.py tests/test_documentation.py -q — 298 passed.
• pytest tests/test_token_budget.py -q — 127 passed.
• ruff check code_review_graph/tools/query.py code_review_graph/main.py tests/test_token_budget.py — passed.
• python -m py_compile for all changed Python files and git diff --check — passed.

Fixes #888

[github-actions]

code-review-graph review

Overall risk: 0.54 (MEDIUM) — 16 changed function(s)/class(es), 0 affected flow(s), 6 test gap(s)

Risk-scored changes

Risk	Level	Symbol	Location	Tested
0.54	medium	code_review_graph/main.py::get_impact_radius_tool	code_review_graph/main.py:220	no
0.54	medium	code_review_graph/main.py::find_large_functions_tool	code_review_graph/main.py:457	no
0.50	medium	code_review_graph/tools/query.py::get_impact_radius	code_review_graph/tools/query.py:133	yes
0.50	medium	code_review_graph/tools/query.py::semantic_search_nodes	code_review_graph/tools/query.py:796	yes
0.50	medium	code_review_graph/tools/query.py::find_large_functions	code_review_graph/tools/query.py:971	no
0.50	medium	code_review_graph/tools/query.py::traverse_graph_func	code_review_graph/tools/query.py:1080	no
0.50	medium	tests/test_token_budget.py::test_hard_ceilings_bind	tests/test_token_budget.py:676	(test)
0.50	medium	tests/test_token_budget.py::TestTruncationContract.test_impact_radius_caps_every_response_list	tests/test_token_budget.py:795	(test)
0.50	medium	tests/test_token_budget.py::TestTruncationContract.test_impact_radius_caps_reachable_response_lists	tests/test_token_budget.py:806	(test)
0.50	medium	tests/test_token_budget.py::TestTruncationContract.test_semantic_search_reports_untruncated_total	tests/test_token_budget.py:816	(test)

Test gaps

• code_review_graph/main.py::get_impact_radius_tool (code_review_graph/main.py:220)
• code_review_graph/main.py::find_large_functions_tool (code_review_graph/main.py:457)
• code_review_graph/tools/query.py::find_large_functions (code_review_graph/tools/query.py:971)
• code_review_graph/tools/query.py::traverse_graph_func (code_review_graph/tools/query.py:1080)
• tests/test_token_budget.py::TestTruncationContract (tests/test_token_budget.py:772)
• ...and 1 more without direct tests

Token savings: this graph-backed report used ~36,715 fewer tokens (~92%) than reading every changed file in full (estimated, chars/4 approximation).

---

Powered by code-review-graph — local-first analysis; no code leaves the CI runner.

[tirth8205]

The net win here is real and I measured it: on main, get_impact_radius(changed_files=["code_review_graph/graph.py"], max_depth=5) and find_large_functions(min_lines=1, limit=HUGE) cost roughly 71k and 469k tokens; on this branch they land at ~45k and ~14k. The mechanism also reuses _bounded/_shown_of/_validate_positive_int from #887 rather than inventing a second one, and the totals really are the untruncated counts. Two things need to change before it can merge, though, and both are about which rows survive rather than how many.

1. The edge cap slices an unranked list, so the visible edges misrepresent the graph. _bounded(edge_dicts, max_results, _MAX_IMPACT_EDGES) at query.py:214-216 takes a prefix of get_edges_among()'s raw row order. Nothing sorts it first. On this repo's own graph:

full edges : 4285  {'CALLS': 2187, 'TESTED_BY': 1624, 'CONTAINS': 317, 'IMPORTS_FROM': 83, 'REFERENCES': 74}
shown      :  150  {'TESTED_BY': 139, 'CALLS': 11}
edges cost : ~20k tokens of a ~45k response

CALLS is 51% of the real set and 7% of what the caller sees; IMPORTS_FROM and REFERENCES disappear entirely. Before this PR the list was unbounded — too big, but complete. Now it is small and skewed, and an agent reading it draws the wrong conclusion about the blast radius while still paying 20k tokens for the privilege. Please rank before bounding (endpoint impact score, or an edge-kind priority that puts CALLS/IMPORTS_FROM ahead of TESTED_BY/CONTAINS). The same concern applies to impacted_files and changed_nodes, which are built from a set in graph.py and so are hash-ordered — this repo never exceeds those caps, but a bigger one would.

2. detail_level="minimal" is now the most expensive way to call find_large_functions. _MAX_LARGE_FUNCTIONS_MINIMAL = 500 is 5× the standard ceiling while a minimal row is only ~2.6× smaller:

find_large_functions(min_lines=1, limit=10**6)                        -> 100 rows, ~14.3k tokens
find_large_functions(min_lines=1, limit=10**6, detail_level="minimal") -> 500 rows, ~42.6k tokens

That is over the worst_max: 30_000 this PR declares for the tool, and it inverts the advice in CLAUDE.md that tells agents to use minimal unless they need more. The budget table can't catch it because the entry's worst kwargs are {"min_lines": 1, "limit": HUGE} with no detail_level — get_architecture_overview_tool right above it does pin one, so this looks like an oversight rather than a convention. Please lower the minimal ceiling so minimal actually costs less than standard, and pin detail_level in the budget entry so the test can see it.

Worth fixing in the same pass:

• semantic_search_nodes totals are now the whole graph. hybrid_search(..., limit=_FETCH_ALL) defeats the limit * 3 fetch cap in search.py, so FTS returns everything: query="graph" gives total=5794 — that is every node in the graph — with results_omitted=5774 and a summary reading showing 20 of 5794. It also materializes 5,794 result dicts to return 20. Bound the fetch to a multiple of the requested limit instead of _FETCH_ALL, and let total mean "matches worth ranking".
• traverse_graph's token budget stops bounding work. It now walks the whole bounded-depth component and slices afterwards: depth=6 on GraphStore takes ~0.33s and issues the same ~13k point queries whether the budget is 1 or 1,000,000, emitting 0 entries in the first case. graph.py documents 500k nodes / 3M edges as the design scale; there this is a lot of work to produce nothing. Short-circuit the walk at the budget again and keep the separate full count.
• result_count now means two different things in one file. fix(tools): bound every unbounded MCP response #887 set it to the untruncated total for query_graph; here it is the shown count for semantic_search_nodes (a change from its previous meaning) and find_large_functions. Nothing downstream reads it, but it is an LLM-facing contract, so please pick one.
• The ceilings are count-based, so the default impact call is still ~45k tokens — 3.6× the tool's own default_max of 12k — because rows cost 126–135 tokens each. Not a regression (it inherits fix(tools): bound every unbounded MCP response #887's 100/150 shape) and it stays under ABSOLUTE_MAX_TOKENS, but a token-aware cap would actually deliver the documented budget.
• docs/COMMANDS.md:59 says each list reports its untruncated *_total; there is no impacted_nodes_total — that list reports total_impacted. Also, three of the four new ceilings aren't mentioned in the MCP docstrings agents read (main.py limit/token_budget), and one docstring leaks the private constant name _MAX_TRAVERSAL_TOKEN_BUDGET instead of its value.

Verified good, for the record: bounds reject 0, -1, True and False on all four params; impacted_nodes keeps the true top-100 by impact score in order; traversal at a one-token budget still reports the correct complete count; the new tests genuinely fail without the source change; and the parameter names and defaults in the docs match the code.

[tirth8205]

Changes required: the nominally minimal result can be substantially larger than standard output, and several caps apply only after unbounded work or arbitrary ordering. Populate GraphStore(root / '.code-review-graph' / 'graph.db') with 550 three-line Function nodes whose file paths include a 180-character directory component, then call find_large_functions(min_lines=1, limit=10**6, repo_root=root) in standard and minimal modes against that store; the recorded output was 100 rows/95,923 JSON characters versus 500 rows/295,341 characters, with exact sizes depending on the temporary root length. Rank results before slicing and bound retrieval and traversal work as well as the final response.

[tirth8205]

This no longer merges into staging. Conflicts in code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md, docs/COMMANDS.md.

git fetch origin && git merge origin/staging
# resolve, then
uv run pytest tests/ -q
uv run ruff check code_review_graph/
uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
git push

When resolving:

• Rebase fix/888-bound-query-responses onto current staging and resolve the two Markdown conflicts (see notes).
• After rebase, re-run the full gate set (pytest 3.13, ruff, mypy) and the edge-case review for the code changes in code_review_graph/tools/query.py and code_review_graph/main.py; neither was assessed because the merge did not complete.

A large integration branch landed on staging today, which is why this drifted.

PRs now target staging, not main. Yours was retargeted already, so nothing to do there.

[tirth8205]

This no longer merges into staging. 5 files conflict and the branch is 243 commits behind:

• code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md
• code_review_graph/main.py
• code_review_graph/tools/query.py
• docs/COMMANDS.md
• tests/test_token_budget.py

Worth knowing before you resolve:

• code_review_graph/main.py: staging routes 28 of the 30 tools through one _offload helper, so tools that were plain def are now async.

git fetch origin
git merge origin/staging
# resolve, then
uv run pytest tests/ -q
uv run ruff check code_review_graph/
uv run mypy code_review_graph/ --ignore-missing-imports --no-strict-optional
git push

I have not reviewed the change itself yet. That comes once it merges and the checks run against the merged state, since staging has moved a long way and the result is what matters.

[tirth8205]

Thank you for this PR. I ran your token-budget tests on this branch and staging.

Before I can merge it, please fix these:

1. Please drop the get_impact_radius changes. fix(parser): resolve Go and Ruby imports to files, not bare strings #1027 already bounds it on staging. It sends max_nodes=_FETCH_ALL (query.py:189). With max_results=1, the store loads 806 nodes and 1,873 edges.
2. With CRG_MAX_IMPACT_NODES=3, the store still gets max_nodes=1000000000. Issue get_impact_radius, find_large_functions, traverse_graph and semantic_search_nodes return unbounded responses #888 needs this fixed. Please default to constants.MAX_IMPACT_NODES and add a test.
3. Minimal find_large_functions returns more than standard (query.py:70). With min_lines=1, limit=10**6, standard gives 100 rows and minimal gives 500. Minimal uses about 36,000 tokens, over your worst_max. Please lower the minimal cap. Add detail_level="minimal" to its entry in tests/test_token_budget.py.
4. Work runs before the cut (query.py:72). semantic_search_nodes(limit=1) fetches 936 rows to show 1. traverse_graph with token_budget=1 visits 1,014 nodes and shows 0. Fetch a small multiple of limit. Stop the walk when the budget ends.
5. result_count now has two meanings. query_graph sets it before the cut. query.py:872, 887 and 1066 set it after. semantic_search_nodes(limit=1) gives result_count=1 and total=936.

Please update your branch with the latest staging. There are conflicts in code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md, code_review_graph/main.py, code_review_graph/tools/query.py, docs/COMMANDS.md and tests/test_token_budget.py.

After you push the fix, I will test it again.