power-loop 3.1.0__tar.gz → 3.3.0__tar.gz

{power_loop-3.1.0 → power_loop-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.1.0
+Version: 3.3.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -162,6 +162,7 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **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; 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.1.0 → power_loop-3.3.0}/README.md

@@ -89,6 +89,7 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **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; 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.1.0 → power_loop-3.3.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "3.1.0"
+__version__ = "3.3.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).
@@ -205,6 +205,7 @@ from power_loop.runtime.store.store import (
     SessionStore,
 )
 from power_loop.runtime.store.types import (
+    HookEventRow,
     MessageRow,
     MessageState,
     ProjectMessageRow,
@@ -311,6 +312,7 @@ __all__ = [
 	"SessionKind",
 	"SubagentLifecycle",
 	"MessageRow",
+	"HookEventRow",
 	"MessageState",
 	"MAX_SPAWN_DEPTH",
 	"DEFAULT_DB_PATH",

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/agent/sink.py

@@ -197,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.1.0 → power_loop-3.3.0}/power_loop/agent/types.py

@@ -143,6 +143,23 @@ class AgentLoopConfig:
     )
     #: 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
@@ -185,6 +202,15 @@ class AgentLoopConfig:
     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.1.0 → power_loop-3.3.0}/power_loop/core/pipeline.py

@@ -292,9 +292,79 @@ class AgentPipeline:
         ordering is preserved; the loop runs other sessions during the I/O."""
         await fn(*args, **kwargs)
 
+    # ── Helper: audit ephemeral LLM_BEFORE hook injections ──
+
+    @staticmethod
+    def _summarize_hook_injection(
+        final_messages: list[Any], pre_hook_ids: set[int] | None, mode: str
+    ) -> dict[str, Any] | None:
+        """Diff the post-LLM_BEFORE message list against the pre-hook identity snapshot to recover
+        exactly the messages a hook injected this round, and summarize them for the hook_events
+        audit. Returns None when auditing is off or nothing was injected. ``mode``: ``metadata``
+        (no text) or ``full`` (include injected ``content``). Identity-diff (not a tail slice) so it
+        captures both tail- and front-positioned injection."""
+        if mode not in ("metadata", "full") or pre_hook_ids is None:
+            return None
+        injected_idx = [i for i, m in enumerate(final_messages) if id(m) not in pre_hook_ids]
+        if not injected_idx:
+            return None
+        injected_set = set(injected_idx)
+        orig_idx = [i for i in range(len(final_messages)) if i not in injected_set]
+        # Rebind fail-safe: an LLM_BEFORE hook may REPLACE all or PART of ctx.messages with fresh
+        # copies (legal per LlmBeforeCtx, though the builtin memory hook mutates in place). Those
+        # copies are id-novel, so the identity diff would mislabel pre-existing turns as "injected"
+        # — in `full` mode that would dump the conversation into the audit. A genuine injection is a
+        # small minority of the request; so treat it as a rebind (record a small truthful marker, no
+        # content) when NOTHING survived id-stable OR the id-novel messages are an implausible
+        # majority. The >3 floor keeps short, legitimately memory-heavy sends from tripping it.
+        rebound = (not orig_idx) or (
+            len(injected_idx) > len(final_messages) / 2 and len(injected_idx) > 3
+        )
+        if pre_hook_ids and rebound:
+            return {
+                "hook_point": "LLM_BEFORE", "hook": "llm_before", "position": "unknown",
+                "kind": "inject_unresolved",
+                "payload": {
+                    "v": 1, "items": [], "item_count": len(injected_idx), "total_chars": 0,
+                    "rebound": True,
+                },
+            }
+        items: list[dict[str, Any]] = []
+        sources: set[str] = set()
+        for i in injected_idx:
+            m = final_messages[i]
+            name = m.get("name") if isinstance(m, dict) else None
+            content = m.get("content") if isinstance(m, dict) else None
+            text = content if isinstance(content, str) else ("" if content is None else str(content))
+            source = "builtin.memory_recall" if str(name or "").startswith("memory_") else "llm_before"
+            sources.add(source)
+            item: dict[str, Any] = {
+                "role": (m.get("role") if isinstance(m, dict) else None),
+                "name": name, "source": source, "chars": len(text),
+            }
+            if mode == "full":
+                item["content"] = text
+            items.append(item)
+        # Tail when every injected item sits after every pre-existing message; else front/mixed.
+        position = "tail" if (not orig_idx or min(injected_idx) > max(orig_idx)) else "front"
+        hook = next(iter(sources)) if len(sources) == 1 else "llm_before"
+        return {
+            "hook_point": "LLM_BEFORE", "hook": hook, "position": position, "kind": "inject",
+            "payload": {
+                "v": 1, "items": items, "item_count": len(items),
+                "total_chars": sum(int(it["chars"]) for it in items),
+            },
+        }
+
     # ── Helper: append message (with MESSAGE_APPEND hook) ──
 
-    async def _append_message(self, msg: LoopMessage, *, round_index: int | None = None) -> None:
+    async def _append_message(
+        self,
+        msg: LoopMessage,
+        *,
+        round_index: int | None = None,
+        hook_injected: dict[str, Any] | None = None,
+    ) -> None:
         ctx = MessageAppendCtx(
             round_index=round_index or 0,
             message=dict(msg),
@@ -307,13 +377,16 @@ class AgentPipeline:
         if self._tok_len == len(self.history) - 1:
             self._tok_total += estimate_message_tokens(ctx.message)
             self._tok_len = len(self.history)
-        # Carry the send_index to the sink — but ONLY on the copy handed to the sink, never on
-        # ctx.message (which lives in self.history and is sent verbatim to the LLM; an unknown
-        # field would leak / break the provider). The sink persists it into the messages.send_index
-        # column; it never reaches the LLM.
+        # Carry the send_index (and hook-injection audit) to the sink — but ONLY on the copy handed
+        # to the sink, never on ctx.message (which lives in self.history and is sent verbatim to the
+        # LLM; an unknown field would leak / break the provider). The sink persists send_index into
+        # the messages.send_index column and hook_injected into the hook_events table; neither
+        # reaches the LLM.
         sink_msg = ctx.message
         if self.send_index is not None:
-            sink_msg = {**ctx.message, "send_index": self.send_index}
+            sink_msg = {**sink_msg, "send_index": self.send_index}
+        if hook_injected is not None:
+            sink_msg = {**sink_msg, "hook_injected": hook_injected}
         await self._emit_sink(self.sink.on_message_appended, sink_msg, round_index=round_index)
 
     async def _resolve_skipped_tool_calls(
@@ -848,6 +921,16 @@ class AgentPipeline:
             runtime_messages = await self._runtime_messages_for_round(round_idx)
             llm_messages = [*self.history, *runtime_messages]
 
+            # Audit (opt-in): snapshot the message identities BEFORE LLM_BEFORE hooks run, so we can
+            # later diff out exactly what they ephemerally injected (e.g. recalled memory) for this
+            # round's LLM call — by identity, so it works regardless of inject position (tail/front).
+            _hook_audit_mode = self.config.record_hook_events
+            _pre_hook_ids = (
+                {id(m) for m in llm_messages}
+                if _hook_audit_mode in ("metadata", "full")
+                else None
+            )
+
             # ── Hook: LLM_BEFORE ──
             llm_before = LlmBeforeCtx(
                 round_index=round_idx,
@@ -859,6 +942,9 @@ class AgentPipeline:
                 session_id=self.session_id,
             )
             await self.hooks.run_typed_async(HookPoint.LLM_BEFORE, llm_before)
+            hook_audit = self._summarize_hook_injection(
+                llm_before.messages, _pre_hook_ids, _hook_audit_mode
+            )
 
             if llm_before.directive == HookDirective.SHORT_CIRCUIT:
                 response = llm_before.output
@@ -902,7 +988,10 @@ class AgentPipeline:
                         round_index=round_idx,
                     )
                     msg = f"[degraded: LLM {reason} — {type(inner).__name__}: {str(inner)[:200]}]"
-                    await self._append_message({"role": "assistant", "content": msg}, round_index=round_idx)
+                    await self._append_message(
+                        {"role": "assistant", "content": msg},
+                        round_index=round_idx, hook_injected=hook_audit,
+                    )
                     await self._finalize("degraded", final_text=msg, rounds=round_idx + 1)
                     return self._make_result("degraded", final_text=msg, rounds=round_idx + 1)
 
@@ -915,7 +1004,10 @@ class AgentPipeline:
                 await self.hooks.run_typed_async(HookPoint.LLM_AFTER, llm_after)
                 if llm_after.directive == HookDirective.BREAK:
                     text = (getattr(response, "raw_text", "") or "").strip()
-                    await self._append_message({"role": "assistant", "content": text}, round_index=round_idx)
+                    await self._append_message(
+                        {"role": "assistant", "content": text},
+                        round_index=round_idx, hook_injected=hook_audit,
+                    )
                     await self._finalize("hook_break", final_text=text, rounds=round_idx + 1)
                     return self._make_result("completed", final_text=text, rounds=round_idx + 1)
                 # After hook may replace the response
@@ -939,7 +1031,7 @@ class AgentPipeline:
             if tool_calls:
                 sanitized_tool_calls = _sanitize_tool_calls(tool_calls)
                 assistant_msg["tool_calls"] = sanitized_tool_calls
-            await self._append_message(assistant_msg, round_index=round_idx)
+            await self._append_message(assistant_msg, round_index=round_idx, hook_injected=hook_audit)
             # Mark pending IMMEDIATELY so a crash here leaves a recoverable state.
             if sanitized_tool_calls:
                 assistant_seq = len(self.history)  # 1-based position in history

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/runtime/representation.py

@@ -178,7 +178,8 @@ class VerbatimRepresentation:
 @dataclass
 class ProjectedRepresentation:
     """Generic, deterministic, no-LLM per-send projection. Each send →
-    ``user`` row: ``{"human": [<user inputs>]}`` (a LIST — folded follow-ups preserved) +
+    ``user`` row: ``{"input": [<user/trigger inputs, verbatim>]}`` (a LIST — folded follow-ups
+    preserved; pre-3.3 rows used the key ``human``) +
     ``project`` row: ``{"tools": [...], "final_text": ...}``. Each tool call is summarized via its
     ``ToolDefinition.project`` hook when present, else a truncating fallback. Rendered to terse
     plain text with NO tool-protocol structure. (This is the old ``DefaultDeterministicProjector``
@@ -220,9 +221,13 @@ class ProjectedRepresentation:
         seqs = [r.seq for r in send_rows]
         rows: list[ProjectedRow] = []
         if users:
-            rows.append(
-                ProjectedRow("user", {"human": [_truncate(u.content, self.max_chars) for u in users]})
-            )
+            # The INPUT side of a send (the user/trigger turn) is kept VERBATIM — it is the actual
+            # conversation content, it is short relative to tool output, and truncating it would drop
+            # context the model genuinely needs. Only the assistant's WORK (tool args/results +
+            # final_text) is compressed, which is where the token savings actually are. Key is
+            # ``input`` (the input turn — not necessarily a human; a multi-agent host feeds another
+            # agent's message here); pre-3.3 rows used ``human`` and are still read (see render()).
+            rows.append(ProjectedRow("user", {"input": [u.content for u in users]}))
         rows.append(
             ProjectedRow(
                 "project",
@@ -269,9 +274,14 @@ class ProjectedRepresentation:
         for r in rows:
             si = r.send_index
             if r.kind == "user":
-                humans = (r.content or {}).get("human") or []
+                content = r.content or {}
+                # ``input`` since 3.3; ``human`` is the pre-3.3 key — read both so old projection
+                # rows still render correctly after upgrade.
+                inputs = content.get("input")
+                if inputs is None:
+                    inputs = content.get("human") or []
                 tag = f"[#{si}] " if si is not None else ""
-                out.append({"role": "user", "content": tag + "\n".join(str(h) for h in humans)})
+                out.append({"role": "user", "content": tag + "\n".join(str(h) for h in inputs)})
             elif r.kind == "project":
                 tag = f"#{si} " if si is not None else ""
                 out.append({"role": "assistant", "content": tag + self._render_project(r.content)})

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/runtime/store/dialect.py

@@ -35,6 +35,13 @@ class Dialect(Protocol):
         :meth:`ddl` for fresh provisioning. Idempotent (CREATE … IF NOT EXISTS)."""
         ...
 
+    def hook_events_ddl(self, prefix: str) -> list[str]:
+        """DDL for the ``hook_events`` table + index (audit log of ephemeral hook
+        augmentations, e.g. LLM_BEFORE memory injection), split out so the v2→v3
+        migration can add just this table. Included in :meth:`ddl` for fresh
+        provisioning. Idempotent (CREATE … IF NOT EXISTS)."""
+        ...
+
     def upsert(
         self,
         table: str,
@@ -131,6 +138,7 @@ class SqliteDialect:
                 pinned INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL,
                 updated_at INTEGER NOT NULL, PRIMARY KEY (session_id, note_id))""",
             *self.project_messages_ddl(p),
+            *self.hook_events_ddl(p),
         ]
 
     def project_messages_ddl(self, prefix: str) -> list[str]:
@@ -147,6 +155,18 @@ class SqliteDialect:
             f"ON {p}project_messages(session_id, kind, send_index)",
         ]
 
+    def hook_events_ddl(self, prefix: str) -> list[str]:
+        p = prefix
+        return [
+            f"""CREATE TABLE IF NOT EXISTS {p}hook_events (
+                session_id TEXT NOT NULL, event_id INTEGER NOT NULL, message_seq INTEGER,
+                round_index INTEGER, send_index INTEGER, hook_point TEXT NOT NULL, hook TEXT,
+                position TEXT, kind TEXT NOT NULL, payload_json TEXT, created_at INTEGER NOT NULL,
+                PRIMARY KEY (session_id, event_id))""",
+            f"CREATE INDEX IF NOT EXISTS {p}idx_hook_events_session_msg "
+            f"ON {p}hook_events(session_id, message_seq)",
+        ]
+
     def upsert(self, table, key_cols, val_cols, *, add_cols=(), insert_only_cols=()):
         return _onconflict_upsert(table, key_cols, val_cols, add_cols, insert_only_cols)
 
@@ -260,6 +280,7 @@ class PostgresDialect:
                 pinned SMALLINT NOT NULL DEFAULT 0, created_at BIGINT NOT NULL,
                 updated_at BIGINT NOT NULL, PRIMARY KEY (session_id, note_id))""",
             *self.project_messages_ddl(p),
+            *self.hook_events_ddl(p),
         ]
 
     def project_messages_ddl(self, prefix: str) -> list[str]:
@@ -276,6 +297,18 @@ class PostgresDialect:
             f"ON {p}project_messages(session_id, kind, send_index)",
         ]
 
+    def hook_events_ddl(self, prefix: str) -> list[str]:
+        p = prefix
+        return [
+            f"""CREATE TABLE IF NOT EXISTS {p}hook_events (
+                session_id TEXT NOT NULL, event_id BIGINT NOT NULL, message_seq BIGINT,
+                round_index BIGINT, send_index BIGINT, hook_point TEXT NOT NULL, hook TEXT,
+                position TEXT, kind TEXT NOT NULL, payload_json TEXT, created_at BIGINT NOT NULL,
+                PRIMARY KEY (session_id, event_id))""",
+            f"CREATE INDEX IF NOT EXISTS {p}idx_hook_events_session_msg "
+            f"ON {p}hook_events(session_id, message_seq)",
+        ]
+
     def upsert(self, table, key_cols, val_cols, *, add_cols=(), insert_only_cols=()):
         return _onconflict_upsert(table, key_cols, val_cols, add_cols, insert_only_cols)
 
@@ -376,6 +409,7 @@ class MySQLDialect:
                 pinned TINYINT NOT NULL DEFAULT 0, created_at BIGINT NOT NULL,
                 updated_at BIGINT NOT NULL, PRIMARY KEY (session_id, note_id)) {opts}""",
             *self.project_messages_ddl(p),
