### Problem/Motivation Every connector that wants entity handles has to ship a ~220 line event subscriber. Three copies exist today: - `tool_ai_connector/src/EventSubscriber/ToolAiConnectorEntityHandleTransformSubscriber.php` - `tool_test/src/EventSubscriber/TestEntityHandleTransformSubscriber.php` - `mcp_server_tool_bridge/src/EventSubscriber/EntityHandleSubscriber.php` ([#3613896](https://www.drupal.org/project/mcp_server_tool_bridge/issues/3613896), in review) The bridge copy diffs against the AI connector copy in exactly three places: namespace, class name, invoker constant. Everything else is byte-identical logic: the invoker gate on four events, the batch list path, the single path, the batch hint builder, `isEntityListDefinition()`. Each copy also drops the why-comments from the original, so the reasoning behind `stopPropagation()` and the batch path erodes with every fork. `EntityHandleTransformer`'s docblock says "Connector modules delegate to this after their own invoker checks." The delegation is the 200 lines. The invoker check is one line. ### Proposed resolution Move the subscriber into `tool` as an abstract base. Connectors supply the invoker ID. ```php namespace Drupal\tool\EventSubscriber; abstract class EntityHandleTransformSubscriberBase implements EventSubscriberInterface { public function __construct( protected readonly EntityHandleTransformer $entityHandleTransformer, ) {} abstract protected function getInvokerId(): string; public static function getSubscribedEvents(): array { return [ ToolInputTransformEvent::class => ['onInputTransform', 100], ToolOutputTransformEvent::class => ['onOutputTransform', 100], ToolInputDefinitionNormalizeEvent::class => ['onInputDefinitionNormalize', 100], ToolOutputDefinitionNormalizeEvent::class => ['onOutputDefinitionNormalize', 100], ]; } public function onInputTransform(ToolInputTransformEvent $event): void { if ($event->getInvoker() !== $this->getInvokerId()) { return; } // Existing single-path logic. } // onOutputTransform(), onInputDefinitionNormalize(), // onOutputDefinitionNormalize(), transformBatchOutput(), buildBatchHint() // move here unchanged. } ``` A connector becomes: ```php final class ToolAiConnectorEntityHandleTransformSubscriber extends EntityHandleTransformSubscriberBase { protected function getInvokerId(): string { return ToolAiConnectorInvoker::ID; } } ``` While consolidating, fix two things the copies carry: **Input batch path is redundant.** `RecursiveToolValueTransformSubscriber` at -100 already re-dispatches per item with a non-multiple clone of the definition, and the single path resolves each one. For `ListContextDefinition` the single path is already a no-op (`isContentEntityDefinition()` returns FALSE for data type `list`), so recursion is the only thing resolving those items today. Delete the input batch block. Keep the output batch path: its job is one summarized hint instead of per-item hints. **`stopPropagation()` is not needed for correctness.** `resolveInput()` passes an already-resolved entity through (`hasHandlePrefix()` is `is_string`-guarded) and `transformOutput()` returns NULL for a handle string, so the recursive re-walk is a no-op on both sides. The stop blocks `InputTypeCoercionSubscriber` at 50 and any third-party subscriber below 100. Remove it from the input side with the batch block. On the output side, either remove it or document that it exists to suppress per-item hints from the recursive dispatch. "So lower-priority subscribers do not re-walk" describes an optimization, not a contract. Remaining tasks: - [ ] Add `EntityHandleTransformSubscriberBase`. - [ ] Convert `tool_ai_connector` and `tool_test` subscribers to extend it. - [ ] Drop input batch path and input-side `stopPropagation()`; decide on output side. - [ ] Kernel coverage in `tool` for: multiple entity input as array of handles, bare handle string for a multiple input (coercion wraps it after resolution), JSON-encoded list of handles, `ListContextDefinition` of entities. - [ ] Document in `tool.api.php` (#3582966). API changes: new abstract class `Drupal\tool\EventSubscriber\EntityHandleTransformSubscriberBase`. Existing connector subscribers keep their service IDs and class names. ### Alternatives considered - **Single concrete subscriber in `tool` with a registry of invoker IDs.** Connectors would tag a service or implement an interface to opt in. More moving parts than an abstract method, and connectors lose the ability to override one handler when they need to. - **Leave it to connectors.** The current state. Three copies already diverge in comments; the next connector will diverge in behavior. ### 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. - [ ] **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.