### Description `EntityHandleTransformSubscriberBase` (https://git.drupalcode.org/project/tool/-/work_items/3583011) cut the copied logic, but every connector still has to ship a subclass and an `event_subscriber` service to turn entity handles on. `tool_ai_connector`, `mcp_server_tool_bridge`, and `tool_test` each carry that pair. The connector already tells Tool API who it is at one place, `ToolManager::createInstance($id, [], 'mcp_server')`, and a bare string can only carry identity. Replace the string with an `Invoker` value object that also carries what the caller needs. Tool API ships one `EntityHandleTransformSubscriber` gated on that, and the connector's whole integration becomes the call site: ```php $tool = $this->toolManager->createInstance( $plugin_id, [], new Invoker('mcp_server', InvokerCapability::EntitiesAsHandles), ); ``` Capabilities are enum cases typed as `\UnitEnum`, so a contrib module can define its own enum for behavior its own subscribers gate on, checked with `$event->getInvoker()?->has(MyCapability::Case)`. No registry, no compiler pass. Anything a capability might otherwise configure (limits, formats) belongs on the typed data definitions and constraints, so capabilities stay flags. ### Proposed changes - `Drupal\tool\Tool\Invoker`: `readonly string $id`, variadic `\UnitEnum ...$capabilities`, `has()`, `from(string|self)`, `Stringable`. - `Drupal\tool\Tool\InvokerCapability` enum with one case, `EntitiesAsHandles`. - `ToolInterface::setInvoker()` and `ToolManager::createInstance()` accept `string|Invoker`. Strings still work and wrap to an `Invoker` with no capabilities. - `ToolInterface::getInvoker()` and the four event `getInvoker()` methods return `?Invoker` instead of `?string`. Subscribers that gate on identity compare `$event->getInvoker()?->id`. - `EntityHandleTransformSubscriber` registered in `tool.services.yml`, gated on `InvokerCapability::EntitiesAsHandles`. Same handler bodies as the base class. - Remove `EntityHandleTransformSubscriberBase`, `ToolAiConnectorEntityHandleTransformSubscriber`, `TestEntityHandleTransformSubscriber`, and their service definitions. `tool_ai_connector` passes the capability from `ToolPluginBase::getPluginInstance()`. - `tool.api.php` and `docs/developers/events.md` describe the call-site opt-in. ### API changes Breaking, acceptable in beta: - `getInvoker()` on `ToolInterface` and all four transform/normalize events returns `?Invoker`, not `?string`. - Event constructors take `?Invoker $invoker`. - `EntityHandleTransformSubscriberBase` is removed. `mcp_server_tool_bridge` follows in https://git.drupalcode.org/project/mcp_server_tool_bridge/-/work_items/3613896, where the subscriber and services.yml go away. ### Tasks - [ ] `Invoker` and `InvokerCapability` - [ ] Thread `Invoker` through `ToolBase`, `ToolManager`, the four events, `RecursiveToolValueTransformSubscriber`, `ToolDefinitionSerializer` - [ ] Concrete `EntityHandleTransformSubscriber`, remove the base class and both subclasses - [ ] Update `tool_ai_connector` call site - [ ] Docs: `tool.api.php`, `docs/developers/events.md` - [ ] Tests: rename `EntityHandleTransformSubscriberBaseTest`, update invoker comparisons - [ ] Tests: a capability enum defined in `tool_test`, proving contrib can gate its own subscribers ### AI usage (if applicable) - [x] **AI Assisted Issue:** This issue was generated with AI assistance, but was reviewed and refined by the creator. - [ ] **AI Assisted Code:** This code was mainly generated by a human, with AI autocompleting or parts AI generated, but under full human supervision. - [x] **AI Generated Code:** This code was mainly generated by an AI with human guidance, and reviewed, tested, and refined by a human. - [ ] **Vibe Coded:** This code was generated by an AI and has only been functionally tested.