+            *self.hook_events_ddl(p),
         ]
 
     def project_messages_ddl(self, prefix: str) -> list[str]:
@@ -392,6 +426,18 @@ class MySQLDialect:
                 KEY {p}idx_project_messages_session_kind (session_id, kind, send_index)) {opts}""",
         ]
 
+    def hook_events_ddl(self, prefix: str) -> list[str]:
+        p = prefix
+        opts = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4"
+        return [
+            f"""CREATE TABLE IF NOT EXISTS {p}hook_events (
+                session_id VARCHAR(255) NOT NULL, event_id BIGINT NOT NULL, message_seq BIGINT,
+                round_index BIGINT, send_index BIGINT, hook_point VARCHAR(32) NOT NULL, hook VARCHAR(255),
+                position VARCHAR(32), kind VARCHAR(32) NOT NULL, payload_json TEXT, created_at BIGINT NOT NULL,
+                PRIMARY KEY (session_id, event_id),
+                KEY {p}idx_hook_events_session_msg (session_id, message_seq)) {opts}""",
+        ]
+
     def upsert(self, table, key_cols, val_cols, *, add_cols=(), insert_only_cols=()):
         # MySQL: INSERT … AS new_row ON DUPLICATE KEY UPDATE col=new_row.col; accumulate via
         # col=col+new_row.col; insert_only_cols are inserted but omitted from the UPDATE (so

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/runtime/store/schema.py

@@ -55,7 +55,8 @@ def validate_table_prefix(prefix: str) -> str:
 
 #: Bump + append a migration step for ANY schema change.
 #: v2 (2026-06): adds the ``{prefix}project_messages`` table (send-context projection).
-CURRENT_SCHEMA_VERSION = 2
+#: v3 (2026-06): adds the ``{prefix}hook_events`` table (ephemeral hook-augmentation audit log).
+CURRENT_SCHEMA_VERSION = 3
 
 #: The store's data tables (besides ``{prefix}schema_migrations``) — used by VERIFY to
 #: confirm the FULL schema is present, not just the version row. Keep in sync with
@@ -63,7 +64,7 @@ CURRENT_SCHEMA_VERSION = 2
 _STORE_TABLES: tuple[str, ...] = (
     "sessions", "messages", "compactions", "usage_rounds", "session_state",
     "session_runtime_state", "shared_state", "background_tasks", "session_stats",
-    "timers", "notes", "project_messages",
+    "timers", "notes", "project_messages", "hook_events",
 )
 
 
@@ -94,6 +95,11 @@ async def _migration_steps(
                 f"ALTER TABLE {prefix}messages ADD COLUMN send_index "
                 f"{_send_index_column_type(db.dialect.name)}"
             )
+    if from_version < 3:
+        # v2 → v3: add the hook_events (ephemeral hook-augmentation audit) table + index. A new
+        # CREATE TABLE IF NOT EXISTS — no ALTER on the hot messages table, so no _column_exists
+        # probe needed (the CREATE is itself idempotent).
+        steps += db.dialect.hook_events_ddl(prefix)
     return steps
 
 
@@ -109,6 +115,8 @@ def migration_ddl_for_display(db: Database, prefix: str, *, from_version: int) -
             f"ALTER TABLE {prefix}messages ADD COLUMN send_index "
             f"{_send_index_column_type(db.dialect.name)}"
         )
+    if from_version < 3:
+        steps += db.dialect.hook_events_ddl(prefix)
     return steps
 
 

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/runtime/store/store.py

@@ -32,6 +32,7 @@ from power_loop.runtime.store.schema import (
 from power_loop.runtime.store.types import (
     BackgroundTaskRow,
     CompactionRow,
+    HookEventRow,
     MessageRow,
     MessageState,
     NoteRow,
@@ -119,12 +120,16 @@ class _Tables:
         self.timers = f"{prefix}timers"
         self.notes = f"{prefix}notes"
         self.project_messages = f"{prefix}project_messages"
+        self.hook_events = f"{prefix}hook_events"
 
 
 # Logical export schema: (logical_name, physical(t)->table, explicit_columns). Explicit
-# column lists (no SELECT *) keep the export wire format backend-neutral; background_tasks
-# (transient), shared_state (not session-scoped), and project_messages (a DERIVED projection
-# rebuildable from messages) are intentionally excluded.
+# column lists (no SELECT *) keep the export wire format backend-neutral. Intentionally excluded:
+# background_tasks (transient), shared_state (not session-scoped), project_messages (a DERIVED
+# projection rebuildable from messages), and hook_events (an audit-only sidecar — observability,
+# not session state). NOTE: hook_events is NOT rebuildable, so an export-then-prune / cross-store
+# move does NOT carry the hook-injection audit; that is a deliberate scope choice (the audit lives in
+# the live store where it is written), not an oversight.
 _EXPORT_TABLES: tuple[tuple[str, Any, tuple[str, ...]], ...] = (
     ("sessions", lambda t: t.sessions, (
         "session_id", "created_at", "updated_at", "system_prompt", "model", "config_json",
@@ -322,10 +327,17 @@ class SessionStore:
         round_index: int | None = None,
         meta: dict[str, Any] | None = None,
         send_index: int | None = None,
+        hook_injected: dict[str, Any] | None = None,
     ) -> int:
         """Append one message and return its allocated per-session ``seq`` (allocated +
         inserted atomically in one transaction). ``send_index`` is the authoritative per-session
