postgres-aiops 0.11.0__tar.gz → 0.13.0__tar.gz

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "postgres-aiops",
   "displayName": "Postgres AIops",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Governed PostgreSQL DBA ops: slow-query RCA, bloat/vacuum & blocking-lock analysis; 35 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "postgres-aiops==0.11.0",
+        "postgres-aiops==0.13.0",
         "postgres-aiops-mcp"
       ]
     }

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.13.0 — 2026-10-30
+
+### Security and observability (BREAKING)
+- **BREAKING:** Writes now require a durable audit intent before contacting the upstream platform. If the audit database cannot accept the intent, the write fails closed; a failed final audit update leaves an unresolved `pending` intent.
+- Real writes now commit a durable `pending` audit intent before the upstream call. If audit storage is unavailable, the write does not start; a failed final update leaves a visible pending intent and blocks further writes in that process.
+- Audit rows retain outcome metadata instead of full business responses. `AIOPS_WORKFLOW_ID` links calls across a workflow; optional `AIOPS_TELEMETRY=1` emits metadata-only JSON events and `AuditEngine.health()` reports audit failures and pending intents.
+
+
+## v0.12.0 — 2026-10-15
+
+### Fixed
+- The MCP server moved from a top-level `mcp_server` package to
+  `postgres_aiops.mcp_server`. Every AIops tool used to ship its own top-level
+  `mcp_server`, so installing two of them into one environment merged the two
+  into one package: `postgres-aiops-mcp` could start another tool's server, and
+  `postgres-aiops undo` wrote audit and undo rows into the other tool's home
+  directory. Installs through `uvx`, the Claude Code plugin or the OpenClaw
+  bundle were isolated and unaffected. The `postgres-aiops-mcp` command is
+  unchanged; only code that imported `mcp_server` directly must now import
+  `postgres_aiops.mcp_server`.
+
 ## v0.11.0 — 2026-10-15
 
 ### Added

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: postgres-aiops
-Version: 0.11.0
+Version: 0.13.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
@@ -18,6 +18,8 @@ Description-Content-Type: text/markdown
 
 # Postgres AIops
 
+> **Audit availability:** Real writes require a committed `pending` audit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
+
 > **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
 
 Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
@@ -152,7 +154,7 @@ postgres-aiops-mcp
 
 Every MCP tool passes through the bundled `@governed_tool` harness:
 
-- **Audit** — every call (params, result, status, duration, risk tier, and any
+- **Audit** — every call (params, outcome summary, status, duration, risk tier, and any
   operator-supplied approver/rationale) is logged to `~/.postgres-aiops/audit.db`
   (relocatable via `POSTGRES_AIOPS_HOME`). The CLI writes the same row the MCP
   path does — there is no unaudited entry point.

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/README.md

@@ -2,6 +2,8 @@
 
 # Postgres AIops
 
+> **Audit availability:** Real writes require a committed `pending` audit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
+
 > **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
 
 Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server with
@@ -136,7 +138,7 @@ postgres-aiops-mcp
 
 Every MCP tool passes through the bundled `@governed_tool` harness:
 
-- **Audit** — every call (params, result, status, duration, risk tier, and any
+- **Audit** — every call (params, outcome summary, status, duration, risk tier, and any
   operator-supplied approver/rationale) is logged to `~/.postgres-aiops/audit.db`
   (relocatable via `POSTGRES_AIOPS_HOME`). The CLI writes the same row the MCP
   path does — there is no unaudited entry point.

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/SECURITY.md

@@ -41,7 +41,7 @@ reports.
 ### Governed Operations
 Every MCP tool runs through the bundled `@governed_tool` harness
 (`postgres_aiops.governance`):
-- **Audit** — every call logged to a local SQLite DB under `~/.postgres-aiops/`
+- **Audit** — calls logged to a local SQLite DB when storage is available under `~/.postgres-aiops/`
   (relocatable via `POSTGRES_AIOPS_HOME`), agent-attributed, secret-redacted.
 - **Token/runaway budget** — hard ceilings (`POSTGRES_MAX_TOOL_CALLS` /
   `POSTGRES_MAX_TOOL_SECONDS` — the env-var names the bundled harness reads) plus
@@ -82,7 +82,7 @@ connection. No post-install scripts or background services.
 ## Static Analysis
 
 ```bash
-uvx bandit -r postgres_aiops/ mcp_server/
+uvx bandit -r postgres_aiops/
 uv run ruff check .
 ```
 
@@ -90,3 +90,20 @@ uv run ruff check .
 
 The latest released version receives security fixes. This is a preview (0.x);
 pin a version in production.
+
+## Audit availability and telemetry
+
+Real writes first commit a `pending` audit intent. If audit storage is unavailable,
+the upstream write does not start. If finalization fails after an upstream call,
+the intent stays visible and further writes in that process are blocked. Check
+that the process is no longer executing and verify server state before calling
+`AuditEngine.reconcile_pending(audit_id)` to mark the intent `unknown`.
+
+Reads and dry-run previews continue when audit storage fails, with a warning
+rather than a durable row. New audit rows store outcome summaries instead of
+full business responses; older rows and rotated archives are not rewritten
+automatically. Parameter redaction still follows each tool's
+`sensitive_params`. `AIOPS_WORKFLOW_ID` supplies a correlation ID, and optional
+`AIOPS_TELEMETRY=1` emits metadata-only JSON logs. `AuditEngine.health()`
+reports availability, write blocking, failure count, and pending intent count.
+On POSIX the rotation lock spans processes; on Windows it is process-local.

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/docs/VERIFICATION.md

@@ -174,3 +174,7 @@ based analysis, replication reads, session termination, `REINDEX`, and
   `pg_basebackup`) and re-run `repl status` / `repl slots` / `repl wal`.
 - The analyses also accept **injected records**, so exported rows from a cluster
   you cannot write to still exercise section 3 without any write access.
+
+## Governance hardening — local synthetic verification (2026-10-30)
+
+The shared governance tests exercise a durable `pending` row before a write, refusal when the audit DB cannot persist that row, a visible pending row after finalization failure, explicit reconciliation to `unknown`, async/preview parity, result minimization, and metadata-only telemetry with `AIOPS_WORKFLOW_ID`. The tests use a temporary SQLite DB and synthetic tools; they do not claim a new live upstream write was performed. Existing audit rows and rotated archives from earlier releases are not automatically scrubbed. A pending intent from another process is never auto-reconciled. On POSIX the rotation/intent lock spans processes; on Windows it currently protects only threads in this process.

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "postgres-aiops==0.11.0",
+        "postgres-aiops==0.13.0",
         "postgres-aiops-mcp"
       ]
     }

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/postgres-aiops",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Governed PostgreSQL DBA ops: slow-query RCA, bloat/vacuum & blocking-lock analysis; 35 MCP tools.",
   "private": true,
   "license": "MIT",

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/postgres_aiops/cli/_root.py

@@ -61,7 +61,7 @@ def mcp_cmd() -> None:
         )
         raise typer.Exit(2)
 
-    from mcp_server.server import main as _mcp_main
+    from postgres_aiops.mcp_server.server import main as _mcp_main
 
     _mcp_main()
 

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/postgres_aiops/cli/query.py

@@ -70,7 +70,7 @@ def query_reset(target: TargetOption = None, dry_run: DryRunOption = False) -> N
     ``@governed_tool``-wrapped MCP function, so each is audited on the same
     governance path as MCP calls.
     """
-    from mcp_server.tools import queries as gov
+    from postgres_aiops.mcp_server.tools import queries as gov
 
     if dry_run:
         dry_run_preview(

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/postgres_aiops/cli/remediate.py

@@ -32,7 +32,7 @@ def remediate_terminate(
     dry_run: DryRunOption = False,
 ) -> None:
     """Terminate a backend (no undo; dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         # Through the governed call: terminate_backend refuses this tool's own
@@ -54,7 +54,7 @@ def remediate_cancel(
     dry_run: DryRunOption = False,
 ) -> None:
     """Cancel a backend's running query (no undo; dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         dry_run_preview(
@@ -76,7 +76,7 @@ def remediate_vacuum(
     dry_run: DryRunOption = False,
 ) -> None:
     """VACUUM a table (dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         dry_run_preview(
@@ -97,7 +97,7 @@ def remediate_analyze(
     dry_run: DryRunOption = False,
 ) -> None:
     """ANALYZE a table (dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         dry_run_preview(
@@ -120,7 +120,7 @@ def remediate_create_index(
     dry_run: DryRunOption = False,
 ) -> None:
     """Create an index (reversible; dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         # Through the governed call: create_index validates the table/columns vs
@@ -146,7 +146,7 @@ def remediate_drop_index(
     dry_run: DryRunOption = False,
 ) -> None:
     """Drop an index (reversible; captures the definition first; dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         dry_run_preview(
@@ -168,7 +168,7 @@ def remediate_reindex(
     dry_run: DryRunOption = False,
 ) -> None:
     """REINDEX an index/table/schema (dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     if dry_run:
         dry_run_preview(
@@ -195,7 +195,7 @@ def remediate_set(
     dry_run: DryRunOption = False,
 ) -> None:
     """ALTER SYSTEM SET a parameter, or --reset it (reversible; dry-run + confirm)."""
-    from mcp_server.tools import remediation as gov
+    from postgres_aiops.mcp_server.tools import remediation as gov
 
     action = f"ALTER SYSTEM RESET {name}" if reset else f"ALTER SYSTEM SET {name} ="
     if dry_run:

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/postgres_aiops/cli/undo.py

@@ -1,7 +1,7 @@
 """``postgres-aiops undo`` — list recorded undo tokens and apply them.
 
 Real execution is delegated to the ``@governed_tool``-wrapped functions in
-``mcp_server.tools.undo`` so an applied undo is audited on the SAME governance
+``postgres_aiops.mcp_server.tools.undo`` so an applied undo is audited on the SAME governance
 path as any other write (the inverse tool it dispatches is itself re-gated).
 """
 
@@ -38,7 +38,7 @@ def undo_list_cmd(
     target: TargetOption = None,
 ) -> None:
     """List recorded, not-yet-applied undo tokens."""
-    from mcp_server.tools import undo as gov
+    from postgres_aiops.mcp_server.tools import undo as gov
 
     console.print_json(json.dumps(gov.undo_list(limit=limit, target=target)))
 
@@ -49,7 +49,7 @@ def undo_apply_cmd(
     undo_id: UndoIdArg, target: TargetOption = None, dry_run: DryRunOption = False
 ) -> None:
     """Apply a recorded undo (dispatches its inverse tool; dry-run + confirm)."""
-    from mcp_server.tools import undo as gov
+    from postgres_aiops.mcp_server.tools import undo as gov
 
     if dry_run:
         # undo_apply refuses an unknown or already-applied token, and refuses one

{postgres_aiops-0.11.0 → postgres_aiops-0.13.0}/postgres_aiops/governance/audit.py

@@ -1,4 +1,4 @@
-"""Unified audit logging engine — all PostgreSQL skills write to a single SQLite database.
+"""Unified audit logging engine — all Monitoring skills write to a single SQLite database.
 
 Replaces 7 per-skill JSON Lines audit loggers with one shared ``~/.postgres-aiops/audit.db``.
 Framework-agnostic: works with Claude, Codex, local agents, or any MCP client.
@@ -12,12 +12,18 @@ import logging
 import os
 import sqlite3
 import threading
+from contextlib import contextmanager
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
 from postgres_aiops.governance.paths import ops_path
 
+try:
+    import fcntl
+except ImportError:  # Windows has no fcntl; the in-process lock still applies.
+    fcntl = None
+
 _log = logging.getLogger("postgres-aiops.audit")
 
 # Back-compat override hook. When None (default) the path resolves via
@@ -29,6 +35,26 @@ _DEFAULT_DB: Path | None = None
 _MAX_DB_SIZE_BYTES = 100 * 1024 * 1024  # 100 MB
 _MAX_ARCHIVES = 5
 _BUSY_TIMEOUT_MS = 5000
+_rotation_thread_lock = threading.RLock()
+
+
+@contextmanager
+def _rotation_guard(path: Path):
+    """Serialize rotation and intent insertion across local processes."""
+    with _rotation_thread_lock:
+        fd = os.open(path.with_name("audit.lock"), os.O_CREAT | os.O_RDWR, 0o600)
+        try:
+            if fcntl is not None:
+                fcntl.flock(fd, fcntl.LOCK_EX)
+            yield
+        finally:
+            if fcntl is not None:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            os.close(fd)
+
+
+class AuditUnavailable(RuntimeError):
+    """A write was stopped because its durable audit intent could not be recorded."""
 
 _CREATE_TABLE = """\
 CREATE TABLE IF NOT EXISTS audit_log (
@@ -78,6 +104,8 @@ class AuditEngine:
         else:
             self._path = _DEFAULT_DB or ops_path("audit.db")
         self._ok = False
+        self._write_blocked = False
+        self._write_failures = 0
         try:
             self._path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
             self._init_db()
@@ -90,6 +118,7 @@ class AuditEngine:
         conn = self._connect()
         conn.execute(_CREATE_TABLE)
         conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=FULL")
         self._migrate(conn)
         conn.commit()
         conn.close()
@@ -126,6 +155,7 @@ class AuditEngine:
     def _connect(self) -> sqlite3.Connection:
         conn = sqlite3.connect(str(self._path), timeout=_BUSY_TIMEOUT_MS / 1000)
         conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
+        conn.execute("PRAGMA synchronous=FULL")
         return conn
 
     def log(
@@ -144,43 +174,128 @@ class AuditEngine:
         rationale: str = "",
         approved_by: str = "",
         risk_tier: str = "",
-    ) -> None:
-        """Write one audit record.  Never raises — swallows errors to avoid
-        disrupting the actual tool execution.
+        strict: bool = False,
+    ) -> int | None:
+        """Append a row. Strict mode refuses writes if the intent cannot persist.
 
         rationale / approved_by / risk_tier carry the accountability trail:
         *why* a change was made, *who* signed off, and the *approval tier* the
         policy engine assigned (none/confirm/dual/review).
         """
         if not self._ok:
-            return
+            if strict:
+                self._write_blocked = True
+                self._write_failures += 1
+                raise AuditUnavailable("Audit storage is unavailable; write was not started")
+            self._write_failures += 1
+            return None
+        try:
+            with _rotation_guard(self._path):
+                self._maybe_rotate()
+                conn = self._connect()
+                try:
+                    cursor = conn.execute(
+                        _INSERT,
+                        (
+                            datetime.now(tz=UTC).isoformat(),
+                            skill,
+                            tool,
+                            _safe_json(params),
+                            _safe_json(_summarize_result(result)),
+                            status,
+                            duration_ms,
+                            agent,
+                            workflow_id,
+                            user or _current_user(),
+                            risk_level,
+                            rationale,
+                            approved_by,
+                            risk_tier,
+                        ),
+                    )
+                    conn.commit()
+                    audit_id = cursor.lastrowid
+                finally:
+                    conn.close()
+            _log.debug("[AUDIT] %s.%s -> %s (%dms)", skill, tool, status, duration_ms)
+            return audit_id
+        except Exception:
+            self._write_failures += 1
+            _log.warning("Failed to write audit log", exc_info=True)
+            if strict:
+                self._write_blocked = True
+                raise AuditUnavailable("Audit storage is unavailable; write was not started") from None
+            return None
+
+    def begin_write(self, **metadata: Any) -> int:
+        """Commit a durable intent before the caller sends an upstream write."""
+        if self._write_blocked:
+            raise AuditUnavailable("Audit storage failed; further writes are blocked")
+        audit_id = self.log(status="pending", strict=True, **metadata)
+        assert audit_id is not None
+        return audit_id
+
+    def finish_write(self, audit_id: int, *, result: Any, status: str, duration_ms: int) -> None:
+        """Resolve a write intent; on failure leave a recoverable pending row."""
         try:
-            self._maybe_rotate()
             conn = self._connect()
-            conn.execute(
-                _INSERT,
-                (
-                    datetime.now(tz=UTC).isoformat(),
-                    skill,
-                    tool,
-                    _safe_json(params),
-                    _safe_json(result),
-                    status,
-                    duration_ms,
-                    agent,
-                    workflow_id,
-                    user or _current_user(),
-                    risk_level,
-                    rationale,
-                    approved_by,
-                    risk_tier,
-                ),
+            try:
+                cursor = conn.execute(
+                    "UPDATE audit_log SET result = ?, status = ?, duration_ms = ? "
+                    "WHERE id = ? AND status = 'pending'",
+                    (_safe_json(_summarize_result(result)), status, duration_ms, audit_id),
+                )
+                if cursor.rowcount != 1:
+                    raise RuntimeError(f"audit intent {audit_id} is missing")
+                conn.commit()
+            finally:
+                conn.close()
+        except Exception:
+            self._write_blocked = True
+            self._write_failures += 1
+            _log.warning("Failed to finalize audit intent %s", audit_id, exc_info=True)
+            raise AuditUnavailable(
+                f"Audit intent {audit_id} remains pending; operation may have completed"
+            ) from None
+
+    def reconcile_pending(self, audit_id: int) -> bool:
+        """Mark an orphaned intent unknown after an operator checks the process.
+
+        Never run this automatically: another process may still be executing
+        the write. The row remains visible until explicitly reconciled.
+        """
+        conn = self._connect()
+        try:
+            cursor = conn.execute(
+                "UPDATE audit_log SET status = 'unknown', result = ? "
+                "WHERE id = ? AND status = 'pending'",
+                (_safe_json({"auditInterrupted": True}), audit_id),
             )
             conn.commit()
+            return cursor.rowcount == 1
+        finally:
             conn.close()
-            _log.debug("[AUDIT] %s.%s -> %s (%dms)", skill, tool, status, duration_ms)
-        except Exception:
-            _log.warning("Failed to write audit log", exc_info=True)
+
+    def health(self) -> dict[str, Any]:
+        """Safe local health counters for operators and telemetry exporters."""
+        pending: int | None = None
+        if self._ok:
+            try:
+                conn = self._connect()
+                try:
+                    pending = conn.execute(
+                        "SELECT COUNT(*) FROM audit_log WHERE status = 'pending'"
+                    ).fetchone()[0]
+                finally:
+                    conn.close()
+            except Exception:
+                pass
+        return {
+            "available": self._ok and pending is not None and not self._write_blocked,
+            "writeBlocked": self._write_blocked,
+            "auditWriteFailures": self._write_failures,
+            "pendingWrites": pending,
+        }
 
     # ── Rotation ──────────────────────────────────────────────────────
 
@@ -191,20 +306,27 @@ class AuditEngine:
                 return
             if self._path.stat().st_size < _MAX_DB_SIZE_BYTES:
                 return
+            pending_conn = self._connect()
+            try:
+                if pending_conn.execute(
+                    "SELECT 1 FROM audit_log WHERE status = 'pending' LIMIT 1"
+                ).fetchone():
+                    return
+            finally:
+                pending_conn.close()
             archive_name = self._path.with_suffix(
                 f".{datetime.now(tz=UTC).strftime('%Y%m%d-%H%M%S')}.db"
             )
             # Checkpoint the WAL into the main file before renaming, otherwise
             # un-checkpointed rows in audit.db-wal are silently lost (the
             # sidecars belong to the OLD path and never follow the archive).
+            conn = self._connect()
             try:
-                conn = self._connect()
-                try:
-                    conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
-                finally:
-                    conn.close()
-            except Exception:
-                _log.warning("WAL checkpoint before rotation failed", exc_info=True)
+                checkpoint = conn.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
+                if checkpoint is None or checkpoint[0]:
+                    raise RuntimeError(f"WAL checkpoint incomplete: {checkpoint}")
+            finally:
+                conn.close()
             self._path.rename(archive_name)
             # Drop now-stale sidecars (empty after a successful checkpoint).
             for suffix in ("-wal", "-shm"):
@@ -327,6 +449,28 @@ def _safe_json(obj: Any) -> str:
         return json.dumps({"_raw": str(obj)})
 
 
+def _summarize_result(result: Any) -> dict[str, Any]:
+    """Persist only outcome metadata; never copy a tool's business payload."""
+    if isinstance(result, dict):
+        summary: dict[str, Any] = {"kind": "object"}
+        if result.get("error"):
+            summary["error"] = True
+        if result.get("outcomeUnknown") is True:
+            summary["outcomeUnknown"] = True
+        if result.get("_undo_id"):
+            summary["undoRecorded"] = True
+        if result.get("_pattern_id"):
+            summary["patternMatched"] = True
+        for key in ("truncated", "returned", "limit"):
+            value = result.get(key)
+            if type(value) in (bool, int):
+                summary[key] = value
+        return summary
+    if isinstance(result, (list, tuple)):
+        return {"kind": "list", "count": len(result)}
+    return {"kind": type(result).__name__}
+
+
 def detect_agent() -> str:
     """Infer the calling AI agent from environment variables."""
     if os.environ.get("CLAUDE_SESSION_ID") or os.environ.get("CLAUDE_CODE"):