power-loop 3.0.2__tar.gz → 3.2.0__tar.gz

{power_loop-3.0.2 → power_loop-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.0.2
+Version: 3.2.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -161,7 +161,8 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
 | **Hooks & events** | Veto/observe at every lifecycle point; strongly-typed event payloads | [Hooks](docs/en/user-guide/hooks.md) · [Events](docs/en/user-guide/events.md) |
 | **Structured output** | `output_schema` → provider `response_format` → parsed & validated | [Structured](docs/en/user-guide/structured-output.md) |
-| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol | [Memory](docs/en/user-guide/memory.md) |
+| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol; a default-on built-in hook injects it ephemerally at the request tail (prefix-cacheable) | [Memory](docs/en/user-guide/memory.md) |
+| **Hook-injection audit** | Optionally record the ephemeral context `LLM_BEFORE` hooks inject each round (e.g. recalled memory) into `pl_hook_events` — observability only, never re-enters history/the request | [Hook-events audit](docs/en/user-guide/hook-events-audit.md) |
 | **Retry / cancel / budgets** | Provider-aware retry, a unified cancellation token, hard per-run token caps | [Retry & Cancel](docs/en/user-guide/retry-cancel.md) |
 | **Stable error codes** | Every `PowerLoopError` carries a frozen machine-readable `code` — branch on `exc.code` | [API: error codes](docs/en/api/index.md#error-codes) |
 | **Crash recovery** | `heal_pending` / `resume` / `abort_pending` for runs killed mid tool-call | [Pending recovery](docs/en/user-guide/sessions.md#pending-recovery) |

{power_loop-3.0.2 → power_loop-3.2.0}/README.md

@@ -88,7 +88,8 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **MCP tools** | Surface a Model Context Protocol server's tools as power-loop tools | [Extending](docs/en/user-guide/extending-tools.md) |
 | **Hooks & events** | Veto/observe at every lifecycle point; strongly-typed event payloads | [Hooks](docs/en/user-guide/hooks.md) · [Events](docs/en/user-guide/events.md) |
 | **Structured output** | `output_schema` → provider `response_format` → parsed & validated | [Structured](docs/en/user-guide/structured-output.md) |
-| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol | [Memory](docs/en/user-guide/memory.md) |
+| **Pluggable memory** | Cross-session recall via a `MemoryProvider` Protocol; a default-on built-in hook injects it ephemerally at the request tail (prefix-cacheable) | [Memory](docs/en/user-guide/memory.md) |
+| **Hook-injection audit** | Optionally record the ephemeral context `LLM_BEFORE` hooks inject each round (e.g. recalled memory) into `pl_hook_events` — observability only, never re-enters history/the request | [Hook-events audit](docs/en/user-guide/hook-events-audit.md) |
 | **Retry / cancel / budgets** | Provider-aware retry, a unified cancellation token, hard per-run token caps | [Retry & Cancel](docs/en/user-guide/retry-cancel.md) |
 | **Stable error codes** | Every `PowerLoopError` carries a frozen machine-readable `code` — branch on `exc.code` | [API: error codes](docs/en/api/index.md#error-codes) |
 | **Crash recovery** | `heal_pending` / `resume` / `abort_pending` for runs killed mid tool-call | [Pending recovery](docs/en/user-guide/sessions.md#pending-recovery) |

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "3.0.2"
+__version__ = "3.2.0"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).
@@ -154,9 +154,15 @@ from power_loop.runtime.fold import (
     NoteOp,
 )
 from power_loop.runtime.human_input import HumanInputRequired, request_user_input
-from power_loop.runtime.memory import MemoryProvider, MemorySnapshot, tag_as_memory
+from power_loop.runtime.memory import (
+    MemoryProvider,
+    MemoryRecallHook,
+    MemorySnapshot,
+    tag_as_memory,
+)
 from power_loop.runtime.notes import (
     DEFAULT_NOTES_POLICY,
+    NoteMemory,
     NotesFullError,
     NotesPolicy,
     SQLiteNoteMemory,
@@ -199,6 +205,7 @@ from power_loop.runtime.store.store import (
     SessionStore,
 )
 from power_loop.runtime.store.types import (
+    HookEventRow,
     MessageRow,
     MessageState,
     ProjectMessageRow,
@@ -305,6 +312,7 @@ __all__ = [
 	"SessionKind",
 	"SubagentLifecycle",
 	"MessageRow",
+	"HookEventRow",
 	"MessageState",
 	"MAX_SPAWN_DEPTH",
 	"DEFAULT_DB_PATH",
@@ -361,10 +369,12 @@ __all__ = [
 	"LlmDegradedPayload",
 	"LoopCancelledPayload",
 	"MemoryProvider",
+	"MemoryRecallHook",
 	"MemorySnapshot",
 	"tag_as_memory",
 	"NotesPolicy",
 	"NotesFullError",
+	"NoteMemory",
 	"SQLiteNoteMemory",
 	"DEFAULT_NOTES_POLICY",
 	"render_notes",

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/agent/sink.py

@@ -32,7 +32,6 @@ class MessageSink(Protocol):
 
     async def on_round_started(self, round_index: int) -> None: ...
     async def on_message_appended(self, message: LoopMessage, *, round_index: int | None) -> None: ...
-    def on_messages_inserted(self, *, index: int, count: int) -> None: ...  # pure (no I/O) → sync
     async def on_assistant_tool_calls(
         self, *, assistant_seq: int, tool_calls: list[dict[str, Any]], round_index: int
     ) -> None: ...
@@ -57,7 +56,6 @@ class NullSink:
 
     async def on_round_started(self, round_index: int) -> None: ...
     async def on_message_appended(self, message: LoopMessage, *, round_index: int | None) -> None: ...
-    def on_messages_inserted(self, *, index: int, count: int) -> None: ...
     async def on_assistant_tool_calls(
         self, *, assistant_seq: int, tool_calls: list[dict[str, Any]], round_index: int
     ) -> None: ...
@@ -129,16 +127,12 @@ class SQLiteSink:
         self._history_seqs = list(seqs)
         self._history_ord = list(ords) if ords is not None else list(seqs)
 
-    def on_messages_inserted(self, *, index: int, count: int) -> None:
-        """Record that ``count`` in-memory-only messages were spliced into
-        ``pipeline.history`` at ``index`` without being persisted (recalled
-        ``memory_*``). Insert matching ``None`` placeholders so ``_history_seqs``
-        stays index-aligned with ``history`` and later folds map to the right rows."""
-        if count <= 0:
-            return
-        idx = max(0, min(index, len(self._history_seqs)))
-        self._history_seqs[idx:idx] = [None] * count
-        self._history_ord[idx:idx] = [None] * count
+    # NOTE: on_messages_inserted was removed when memory recall moved to the
+    # ephemeral tail-injection LLM_BEFORE hook (it never enters self.history, so
+    # there is no in-memory-only row to align). The _history_seqs/_history_ord
+    # maps stay `list[int | None]` and on_compaction keeps its None-guards: those
+    # remain load-bearing for projection mode (seeds None prefixes) and for
+    # corrupt-history repair (align_tool_calls synthesizes placeholders).
 
     # ── messages ───────────────────────────────────────────────
 
@@ -203,6 +197,7 @@ class SQLiteSink:
                 round_index=round_index,
                 meta=message.get("meta"),
                 send_index=message.get("send_index"),
+                hook_injected=message.get("hook_injected"),
             )
             self._history_seqs.append(seq)
             self._history_ord.append(seq)

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/agent/stateful_loop.py

@@ -31,10 +31,7 @@ from power_loop._vendor.llm_client.interface import LLMService
 from power_loop.agent.follow_up import FollowUpQueued, merge_follow_up_inputs
 from power_loop.agent.sink import SQLiteSink
 from power_loop.agent.system_prompt import (
-    DEFAULT_AGENT_SYSTEM_PROMPT,
-    SystemPromptContext,
-    format_tool_catalog,
-    section_skills,
+    resolve_runtime_system_prompt,
 )
 from power_loop.agent.types import AgentLoopConfig, AgentLoopResult, LoopMessage
 from power_loop.contracts.errors import SessionNotFoundError, SessionPendingError
@@ -51,7 +48,6 @@ from power_loop.core.runner import AgentRunner
 from power_loop.runtime.budget import estimate_tokens
 from power_loop.runtime.cancellation import CancellationLike
 from power_loop.runtime.history_sanitize import align_tool_calls
-from power_loop.runtime.skills import SkillLoader
 from power_loop.runtime.store.schema import SchemaPolicy
 from power_loop.runtime.store.store import (
     DEFAULT_DB_PATH,
@@ -210,7 +206,13 @@ class StatefulAgentLoop:
         self._orphaned_close_task: asyncio.Future[None] | None = None
         self.config = config if config is not None else AgentLoopConfig()
         self.tool_registry = tool_registry
-        self._runner = AgentRunner(event_bus=event_bus, hooks=hooks)
+        # Own a FRESH AgentHooks when the caller supplies none — NOT the shared
+        # module-level DEFAULT_HOOKS singleton — so per-loop built-in hooks (e.g.
+        # the memory recall hook) don't stack across loops or leak config.
+        self._runner = AgentRunner(
+            event_bus=event_bus, hooks=hooks if hooks is not None else AgentHooks()
+        )
+        self._register_builtin_hooks()
         self._locks: dict[str, asyncio.Lock] = {}
         self._follow_up_queues: dict[str, list[str | LoopMessage]] = {}
         self._follow_up_queue_locks: dict[str, asyncio.Lock] = {}
@@ -222,6 +224,33 @@ class StatefulAgentLoop:
         self._cache_misses = 0
         self._cache_evictions = 0
 
+    def _register_builtin_hooks(self) -> None:
+        """Register power-loop's default functional hooks on this loop's own
+        AgentHooks. They carry a ``builtin.*`` name so a host can override them
+        (``hooks.replace(..., name=...)``) or disable them (``hooks.remove(...)``).
+        """
+        cfg = self.config
+        if cfg.memory is not None and getattr(cfg, "builtin_memory_hook", True):
+            from power_loop.contracts.hooks import HookPoint
+            from power_loop.runtime.memory import MemoryRecallHook
+
+            hook = MemoryRecallHook(
+                cfg.memory,
+                budget_tokens=int(cfg.memory_budget_tokens or 0),
+                position=getattr(cfg, "memory_position", "tail"),
+                hooks=self._runner.hooks,
+                event_bus=self._runner.event_bus,
+            )
+            # order=100 → runs AFTER host LLM_BEFORE hooks (default order 0) so
+            # memory lands at the true request tail. Skip if the host already
+            # registered one under this name (their override wins); a host can
+            # also override/disable post-construction via loop.hooks.replace /
+            # .remove(MemoryRecallHook.NAME).
+            if not self._runner.hooks.has(MemoryRecallHook.NAME):
+                self._runner.hooks.register(
+                    HookPoint.LLM_BEFORE, hook, order=100, name=MemoryRecallHook.NAME,
+                )
+
     async def ensure_store(self) -> SessionStore:
         """Public accessor: return this loop's store, opening an owned one on first use.
 
@@ -906,9 +935,14 @@ class StatefulAgentLoop:
         Returns
         -------
         str
-            The fully resolved prompt string — exactly what the LLM
-            will see as the system message on the next :meth:`send`
-            call.
+            The fully resolved prompt for a :meth:`send` with **no per-call
+            overrides** — base (session/config) + auto-injected tool catalog
+            (full registry) + skill section, via the same
+            ``resolve_runtime_system_prompt`` helper the live pipeline uses.
+
+            A per-call ``send(system_prompt=...)`` or ``send(tools=[...])`` is
+            applied at send time and is NOT reflected here (this previews the
+            no-override case; pass nothing at ``send`` for a byte-identical match).
         """
         # Session-level prompt wins over config-level prompt.
         base: str | None = None
@@ -917,36 +951,18 @@ class StatefulAgentLoop:
             row = await store.get_session(session_id)
             if row is not None:
                 base = row.system_prompt
-
         if base is None or not base.strip():
-            base = self.config.system_prompt or DEFAULT_AGENT_SYSTEM_PROMPT
-
-        base = base.strip()
-
-        if self.config.inject_tool_descriptions and self.tool_registry is not None:
-            catalog = format_tool_catalog(
-                self.tool_registry,
-                header=self.config.tool_catalog_header,
-            )
-            if catalog:
-                base = f"{base}\n\n{catalog}"
-
-        skills = None
-        if self.config.skills_dir:
-            try:
-                loader = SkillLoader(self.config.skills_dir)
-                skills = section_skills(
-                    SystemPromptContext(
-                        skills_dir=str(loader.skills_dir),
-                        skill_descriptions=loader.get_descriptions(),
-                    )
-                )
-            except Exception:
-                skills = None
-        if skills:
-            base = f"{base}\n\n{skills}"
-
-        return base
+            base = self.config.system_prompt
+
+        # Shared assembly — the SAME helper AgentPipeline.__init__ uses — so this
+        # preview is byte-identical to what the LLM actually receives.
+        return resolve_runtime_system_prompt(
+            base,
+            inject_tool_descriptions=self.config.inject_tool_descriptions,
+            tool_catalog_header=self.config.tool_catalog_header,
+            tool_registry=self.tool_registry,
+            skills_dir=self.config.skills_dir,
+        )
 
     # ── internals ─────────────────────────────────────────────────────────
 
@@ -1645,7 +1661,9 @@ class StatefulAgentLoop:
             if len(live_sends) <= keep:
                 return None, ()  # nothing foldable beyond the keep-recent floor
             trigger_ratio = float(getattr(fold_strategy, "trigger_ratio", 0.75) or 0.75)
-            threshold = int((self.config.max_tokens or 8000) * trigger_ratio)
+            # Reserve headroom for the ephemeral tail-injected memory block (not
+            # part of the projected snapshot, so invisible here) — fold earlier.
+            threshold = int((self.config.effective_context_budget() or 8000) * trigger_ratio)
             rendered_prefix = projector.render(([prior] if prior is not None else []) + snapshot)
             if estimate_tokens(rendered_prefix) < threshold:
                 return None, ()  # below threshold — small per-send projections just accumulate

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/agent/system_prompt.py

@@ -417,6 +417,56 @@ DEFAULT_EXPLORE_SUBAGENT_SYSTEM_PROMPT = (
 ).build(SystemPromptContext())
 
 
+def build_skill_section(skills_dir: str | None) -> str:
+    """Render the auto-injected skill-catalog section for ``skills_dir``.
+
+    Returns ``""`` when no skills_dir is set or loading fails. Lazy-imports
+    SkillLoader to avoid a core↔runtime import cycle.
+    """
+    if not skills_dir:
+        return ""
+    try:
+        from power_loop.runtime.skills import SkillLoader
+
+        loader = SkillLoader(skills_dir)
+        section = section_skills(
+            SystemPromptContext(
+                skills_dir=str(loader.skills_dir),
+                skill_descriptions=loader.get_descriptions(),
+            )
+        )
+        return section or ""
+    except Exception:
+        return ""
+
+
+def resolve_runtime_system_prompt(
+    base: str | None,
+    *,
+    inject_tool_descriptions: bool,
+    tool_catalog_header: str,
+    tool_registry: Any,
+    skills_dir: str | None,
+) -> str:
+    """Single source of truth for runtime system-prompt assembly:
+    ``base → tool catalog → skill section`` (each joined by ``"\\n\\n"``).
+
+    Shared by :meth:`AgentPipeline.__init__` (the live prompt) and
+    :meth:`StatefulAgentLoop.resolve_system_prompt` (the preview), so the two
+    can never drift. Callers resolve ``base`` themselves (config vs session
+    override) and pass it in; everything after is computed here once.
+    """
+    out = (base or DEFAULT_AGENT_SYSTEM_PROMPT).strip()
+    if inject_tool_descriptions and tool_registry is not None:
+        catalog = format_tool_catalog(tool_registry, header=tool_catalog_header)
+        if catalog:
+            out = f"{out}\n\n{catalog}"
+    skill = build_skill_section(skills_dir)
+    if skill:
+        out = f"{out}\n\n{skill}"
+    return out
+
+
 def build_agent_system_prompt(
     ctx: SystemPromptContext,
     extra: str | None = None,

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/agent/types.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import warnings
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal
@@ -111,6 +112,54 @@ class AgentLoopConfig:
     retry_policy: LLMRetryPolicy | None = None
     memory: MemoryProvider | None = None
     memory_budget_tokens: int = 1500
+    #: Where the built-in MemoryRecallHook injects recalled memory into the
+    #: per-call request: "tail" (default — after history, keeps the prior-history
+    #: prefix byte-stable and prefix-cacheable) or "front" (after leading system
+    #: messages — legacy position; breaks prefix caching when memory changes).
+    memory_position: str = "tail"
+    #: Auto-register the built-in MemoryRecallHook when ``memory`` is set. Turn
+    #: off to inject memory yourself via an LLM_BEFORE hook.
+    builtin_memory_hook: bool = True
+
+    # ── Microcompact (large tool-output spill-to-disk) ──
+    #
+    # A cheap, no-LLM per-round mechanism that replaces OLD oversized tool
+    # outputs (older than the hot tail) with a short on-disk pointer, to save
+    # context tokens — orthogonal to the LLM-summary fold/compactor. Verbatim
+    # mode only (projection renders finished sends from the projection store).
+    #
+    # DEFAULT OFF as of 3.1.x: it only helps when those old outputs are never
+    # needed again; otherwise the pointer just trades for a re-read. Projection
+    # mode + fold + provider prefix-caching already cover context budget. Turn it
+    # on for long verbatim sessions that read many large files and rarely revisit
+    # the old ones. The thresholds default from the legacy CONTEXT_MICRO_* env
+    # vars for back-compat; the config fields take precedence.
+    microcompact_enabled: bool = False
+    microcompact_size_limit: int = field(
+        default_factory=lambda: int(os.getenv("CONTEXT_MICRO_SIZE_LIMIT", "1000"))
+    )
+    microcompact_hot_tail: int = field(
+        default_factory=lambda: int(os.getenv("CONTEXT_MICRO_HOT_TAIL", "10"))
+    )
+    #: Where spilled outputs are written. None → the runtime home's ``.cache``.
+    microcompact_spill_dir: str | None = None
+    # Audit the EPHEMERAL context that LLM_BEFORE hooks inject per round (e.g. recalled memory),
+    # which otherwise vanishes after the call. Recorded into the {prefix}hook_events store table,
+    # linked to the round's assistant message; observability ONLY — never read back into history or
+    # the LLM request, so it can't change context or prefix-caching.
+    #   "off"      — do not capture (default; zero overhead).
+    #   "metadata" — record name/source/char-count/position per injected item, NOT the text.
+    #   "full"     — also record the injected content text. NOTE: stored VERBATIM with no per-item
+    #                cap, so the audit table grows with large RAG/memory blocks — use "metadata" if
+    #                volume is a concern.
+    # ONE row is written per ROUND (the LLM_BEFORE hook runs each round; the builtin memory block is
+    # memoized once per send but re-injected every round), so a multi-round send yields one audit row
+    # per round. Assumes LLM_BEFORE handlers MUTATE ctx.messages in place (the builtin contract) and
+    # captures only APPENDED injection, not in-place edits of existing messages. A handler that
+    # REPLACES all or most of ctx.messages with fresh copies makes the per-injection diff
+    # unresolvable — the row is then a small "inject_unresolved" marker (still never affects
+    # context/cache).
+    record_hook_events: str = "off"
     # Bounds for the note_add/note_update/note_delete tools (agent-authored
     # notes). None → DEFAULT_NOTES_POLICY. See power_loop.runtime.notes.
     notes_policy: NotesPolicy | None = None
@@ -132,9 +181,36 @@ class AgentLoopConfig:
     inject_tool_descriptions: bool = True
     tool_catalog_header: str = "# Available Tools"
 
+    def effective_context_budget(self) -> int:
+        """Fold/compaction budget after reserving headroom for the ephemeral
+        memory block.
+
+        Memory is injected at the per-call tail by the built-in hook and is NOT
+        counted by the fold trigger (it isn't in ``self.history``). To keep
+        ``history + memory`` within the model window, the fold threshold targets
+        ``max_tokens − memory_budget_tokens`` so folding fires early enough.
+        ``0``/``None`` max_tokens means "no explicit budget" → returned
+        unchanged.
+        """
+        mt = int(self.max_tokens or 0)
+        if mt <= 0:
+            return mt
+        if self.memory is not None and self.builtin_memory_hook:
+            return max(1, mt - int(self.memory_budget_tokens or 0))
+        return mt
+
     def __post_init__(self) -> None:
         self._map_legacy_axes()
         self._validate_context_config()
+        # record_hook_events is a closed enum; normalize case and reject typos loudly (consistent
+        # with the file's loud-config convention) rather than silently capturing nothing.
+        rhe = str(self.record_hook_events or "off").strip().lower()
+        if rhe not in ("off", "metadata", "full"):
+            raise ValueError(
+                "AgentLoopConfig: record_hook_events must be 'off' | 'metadata' | 'full'; "
+                f"got {self.record_hook_events!r}"
+            )
+        object.__setattr__(self, "record_hook_events", rhe)
         # Mark init complete so __setattr__ starts re-validating reassignments (the dataclass
         # is mutable; a post-hoc reassignment of an axis or max_tokens must stay valid).
         object.__setattr__(self, "_initialized", True)

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/contracts/hook_contexts.py

@@ -122,7 +122,9 @@ class LlmBeforeCtx(BaseHookCtx):
     """Context for :pyattr:`HookPoint.LLM_BEFORE`.
 
     Directives: SHORT_CIRCUIT (set ``output`` to an ``LLMResponse``), BREAK.
-    Handler may modify any input field.
+    Handler may modify any input field. ``messages`` is the fresh per-call list
+    actually sent to the LLM — mutating it (e.g. appending an ephemeral memory
+    block) never touches the loop's persisted history.
     """
 
     messages: list[LoopMessage] = field(default_factory=list)
@@ -130,6 +132,7 @@ class LlmBeforeCtx(BaseHookCtx):
     tools: list[dict[str, Any]] | None = None
     max_tokens: int = 8000
     temperature: float = 0.0
+    session_id: str | None = None
     # Handler output (for SHORT_CIRCUIT)
     output: LLMResponse | None = None
 

{power_loop-3.0.2 → power_loop-3.2.0}/power_loop/core/hooks.py

@@ -26,6 +26,7 @@ Legacy handlers that receive ``HookContext`` and return
 class _HookEntry:
     handler: HookHandlerFn
     order: int
+    name: str | None = None
 
 
 class AgentHooks:
@@ -45,10 +46,57 @@ class AgentHooks:
     def __init__(self) -> None:
         self._handlers: dict[str, list[_HookEntry]] = {}
 
-    def register(self, hook_point: HookPoint | str, handler: HookHandlerFn, *, order: int = 0) -> None:
+    def register(
+        self,
+        hook_point: HookPoint | str,
+        handler: HookHandlerFn,
+        *,
+        order: int = 0,
+        name: str | None = None,
+        replace: bool = False,
+    ) -> None:
+        """Register a handler at ``hook_point``.
+
+        ``name`` gives the entry a stable identity so it can later be
+        :meth:`remove`-d or :meth:`replace`-d — used by built-in hooks
+        (``builtin.*``) so hosts can override them. ``replace=True`` (with a
+        ``name``) drops any existing entry of the same name at this point first,
+        so re-registering is idempotent.
+        """
         key = str(hook_point)
-        self._handlers.setdefault(key, []).append(_HookEntry(handler=handler, order=order))
-        self._handlers[key].sort(key=lambda e: e.order)
+        entries = self._handlers.setdefault(key, [])
+        if name is not None and replace:
+            entries[:] = [e for e in entries if e.name != name]
+        entries.append(_HookEntry(handler=handler, order=order, name=name))
+        entries.sort(key=lambda e: e.order)
+
+    def replace(
+        self, hook_point: HookPoint | str, handler: HookHandlerFn, *, name: str, order: int = 0
+    ) -> None:
+        """Replace (or add) the named handler at ``hook_point``."""
+        self.register(hook_point, handler, order=order, name=name, replace=True)
+
+    def remove(self, name: str, hook_point: HookPoint | str | None = None) -> int:
+        """Remove every entry with ``name`` (optionally scoped to one point).
+
+        Returns the number of entries removed. Used to disable a built-in hook:
+        ``hooks.remove("builtin.memory_recall")``.
+        """
+        keys = [str(hook_point)] if hook_point is not None else list(self._handlers)
+        removed = 0
+        for key in keys:
+            entries = self._handlers.get(key)
+            if not entries:
+                continue
+            before = len(entries)
+            entries[:] = [e for e in entries if e.name != name]
+            removed += before - len(entries)
+        return removed
+
+    def has(self, name: str, hook_point: HookPoint | str | None = None) -> bool:
+        """Whether a named entry is registered (optionally scoped to one point)."""
+        keys = [str(hook_point)] if hook_point is not None else list(self._handlers)
+        return any(e.name == name for key in keys for e in self._handlers.get(key, []))
 
     def clear(self, hook_point: HookPoint | str | None = None) -> None:
         if hook_point is None: