[Discuss] Decide if the context tools must always apply Never include and hard filters
## Summary
A site builder uses two delivery controls to decide which context items a consumer, such as an agent, gets:
* **Never include** in the consumer configuration keeps an item out of the context of that consumer.
* Hard filters remove an item that does not apply to the request. The Languages, Site Sections, Entity Types, Taxonomy Terms, Specific Entities and Roles scopes can act as hard filters (`AiContextScopeResolver::filterByRequestContext()`).
In push injection, only the site builder can change these controls, for example with **Always include** on the consumer. In the context tools, there are three cases where the tool input changes the controls, or where the tool does not apply them. All code facts below are from `1.0.x` at `65f20b72`.
### Case 1: `consumer_id` in the tool input replaces the running agent
The Get Relevant tool (`ai_context:get_relevant_ai_context_items`) and the List tool (`ai_context:list_ai_context_items`) have an optional `consumer_id` input.
* `AiContextAgentToolSubscriber::onToolPreExecute()` sets `consumer_id` to `agent:{running agent}` only when the input is empty or not in the `{type}:{instance}` form. When the input has a well-formed ID, the subscriber keeps it and does not read the running agent.
* `AiContextSelectionFactory::fromParameters()` then merges the configuration of the consumer in the input: subscriptions, Always include, Never include, limits and selection mode. The configuration of the running agent is not used.
* Each well-formed ID is accepted. An ID that has no consumer row, for example `agent:unknown`, gives empty Always include and Never include lists. Then no consumer Never include applies.
* The Always include items of the named consumer also skip hard filters (see Case 2).
* In Get Relevant, the `never_include` input is added to the consumer list, and the tool input cannot remove items from that list. In Get Relevant and List, a different `consumer_id` is the only intended way for the tool input to remove the Never include of the running agent. On `65f20b72`, an `always_include` ID with leading zeros in Get Relevant also skips Never include. #3586708+s fixes that bug.
* Who can do it: in an agent run, the model chooses the input. Outside an agent run, the caller chooses it, and there is no running agent.
The docs describe this behavior: an explicit `consumer_id` wins (`docs/features/context_delivery.md`, `docs/developers/function_calls.md`).
### Case 2: `always_include` in the tool input skips hard filters
* Get Relevant takes `always_include` from the tool input. `fromParameters()` merges it with the Always include of the consumer into one list.
* `AiContextSelector::loadCandidateItems()` loads the always-included items with `loadPublishedItemsByIds()` and `AiContextLanguageService::translateItems()`. These check publication and view access. `filterByRequestContext()` runs only on the other candidates, in the chunk loop.
* Never include still wins over Always include.
* Example: an item has the Roles value Editor. A user without the Editor role uses the agent. When the model puts the item ID in `always_include`, the tool output has the item.
* Who can do it: the model in an agent run, or a caller outside an agent run.
The docs say that Always include on an agent skips hard filters, including Roles (`docs/features/scopes.md`, `docs/features/context_selection.md`). They describe the consumer setting that a site builder makes. They do not say that the tool input can do the same.
### Case 3: the Load tool does not apply Never include or hard filters
* `AiContextLoadItemsFunctionCallBase` is the base class of `ai_context:load_ai_context_items` and of its deprecated alias `ai_context:load_ai_context_item_by_id`.
* `execute()` returns each requested item that is published and that the account can view (`loadPublishedItems()`, then `translateItems()`). It does not read a consumer configuration. It does not call `filterByRequestContext()` on the requested items.
* Load does not implement `AiContextInheritsConsumerIdInterface` and has no `consumer_id` input, so it does not know the running agent.
* `resolveSubcontext()` gives empty Always include and Never include lists to `AiContextSubcontextResolver::resolve()`. Children with their own scope still go through hard filters.
* `docs/developers/function_calls.md` does not say that Load skips Never include and hard filters.
* Who can do it: each caller of Load. This includes the model, a caller outside an agent run, and a site builder who adds Load with fixed IDs to the **Default information tools** of an agent.
So an agent that has the Load tool can get an item that its Never include or the Roles scope keeps out of push injection and Get Relevant. The List tool shows numeric item IDs, and item IDs are serial numbers.
### How the tool input is made
In an agent run, the model writes the tool input. It uses the chat request and the text that it reads during the run, for example page content or tool output. So the chat user, or text that gives instructions to the model (prompt injection), can change the input. Outside an agent run, the caller writes the input directly, for example a remote MCP client through drupal/mcp (see #3586606+s). Each tool runs as the current account.
### This is not an access bypass
None of the three cases lets an account read an item that it cannot read already:
* Each context tool requires one of three permissions (`AiContextFunctionCallBase::hasContextPermission()`). Each tool checks view access for each item.
* `AiContextItemAccessControlHandler::checkAccess()` gives view access to each published item for **View AI Context Items in CCC** and for **Use Published AI Context in AI Features**. **Administer AI Context** skips the check.
* The item page (`/admin/config/ai/context/items/{ai_context_item}`) requires only view access. So the same accounts can read each published item there. #3586357+s proposes to change the item page in 1.1. After that change, the Load tool still returns each published item that the account can view.
* On the item form, the Roles scope says that it does not control who can view or edit the item.
Never include and hard filters are delivery controls. They decide which context a consumer gets. They do not decide who can read an item. The questions below are about how predictable these controls are for site builders, and about how much the tool input can change them.
### Not in this issue
* Other inputs change the result intentionally. `scope_subscriptions` replaces the consumer subscriptions that have the same scope key. An explicit `selection_mode` replaces the consumer mode. `entity_type` and `entity_id` set the request entity that hard filters check. These inputs do not skip Never include or hard filters.
* #3586708+s fixes a related bug: Never include does not remove an item when the tool input gives its ID with leading zeros. That fix does not change the three cases here.
Related:
* #3586606+s documents what external agents can and cannot do with the context tools.
* #3586357+s separates the CCC item page from the permission that the tools use.
* #3586681+s explores Get Relevant and Load as Tool API plugins. These plugins must follow the same decision.
## Questions
Each change in Questions 1 to 3 changes tool behavior after 1.0.0. Agents and prompts can depend on the current behavior. So a change belongs in 1.1.0, with a release note. Docs for the current behavior can go into 1.0.x (Question 4).
### Question 1: Can `consumer_id` in the tool input replace the settings of the running agent?
1. Keep the current behavior, and document it.
* Pro: No behavior change. An agent can still get the context of a different consumer intentionally. For example, a main agent can get the context for a sub-agent that it runs.
* Con: The Never include of the running agent does not apply to tool calls. An ID without a consumer row removes all consumer Never include.
2. In an agent run, always add the Never include of the running agent. The `consumer_id` input still selects the other settings.
* Pro: The Never include of the running agent always applies. Use of a different consumer stays possible.
* Con: The subscriber must keep the running agent also when the input has a valid ID. The result mixes two configurations, which is more difficult to explain.
3. In an agent run, ignore a `consumer_id` input that is not the running agent.
* Pro: One rule. An agent always gets its own settings.
* Con: Agents that use a different consumer intentionally stop working. Callers outside an agent run can still choose any consumer.
### Question 2: Must hard filters apply to `always_include` from the tool input?
1. Keep the current behavior. Document that Always include from the tool input also skips hard filters.
* Pro: No behavior change. One rule for all Always include items.
* Con: The model can add an item for an audience that the request does not match, for example an Editor item for a user without that role.
2. Apply hard filters to Always include items from the tool input. Keep the skip for Always include in the consumer configuration.
* Pro: Only a site builder can skip hard filters. This matches the docs, which describe the skip as a consumer setting.
* Con: `AiContextSelectionParams` and `AiContextSelection` must keep the tool input IDs apart from the consumer IDs. This adds to public classes. The Load tool still returns the item, unless Question 3 changes Load too.
3. Apply hard filters to all Always include items.
* Pro: One rule for all delivery paths.
* Con: This changes the documented behavior of the consumer configuration, also for push injection. Sites that use Always include to deliver an item outside its scope lose that function.
### Question 3: Must the Load tool apply Never include and hard filters?
1. Keep the current behavior. Document that Load checks only publication and view access. Tell site builders not to give Load to an agent when its Never include or the Roles scope must apply.
* Pro: No behavior change. The same IDs always give the same items.
* Con: Never include and Roles do not apply for an agent that has Load.
2. In an agent run, apply the Never include of the running agent. For example, Load implements `AiContextInheritsConsumerIdInterface` and gets a `consumer_id` input. Then the answer to Question 1 also applies to Load.
* Pro: Never include applies in all three tools in an agent run. Never include does not depend on the request, so List and Load use the same Never include.
* Con: Behavior change. The output for one ID then depends on the agent. Callers outside an agent run see no change.
3. Do option 2, and also apply hard filters to the requested items.
* Pro: Load applies the same Never include and hard filters as List and Get Relevant. An ID that List hides because of these controls does not load.
* Con: Load has no `entity_type` and `entity_id` inputs, so the Entity Types and Specific Entities filters check only the request. Hard filters also apply to the fixed IDs in **Default information tools**. The output must tell the model which IDs are not available.
### Question 4: Where do we document the current behavior for 1.0.x?
1. Add the three cases to #3586606+s.
* Pro: One docs issue for what tool callers can do.
* Con: #3586606+s is about callers outside the site. The three cases also apply to agents in the site.
2. Open a separate docs issue for 1.0.x.
* Pro: Small and independent of the decision in this issue.
* Con: One more issue.
## Decisions
Decided on 2026-11-21, with the input for the reader (#3586716) from the comment of 2026-11-20 on this issue.
* **Question 1: option 2.** In an agent run, the Never include of the running agent always applies. The `consumer_id` input still selects the other settings (subscriptions, Always include, limits and selection mode).
* **Question 2: option 2.** Get Relevant applies hard filters to the Always include IDs from the tool input. Only the consumer configuration can skip hard filters.
* **Question 3: option 2.** In an agent run, Load applies the Never include of the running agent. Load does not apply hard filters, because it returns items by ID, has no request entity input, and also runs with fixed IDs from site builders. So a Roles value does not apply to an agent that has Load. The docs say this.
* **Question 4: option 2.** A separate docs issue documents the current behavior for 1.0.x.
* **The List tool.** In an agent run, List also removes the Never include items of the running agent. Then List does not show items that Get Relevant and Load refuse.
* **Callers without a running agent.** This issue decides only the agent case. Callers outside the site, for example MCP clients, follow the access profile of the outside access model (#3586600, children 7, 9 and 10). Drush and other callers in the site without an agent: no change.
* **Items that Load does not return.** The Load output has one list of the requested IDs that are not returned, with one reason text for all cases (not found, not published, no view access, Never include). The output does not show that a hidden item exists.
* **Order.** The reader (#3586716, tasks 7 to 9) implements these decisions in `loadItems()` and `select()`. The implementation issue for 1.1.0-alpha1 tracks the behavior change, the kernel tests and the release note, and it is done together with the reader tasks.
## Remaining tasks
* [x] Decide Questions 1 to 4.
* [ ] Document the current behavior of the three cases for 1.0.x, in #3586770.
* [ ] Open the implementation issue for 1.1.0-alpha1, with kernel tests for each changed case: a `consumer_id` input for a different consumer, an `always_include` input with a Roles value, a List call and a Load call for an item in Never include, and the list of IDs that Load does not return.
* [ ] Add the decisions to the Tool API work in #3586629+s.
## User interface changes
None.
## API changes
None in this issue. Possible changes after the decision:
* Question 2, option 2: a separate list for Always include IDs from the tool input on `AiContextSelectionParams` and `AiContextSelection`. This is an addition to public classes.
* Question 3, option 2: a `consumer_id` input on `ai_context:load_ai_context_items` and on its deprecated alias.
* Load output: a list of the requested IDs that are not returned, with one reason text.
* The function call plugin IDs do not change.
## Data model changes
None.
## Release note
None for this issue. The implementation issue needs a release note, because it changes tool behavior after 1.0.0.
> [!note]
> Check the one that best describes your usage, or leave all unchecked if AI was not significantly used.
>
> * [ ] AI **Assisted Issue** \
> _Mainly written by a human; AI used for partial generation under full human supervision._
>
> * [x] AI **Generated Issue** \
> _Mainly generated by AI, reviewed and approved by a human before this issue was created._
issue
GitLab AI Context
Project: project/ai_context
Instance: https://git.drupalcode.org
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://git.drupalcode.org/project/ai_context/-/raw/1.0.x/CONTRIBUTING.md — contribution guidelines
- https://git.drupalcode.org/project/ai_context/-/raw/1.0.x/README.md — project overview and setup
Repository: https://git.drupalcode.org/project/ai_context
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD