## Problem/Motivation The `ai_tools_library` form element treats its value as a _set_ of function call plugin ids. A tool is either selected, or it is not, and the element has no way to express "this tool, twice, configured each time differently. That is a real limitation for consumers who can configure each occurrence separately. \[#3552038\] in AI Agents does exactly this: an agent stores a list of tool _instances_, each with its own function name and settings, so one generic tool (a node lookup, an HTTP call, a sub-agent) can be offered to the LLM several times with different configurations. The agent form uses `ai_tools_library` to pick those tools, so the feature stops at the picker: the element cannot accept, render, or return a repeated tool id, and the feature ends up only usable for programmatically written config. Working around this in the consuming module means unbinding the element's own JavaScript and patching its render array from an `#after_build`, which is what the first iteration of the AI Agents MR had to do. That is fragile and does not belong in the contrib; the element should offer the behavior itself, behind an explicit opt-in. There is also a smaller latent bug in the current behaviour. The modal _appends_ its selection to the hidden field (`setToolsFieldValue()` concatenates), and `Drupal.AiToolsLibrary.currentSelection` is cleared on `dialog:afterclose`, so the checkboxes are unchecked again on the next visit. Re-selecting a tool that is already selected therefore submits its id twice. Nothing collapses that: `ToolsLibrary::processToolsIds()` does not deduplicate, so the duplicate reaches the consumer's value, while `processToolsLibrary()` keys the rendered items by tool id and silently collapses them to one. The user sees one item, the stored value has two. ## Steps to reproduce 1. Put an `ai_tools_library` element on a form. 2. Select a tool, save, and reload the form. 3. Open the modal again and select the same tool. 4. The widget still shows one item, but the submitted value contains the id twice. ## Proposed resolution Add an `#allow_duplicates` option to the element, defaulting to `FALSE` So nothing changes for existing consumers. With the option **off** (the default, and the fix for the bug above): - `::valueCallback()` collapses repeats and re-keys, so the value is always a list of distinct ids. - `::processToolsLibrary()` collapses repeats coming from `#default_value` too, so a repeat can never reach the hidden field and be submitted back. With the option **on**: - The value is a list that may repeat an id, in the order the occurrences were selected. Position identifies an occurrence, which is what the consumer aligns its per-occurrence data to. - Selected items are keyed by position rather than by tool id, so each occurrence renders as its own item instead of overwriting the previous one. - An occurrence of a tool that appears more than once is numbered `Calculator (1)`, `Calculator (2)`. A tool selected only once keeps its plain name, so agents that never repeat a tool are not renamed. - The theme hook gains an `instance_index` variable, exposed as `data-instance-index` on the remove button, and the hidden field carries `data-ai-tools-library-allow-duplicates`. The remove handler in `ai_tools_library_form_element.js` uses those to remove one occurrence rather than every copy of the tool. - Adding a further occurrence is done by reopening the modal and selecting the tool again — the modal appends, so each visit adds one more occurrence. The option changes only what the element accepts and returns. It adds no per-occurrence configuration of its own; naming and configuring the occurrences remain with the consumer, where the meaning lives. ## Remaining tasks - [ ] Decide whether the default-off deduplication is in scope here or should be split into its own bug report against 1.4.x. - [ ] Coordinate the merge with \[#3552038\] in AI Agents, which is blocked on this. ## User interface changes None for existing consumers. For a consumer who opts in, repeated tools render as separate numbered items, each with its own remove button. ## API changes Additive only: - New element property `#allow_duplicates` (bool, defaults to `FALSE`). - New `ai_tools_library_item` theme variable `instance_index` (defaults to `NULL`). - New `data-instance-index` attribute on the remove button, and `data-ai-tools-library-allow-duplicates` on the hidden value field. Behaviour change for the default path: a value that repeats an id is now collapsed rather than passed through. That is the documented contract of the element (a set of selected tools), so a consumer relying on the repeat reaching it would have been relying on the bug. ## Data model changes None.