refactor(caller): Protocol HookCaller, split callers, CompletionHook multicall

Complete design step 05:

- HookCaller is now a @runtime_checkable Protocol; concrete callers are
  NormalHookCaller (split list[NormalImpl] / list[WrapperImpl] storage),
  HistoricHookCaller (memorize/replay, rejects wrappers) and
  SubsetHookCaller (read-only filtered proxy). _HookCaller and
  _SubsetHookCaller remain as compat aliases.
- _multicall takes dual sequences and orchestrates phases only: wrapper
  setup collects CompletionHooks, normals run, completion hooks run LIFO
  and may replace (result, exception) - no wrapper flag branching.
- add_hookspecs hands a NormalHookCaller over to a HistoricHookCaller
  when a historic spec arrives after impl registration.
- PluginManager._hookexec and tracing use the dual-sequence signature;
  monitoring callbacks keep receiving one combined impl list.
- HookSpec.verify_all_args_are_provided replaces the caller-side helper;
  set_specification accepts a config object or legacy mapping (shim).
- New tests: protocol isinstance for all concretes, historic handover,
  historic direct-call/call_extra rejection.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: RonnyPfannschmidt

changelog/707.feature.rst

@@ -0,0 +1,12 @@
+:class:`pluggy.HookCaller` is now a runtime-checkable
+:class:`~typing.Protocol` implemented by the new concrete callers
+:class:`pluggy.NormalHookCaller` (split normal/wrapper implementation
+lists), :class:`pluggy.HistoricHookCaller` (call memorization and replay,
+no wrappers) and :class:`pluggy.SubsetHookCaller`.
+``isinstance(caller, HookCaller)`` keeps working for all of them.
+
+The hook execution engine now runs a dual-sequence multicall: wrappers own
+their setup/teardown through ``CompletionHook`` callbacks which run LIFO
+after the normal implementations, removing all wrapper flag branching from
+the hot loop. Hook call monitoring callbacks still receive a single
+combined implementation list.

docs/api_reference.rst

@@ -29,6 +29,17 @@ API Reference
     :members:
     :special-members: __call__
 
+.. autoclass:: pluggy.NormalHookCaller()
+    :members:
+    :special-members: __call__
+
+.. autoclass:: pluggy.HistoricHookCaller()
+    :members:
+    :special-members: __call__
+
+.. autoclass:: pluggy.SubsetHookCaller()
+    :members:
+
 .. autoclass:: pluggy.HookCallError()
     :show-inheritance:
     :members:

src/pluggy/__init__.py

@@ -3,6 +3,9 @@
     "PluginManager",
     "PluginValidationError",
     "HookCaller",
+    "NormalHookCaller",
+    "HistoricHookCaller",
+    "SubsetHookCaller",
     "HookCallError",
     "HookspecConfiguration",
     "HookimplConfiguration",
@@ -20,12 +23,15 @@
 ]
 from ._config import HookimplConfiguration
 from ._config import HookspecConfiguration
+from ._hooks import HistoricHookCaller
 from ._hooks import HookCaller
 from ._hooks import HookImpl
 from ._hooks import HookimplMarker
 from ._hooks import HookRelay
 from ._hooks import HookspecMarker
+from ._hooks import NormalHookCaller
 from ._hooks import NormalImpl
+from ._hooks import SubsetHookCaller
 from ._hooks import WrapperImpl
 from ._manager import PluginManager
 from ._manager import PluginValidationError