## Problem/Motivation `hook_ai_context_scope_values_alter()` is documented (in `ai_context.module` and `docs/developers/hooks.md`) to alter scope values "for display in forms or for matching." In practice it does neither. The alter is only invoked in `AiContextScopeManager::getAllScopeValues()`, which no form or resolver calls: - **Forms** (`AiContextItemForm`, `AiContextAgentForm`) build scope widgets via `$plugin->buildValueForm()`, which reads raw `AiContextScopeBase::getValues()` — the alter never runs. A value added by the hook (e.g. a custom `use_case`) cannot be selected in the UI. - **Labels** (`AiContextScopeBase::getSelectedValueLabels()`) also read raw `getValues()`, so altered values render without a human-readable label in scope summaries, agent context tables, and list builders. - **Matching** never touches `getValues()` — `AiContextScopeResolver` intersects stored value IDs directly — so the docblock's "or for matching" claim is also inaccurate. Net effect: a value added via the documented public hook matches at runtime but is invisible and unselectable in the UI. ### Real-world impact `ai_empathy`'s `ai_empathy_ccc` submodule registers an `empathy_evaluation` use case via this hook, then has to re-apply the altered values by hand on both the scenario form and the `ai_context_item` form (`_ai_empathy_ccc_apply_altered_scope_options()`) just to make the value selectable and labelled. That workaround should be unnecessary. ### Steps to reproduce 1. Implement `hook_ai_context_scope_values_alter()` to add a `use_case` value. 2. Edit a context item at `/admin/config/ai/context` → the new value is absent from the Use Cases checkboxes. 3. Store the value programmatically → its label is missing from scope summaries. ## Proposed resolution - Route `AiContextScopeBase::buildValueForm()` and `getSelectedValueLabels()` through the altered value set so the hook reaches forms and labels. - Fix the `hook_ai_context_scope_values_alter()` docblock and `docs/developers/hooks.md` to describe accurately where the hook applies (forms and labels; not matching, which uses stored IDs). ## Remaining tasks - [ ] Wire altered values into `buildValueForm()` and `getSelectedValueLabels()`. - [ ] Correct the hook docblock + hooks documentation. - [ ] Add a kernel test covering the full loop: alter hook adds a value → value is selectable in the scope form → stored on a context item → returned by `AiContextRequestFactory::getRenderedContext()` and rendered with its label. (No core test exercises the hook through the form/label path, which is why this regressed.) ## User interface changes Altered scope values become selectable in context item and agent forms and display correct labels in summaries and listings. ## AI usage - [x] AI assisted issue