-        send index (a real column, NULL outside a send)."""
+        send index (a real column, NULL outside a send).
+
+        ``hook_injected`` (audit-only) records the EPHEMERAL context an ``LLM_BEFORE`` hook injected
+        into this round's LLM call (e.g. recalled memory) as a child ``hook_events`` row in the SAME
+        transaction — linked to this message's ``seq``. It NEVER touches the ``messages`` row itself,
+        so it can't reach history or the LLM request. Shape:
+        ``{hook_point, hook, position, kind, payload}``."""
         now = _now_ms()
         async with self._db.transaction() as tx:
             st = await self._db.dialect.lock_state(tx, self.t.session_state, session_id)
@@ -348,8 +360,46 @@ class SessionStore:
             await tx.execute(
                 f"UPDATE {self.t.sessions} SET updated_at=? WHERE session_id=?", (now, session_id)
             )
+            if hook_injected:
+                # Per-session monotonic event_id; MAX+1 is race-free here because we hold the
+                # session_state lock for the whole append (serializes same-session writers).
+                ev = await tx.fetchone(
+                    f"SELECT COALESCE(MAX(event_id), 0) + 1 AS nid FROM {self.t.hook_events} "
+                    "WHERE session_id=?",
+                    (session_id,),
+                )
+                await tx.execute(
+                    f"INSERT INTO {self.t.hook_events} ("
+                    "session_id, event_id, message_seq, round_index, send_index, hook_point, hook, "
+                    "position, kind, payload_json, created_at) VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        session_id, int(ev["nid"]), seq, round_index,
+                        (int(send_index) if send_index is not None else None),
+                        str(hook_injected.get("hook_point") or ""), hook_injected.get("hook"),
+                        hook_injected.get("position"), str(hook_injected.get("kind") or ""),
+                        _dumps(hook_injected.get("payload") or {}), now,
+                    ),
+                )
         return seq
 
