Tool capability is additive to grounding, not a replacement for it

[yellowman]

Found by running the product, not by reading it. A file was uploaded into a knowledge context through the browser, the context was selected, and the question was asked. The model answered that it had not been given any notes.

What was wrong

The retriever was never at fault. Called directly, rag.retrieve() returned the chunk for all four phrasings tried, and the lexical channel alone returned it. The loss was one layer up.

_turn_needs_tools() decides whether a turn takes the tool-agent workflow or the plain one. It asks about capability — an attachment, web tools, a published MCP server — and it answered correctly. But the two workflows differ in more than capability:

• llm.generic validates context_id, retrieves for it, and injects the chunks.
• The agent planner never received context_id at all, and offered file_search only when the conversation held a searchable attachment.

So a knowledge context the user explicitly selected entered neither the first prompt nor the tool list. Choosing the capable path silently removed the grounding, leaving the model to infer that a context it could not see needed searching.

Not a web bug, though the shipped settings make it universal

web_tools_enabled ships True and web_search_provider ships "none", so _turn_needs_tools() is true on every fresh installation and every turn takes the agent path. That is why this reproduced immediately. It is not the cause: an attachment or a published MCP server loses the same context with web off. The witness is parameterized over two triggers for that reason — a fix that repaired only the web case would leave an operator with an MCP server still losing every selected context.

The tempting fix, and what it costs

Narrowing the selector to web_tools_enabled and provider != "none" also turns the reds green, which is what makes it dangerous. "none" disables web search; web_fetch needs no provider and is offered whenever web tools are on. Measured on the unfixed code, the tool list for that configuration is exactly ['web_fetch'] — so that patch would restore grounding by removing the turn's only capability, and nothing would have said so.

One witness exists to refuse it rather than to require anything: with web enabled and no provider, web_fetch must be offered and web_search must not.

The fix

At agent-context construction, not at routing.

• context_id reaches the planner and is authorized by _validate_context_scope — the same check llm.generic uses, so the two paths cannot answer "may this user read this" differently.
• Its chunks go into the system block before the first model call.
• The same snippets ride in the plan, so the worker returns them and the turn reports the grounding it used rather than only what a tool fetched.
• file_search is offered whenever a valid ordinary context_id exists. Not a new capability: _run_file_search already resolved an explicit context_id, so the tool worked the whole time and was simply never offered. Iterative search is the additive half, never the only route to the context — which is why the model in the witness makes no tool call.

Retrieval sits beside prompt assembly rather than inside it, because those snippets have two destinations — the prompt and the reported context_snippets — and retrieving twice to tell two callers the same thing is how the two answers begin to differ.

Grounding obeys the prompt budget

_apply_prompt_budget drops context from its low-priority end before it drops any history, then refuses the turn if the prompt still does not fit. Appending the chunks onto system_content and passing [] as context would put them inside an indivisible system block, so the pruner would reach past them:

llm.generic:  drop lowest-priority context  -> then, if needed, history
agent:        grounding cannot be dropped
              -> evict history instead
              -> reject the turn once the block alone overflows

Routing may add capability; it does not rearrange priority. Grounding is passed as context and appended only after budgeting.

_build_agent_context therefore returns the grounding that survived rather than the grounding that was retrieved, and the plan and streamed result carry that set. context_snippets is a claim about what the model was shown, so reporting the pre-pruning retrieval would name chunks it never saw.

Both paths, each witnessed

_stream_agent_files_node calls _explicit_context_grounding itself, passes its own arguments into _build_agent_context, and seeds its own worker plan. Sharing the assembly function does not make any of that shared, so the streaming half has a witness that drives run_streaming rather than resting on inference from the batch cases.

Verification

Nine witnesses, three failing before the fix — including the MCP trigger, which failed identically to the web one.

Seven mutations, all applied, all killed:

mutation	kills
planner drops propagation	4 batch cases
grounding never reaches the prompt	5 (broad)
web_fetch gated on provider	capability witness + control
streaming retrieval removed	streaming case only
streaming arguments removed	streaming case only
folded into system block pre-budget	both budget cases
reports retrieval, not survivors	reporting case only

Two earlier attempts did not apply at all — a stale anchor, and a cooked string that turned a literal backslash-n into a newline. A mutation that does not apply measures nothing, so the driver now reports an unmatched anchor as loudly as a survivor.

Lanes: make test-xdist — 2869 passed, 27 skipped, 0 failed. CI's lint selection (ruff check liminallm/ --select=E,F,W,I --ignore=E501) clean.

On the running product, against the shipped configuration and a live model: the same probe went from three misses to three hits, with the no-context control missing in both — which is what makes the hits mean anything. The browser flow went from 13/14 to 14/14.

Not in this tranche

_turn_needs_tools, the web defaults, and RAG retrieval itself are untouched.

summarize_preferences calls list_artifacts without owner_user_id, so the visibility clause collapses to visibility='global' and a user's own private adapter never appears in GET /v1/preferences/insights. Measured, no cross-user leak — the fail-safe direction. It is a separate owner-scoping call-site defect and is deliberately left out of this tranche.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DQtPsg9YSUXaStGXyUjozA

---

Generated by Claude Code

---

Note

Overview
Fixes a regression where choosing a knowledge context did nothing on the tool-agent path. When _turn_needs_tools() sent a turn to agent.files_v1 (common on fresh installs because web tools default on with no search provider), the planner never received context_id, so selected corpora were neither in the first prompt nor eligible for file_search—while llm.generic still retrieved and injected them.

Agent turns now ground the same way as plain chat. _explicit_context_grounding validates scope and retrieves chunks before assembly; batch and streaming agent paths pass that into _build_agent_context, seed the worker plan with budget-surviving context_snippets, and the tool worker reports those snippets instead of only tool-fetched text. file_search is offered when the turn names an owned context (additive search), not as the only way to see the selection.

Grounding follows §20.3 prompt budgeting: chunks go through _apply_prompt_budget as context (appended after pruning), and returned/reported snippets are the subset actually shown—not the full retrieval.

SPEC §21 and docs/ISSUES.md document the invariant; tests/test_agent_grounding_is_additive.py covers web/MCP triggers, streaming, budget/reporting, and refusing a “disable web_fetch” workaround.

^{Reviewed by Cursor Bugbot for commit 6fe34ca. Bugbot is set up for automated code reviews on this repo. Configure here.}