+    async def list_hook_events(
+        self, session_id: str, *, message_seq: int | None = None
+    ) -> list[HookEventRow]:
+        """Audit rows of hook augmentations for a session (chronological by ``event_id``).
+        ``message_seq`` filters to the augmentations that fed into one specific message."""
+        if message_seq is None:
+            rows = await self._db.fetchall(
+                f"SELECT * FROM {self.t.hook_events} WHERE session_id=? ORDER BY event_id ASC",
+                (session_id,),
+            )
+        else:
+            rows = await self._db.fetchall(
+                f"SELECT * FROM {self.t.hook_events} WHERE session_id=? AND message_seq=? "
+                "ORDER BY event_id ASC",
+                (session_id, int(message_seq)),
+            )
+        return [_row_to_hook_event(r) for r in rows]
+
     async def load_active_messages(
         self, session_id: str, *, after_seq: int | None = None
     ) -> list[MessageRow]:
@@ -793,6 +843,7 @@ class SessionStore:
         await tx.execute(
             f"DELETE FROM {self.t.project_messages} WHERE session_id=?", (session_id,)
         )
+        await tx.execute(f"DELETE FROM {self.t.hook_events} WHERE session_id=?", (session_id,))
         await tx.execute(f"DELETE FROM {self.t.session_state} WHERE session_id=?", (session_id,))
         affected = await tx.execute(
             f"DELETE FROM {self.t.sessions} WHERE session_id=?", (session_id,)
@@ -1553,6 +1604,17 @@ def _row_to_project_message(row: Row) -> ProjectMessageRow:
     )
 
 
+def _row_to_hook_event(row: Row) -> HookEventRow:
+    return HookEventRow(
+        session_id=row["session_id"], event_id=int(row["event_id"]),
+        message_seq=(int(row["message_seq"]) if row["message_seq"] is not None else None),
+        round_index=(int(row["round_index"]) if row["round_index"] is not None else None),
+        send_index=(int(row["send_index"]) if row["send_index"] is not None else None),
+        hook_point=row["hook_point"], hook=row["hook"], position=row["position"],
+        kind=row["kind"], payload=_loads(row["payload_json"]), created_at=row["created_at"],
+    )
+
+
 def _logical_order_key(m: MessageRow) -> tuple[int, int]:
     if m.name == "compact_note":
         ord_val = m.meta.get("ord")

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop/runtime/store/types.py

@@ -30,6 +30,7 @@ __all__ = [
     "BackgroundTaskRow",
     "NoteRow",
     "ProjectMessageRow",
+    "HookEventRow",
 ]
 
 
@@ -205,3 +206,31 @@ class ProjectMessageRow:
     projector_version: int
     token_estimate: int | None
     created_at: int
+
+
+@dataclass
+class HookEventRow:
+    """One audit row of an EPHEMERAL hook augmentation (``{prefix}hook_events``) — e.g. the memory
+    block an ``LLM_BEFORE`` hook injected into a single LLM call's request. It is observability ONLY:
+    written alongside the message it fed into, NEVER read back into history or the LLM request. So
+    the injected context (which today vanishes after the call) is recoverable for audit.
+
+    ``event_id`` is a per-session monotonic id. ``message_seq`` links to the ``messages`` row this
+    augmentation fed into (the assistant response of that round); ``round_index``/``send_index``
+    locate the round/send. ``hook_point`` is the hook phase (``LLM_BEFORE``); ``hook`` a coarse
+    source label (``builtin.memory_recall`` / ``llm_before``); ``position`` is where the items landed
+    in the request (``tail``/``front``); ``kind`` the effect (``inject``). ``payload`` is the parsed
+    ``payload_json`` — ``{v, items:[{role,name,source,chars,content?}], item_count, total_chars}``
+    (``content`` present only when captured in ``full`` mode)."""
+
+    session_id: str
+    event_id: int
+    message_seq: int | None
+    round_index: int | None
+    send_index: int | None
+    hook_point: str
+    hook: str | None
+    position: str | None
+    kind: str
+    payload: Any
+    created_at: int

{power_loop-3.1.0 → power_loop-3.3.0}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 3.1.0
+Version: 3.3.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -162,6 +162,7 @@ Most "agent frameworks" ask you to build your app *inside* them. power-loop is t
 | **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; 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) |