davinci-resolve-mcp 2.206.0 → 2.208.0

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.208.0 — agent execution lifecycle & pre-flight risk inspection
+
+Adapted from the design contributed in PR #187.
+
+### Added
+
+- **Agent execution lifecycle pipeline & hooks:**
+  Tools passing through `_guard_missing_params` now execute within a structured
+  lifecycle pipeline, supporting pre-flight inspection (`before_tool_call`),
+  post-execution enrichment (`after_tool_call`), and failure handling (`on_error`).
+- **Pre-flight operation risk & blast radius assessment:**
+  `resolve_control(action="inspect_operation")` evaluates any tool and action
+  prior to execution, returning risk levels (`low`, `medium`, `high`, `critical`),
+  destructive flags, confirmation requirements, and blast radius scopes (`item`,
+  `track`, `timeline`, `project`, `system`).
+- **Lifecycle hooks introspection:**
+  `resolve_control(action="list_lifecycle_hooks")` exposes registered pipeline
+  hooks and their active states.
+
+### Notes on the adaptation
+
+- **The dry-run simulation interceptor is not included.** As contributed, any
+  call carrying `dry_run: true` outside a hardcoded four-entry allowlist was
+  short-circuited and answered with a synthesised `{"success": true,
+  "simulated": true}`. `src/server.py` has 273 `dry_run` references, so the
+  allowlist was not close: `setup.set_defaults` and
+  `resolve_control.clear_executions` both have real, tested dry-run paths and
+  were hijacked. It also answered `success: true` to
+  `set_defaults(result_envelope="banana")` — a dry run of an operation that
+  cannot succeed — and to adding a marker with no timeline in existence.
+  `dry_run` is the call an editor makes *because* they do not trust the next
+  one; a version of it that always succeeds is worse than none, because it is
+  believed. Nothing about dry-run behaviour changes in this release: every
+  `dry_run` reaches the handler that owns it.
+- **The pipeline can gate a call, but nothing shipped does.**
+  `HookDecision(proceed=False)` and the public `register_hook` remain, so a
+  deliberately registered hook can intercept. Every default hook only observes,
+  and `test_no_default_hook_short_circuits` keeps it that way.
+- **`inspect_operation` no longer contradicts itself about rollback.** It
+  reported `snapshot_available` two ways in one response — `false` inside
+  `risk`, and `true` at the top level whenever any pre-state could be read.
+  Reading a project name is not a restorable snapshot. It is now a single
+  `null`, meaning "not determined", with `pre_state_available` reporting
+  separately whether live state was read at all.
+- **An unrecognised operation is no longer assessed as safe.** Any action
+  matching no rule fell into a general-mutation bucket and returned `medium` /
+  `destructive: false` / `confirmation_required: false` — a confident answer
+  about an operation the classifier had never heard of, including ones that do
+  not exist. Responses now carry `recognised: false` and say in `reasons` that
+  the levels are name-based defaults rather than a finding. The guard exists
+  for hallucinated calls; answering one with reassurance was the failure it was
+  built to prevent.
+- The docs now state plainly that `inspect_operation` is a heuristic over
+  action names, not a simulation: it never touches the project and does not
+  validate parameters.
+
+## What's New in v2.207.0 — execution audit report exports
+
+Contributed in PR #185.
+
+### Added
+
+- **Execution traces can now be exported as reviewable audit reports.**
+  `resolve_control(action="export_execution_report")` writes the latest trace,
+  or a named `execution_id`, as Markdown or JSON. The report carries the
+  request, status, start/end timestamps, duration, tool summary, semantic
+  deltas, verification rollup, warnings, notes, and optional per-step table.
+- **Reports default beside the trace log.** When no path is passed, reports are
+  written under `logs/execution-reports/<execution_id>.md` or `.json`.
+  `RESOLVE_MCP_TRACE_REPORT_DIR` can move that default destination without
+  changing where append-only trace events are logged.
+- **Exports are observer-safe.** Creating a report is exempt from execution-step
+  recording, just like querying traces, so inspecting or exporting a trace
+  cannot mutate the trace being reviewed.
+- **Existing files are protected by default.** A caller must pass
+  `overwrite=true` to replace a report at the chosen path.
+
+### Notes
+
+- The export is built from the existing trace summary fields, not raw tool
+  arguments or raw tool results. It is meant for review and audit, not a replay
+  script.
+- Added focused unit and server integration coverage for Markdown export, JSON
+  export, step omission, invalid formats, overwrite protection, observer
+  isolation, and `resolve_control` dispatch.
+
+### Fixed on the way in
+
+- **An unverified run no longer reports itself as passed.** The verification
+  rollup collapsed "nothing reported any evidence" into `passed: True`, and the
+  report printed it verbatim — so a workflow where nothing was checked produced
+  an audit document reading `Status: unverified` on one line and `Passed: yes`
+  on the next. Those sit inches apart and only one of them gets scanned. The
+  rollup now carries `None` for the unknown case and the Passed row renders
+  "not established — no checks recorded"; a real pass still says yes and a real
+  failure still says no. This is the same distinction v2.206.0 documented for
+  `verification.status`, and the export is exactly where it stops being a
+  nuance and starts being a claim on paper.
+- **The Simplified Chinese README was carrying a false version line.** Its
+  badge and "本翻译对应 vX.Y.Z 版 README" line were bumped to 2.207.0 without the
+  section itself, which is the specific failure the release process calls out —
+  a lagging translation whose version line asserts otherwise. Translated.
+- `path` is documented as honoured-as-given, creating directories to reach the
+  destination: deliberate, since a conform's paperwork belongs beside the
+  conform rather than in `logs/`, but worth stating next to a source-media
+  safety policy. The `execution_id` route is sanitised to a bare filename and
+  cannot escape the report directory — verified.
+
 ## What's New in v2.206.0 — agent execution traces
 
 Adapted from the design contributed in PR #183.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#server-modes)
@@ -274,6 +274,27 @@ semantic deltas (`items_deleted`, `items_added`), and readback verifications.
 Agents and editors can inspect workflows via `resolve_control`:
 `get_execution_trace(execution_id?)`, `list_recent_executions()`, or open a
 scoped execution with `begin_execution(request="...")` / `end_execution()`.
+`export_execution_report(execution_id?, format="markdown"|"json")` writes a
+reviewable audit artifact with the same summary, defaulting to
+`logs/execution-reports/<execution_id>.md`. `path` writes it anywhere you want
+it instead — alongside a conform in a dated TransferFiles folder, say — and
+creates the directories to get there, so check the path before you send it.
+An existing file is never replaced without `overwrite: true`.
+`inspect_operation(tool?, target_action?, target_params?)` evaluates pre-flight
+risk level (`low`, `medium`, `high`, `critical`), destructive potential, and blast
+radius (`item`, `track`, `timeline`, `project`, `system`) before taking action, while
+`list_lifecycle_hooks()` inspects active execution interceptors.
+
+It is a heuristic over action names, not a simulation — it never touches the
+project and does not validate your parameters, so `recognised: false` means the
+levels are defaults rather than a finding, and `snapshot_available: null` means
+rollback availability was not determined rather than absent. Every shipped hook
+observes; none replaces a tool's result, so `dry_run` always reaches the real
+handler and nothing synthesises a preview for an action that has none.
+
+A report for a run where nothing was verified says **"not established — no
+checks recorded"**, not "passed". Absence of evidence is a question still open,
+and an audit document is the last place to let a reader read it as an all-clear.
 
 Traces live in a 100-entry in-memory ring and are appended to
 `logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.208.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.206.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.208.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -172,6 +172,14 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 轨迹保存在一个容量 100 条的内存环形缓冲里，并追加写入 `logs/execution-traces.jsonl`（就在 `server.log` 旁边，可用 `RESOLVE_MCP_TRACE_FILE` 改位置），文件到 8 MB 会轮转并保留一份上一代。`list_recent_executions` 会返回该路径以及是否可写，这样"日志是空的"和"根本没在写"就能区分开。记录的内容是工具名、动作、耗时、状态、语义增量和校验结果——不记录参数，也不记录文件路径。唯一的自由文本是你传给 `begin_execution` 的 `request`，在客户项目上请把它当成提交信息来写。
 
+### 导出执行审计报告
+
+`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。`inspect_operation(tool?, target_action?, target_params?)` 会在执行前评估操作的风险等级（`low`、`medium`、`high`、`critical`）、破坏性以及影响范围（`item`、`track`、`timeline`、`project`、`system`），而 `list_lifecycle_hooks()` 则可以查看当前生效的生命周期钩子。
+
+需要强调的是：这是一套基于动作名称的启发式判断，**不是模拟执行**——它完全不碰项目，也不会校验你传的参数。`recognised: false` 表示没有任何规则命中，那些等级只是按名字给出的默认值，而不是对这次操作的结论；`snapshot_available: null` 表示"是否能回滚未确定"，而不是"不能回滚"。所有随包启用的钩子都只做观察，没有任何一个会替换工具的返回值——因此 `dry_run` 永远会走到真正的处理函数，不会有人替一个本身不支持 dry-run 的动作凭空编一份预览出来。
+
+如果这次运行根本没有做过校验，报告里写的是**"not established — no checks recorded"（未确立——没有记录任何检查）**，而不是"通过"。没有证据是一个仍然悬而未决的问题；审计文件恰恰是最不该让读者把它读成"一切正常"的地方。
+
 ## 可选增强
 
 核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，且**每一项都会诚实拒绝并给出自己的安装命令，而不是退化成瞎猜**——编造的节拍或虚构的电平会产出自信但错误的结果，比没有这个功能更糟。

package/docs/SKILL.md

@@ -271,7 +271,30 @@ Example trace shape returned by `resolve_control(action="get_execution_trace")`:
   Fetches the trace for a specific ID, or the most recent execution if omitted.
 - **`list_recent_executions(limit?)`**: Returns the recent execution traces
   (newest first, default limit 20).
+- **`export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?)`**:
+  Writes a Markdown or JSON audit report for a trace. The default destination is
+  `logs/execution-reports/<execution_id>.md`; pass `format: "json"` for
+  structured output, `include_steps: false` for a shorter summary, or
+  `overwrite: true` to replace an existing report.
 - **`clear_executions(dry_run?)`**: Clears the in-memory execution trace buffer.
+- **`inspect_operation(tool?, target_action?, target_params?)`**: Evaluates operation risk
+  level (`low`, `medium`, `high`, `critical`), destructive potential, confirmation
+  requirements, and blast radius scope before executing an action.
+
+  **It is a heuristic over action names, not a simulation.** It does not touch
+  the project, does not validate your parameters, and cannot tell you whether
+  the clip ids you are holding exist. Read three fields before trusting it:
+  `recognised: false` means no rule matched and the levels are name-based
+  defaults rather than a finding; `snapshot_available: null` means rollback
+  availability was not determined, never that there is none; and
+  `pre_state_available` separates "no project open" from "state never read".
+  For an actual preview, use the action's own `dry_run` where it has one.
+- **`list_lifecycle_hooks()`**: Returns active execution lifecycle pipeline hooks
+  (`risk_classification`, `resolve_state_inspection`, `readback_verification`,
+  `drift_detection`, `provenance_trace`). All of them observe; none replaces a
+  tool result. `dry_run` therefore always reaches the real handler — a tool
+  either implements it or does not, and nothing synthesises a preview on its
+  behalf.
 
 Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
 or `params={"trace_id": ...}` in any tool call to associate it with a specific trace.
@@ -290,6 +313,20 @@ The only free text is the `request` string passed to `begin_execution`.
 
 The file rotates at 8 MB, keeping one previous generation as
 `execution-traces.jsonl.1`. Both are gitignored along with the rest of `logs/`.
+Audit reports are separate point-in-time exports; `RESOLVE_MCP_TRACE_REPORT_DIR`
+moves their default directory without moving the append-only trace log.
+
+`path` is honoured as given — the report can be written anywhere, and the
+directories are created to reach it. That is deliberate (a conform's paperwork
+belongs beside the conform, not in `logs/`), so treat it the way you would any
+other export destination and do not invent a path near source media. The
+`execution_id` route cannot escape the report directory: it is sanitised to a
+filename.
+
+A report whose run recorded no verification checks renders **"not established
+— no checks recorded"** in the Passed row, never "yes" — the same rule as
+`verification.status: "unverified"` in the envelope. Do not report such a run
+to the user as verified.
 
 ---
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.206.0"
+VERSION = "2.208.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.206.0",
+  "version": "2.208.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.206.0"
+VERSION = "2.208.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.206.0"
+VERSION = "2.208.0"
 
 import base64
 import os
@@ -74,6 +74,12 @@ from src.utils.execution_trace import (
     begin_execution,
     end_execution,
     clear_executions,
+    export_execution_report,
+)
+from src.utils import execution_lifecycle as _execution_lifecycle
+from src.utils.execution_lifecycle import (
+    inspect_operation,
+    list_lifecycle_hooks,
 )
 from src.utils.render_ids import (
     render_codec_id_from_codecs as _render_codec_id_from_codecs,
@@ -886,6 +892,37 @@ def _try_connect():
             resolve = None
             return None
 
+def _get_resolve_lifecycle_state() -> Optional[Dict[str, Any]]:
+    """Capture non-blocking pre-flight Resolve project and timeline metadata."""
+    global resolve
+    r = resolve
+    if r is None:
+        try:
+            r = _try_connect()
+        except Exception:
+            r = None
+    if r is None:
+        return None
+    try:
+        pm = r.GetProjectManager()
+        if not pm:
+            return None
+        proj = pm.GetCurrentProject()
+        if not proj:
+            return None
+        state: Dict[str, Any] = {"project_name": proj.GetName()}
+        tl = proj.GetCurrentTimeline()
+        if tl:
+            state["timeline_name"] = tl.GetName()
+            state["duration_frames"] = tl.GetEndFrame() - tl.GetStartFrame()
+            state["track_count_video"] = tl.GetTrackCount("video")
+            state["track_count_audio"] = tl.GetTrackCount("audio")
+        return state
+    except Exception:
+        return None
+
+_execution_lifecycle.get_lifecycle_pipeline().set_state_provider(_get_resolve_lifecycle_state)
+
 def _launch_resolve(headless: Optional[bool] = None):
     """Launch DaVinci Resolve and wait for it to become available.
 
@@ -1499,6 +1536,8 @@ def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
 _TRACE_OBSERVER_ACTIONS = {
     "get_execution_trace", "get_execution", "list_recent_executions",
     "clear_executions", "begin_execution", "end_execution",
+    "export_execution_report",
+    "inspect_operation", "list_lifecycle_hooks",
 }
 
 
@@ -1571,14 +1610,29 @@ def _guard_missing_params(fn):
         async def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
             params = _guarded_params(args, kwargs)
+            lifecycle = _execution_lifecycle.get_lifecycle_pipeline()
+            ctx = _execution_lifecycle.ToolCallContext(
+                tool_name=tool_name,
+                action=action,
+                params=params or {},
+            )
+            decision = lifecycle.run_before(ctx)
+            if decision and not decision.proceed and decision.short_circuit_result is not None:
+                return _build_operation_envelope(tool_name, action, params, decision.short_circuit_result, duration_ms=0)
+
             t0 = time.perf_counter()
             try:
                 result = await fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
+            except Exception as exc:
+                duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+                lifecycle.run_on_error(ctx, exc, duration_ms)
+                raise
             duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
             enveloped = _build_operation_envelope(
                 tool_name, action, params, result, duration_ms=duration_ms)
+            enveloped = lifecycle.run_after(ctx, enveloped, duration_ms)
             _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
             return enveloped
     else:
@@ -1586,14 +1640,29 @@ def _guard_missing_params(fn):
         def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
             params = _guarded_params(args, kwargs)
+            lifecycle = _execution_lifecycle.get_lifecycle_pipeline()
+            ctx = _execution_lifecycle.ToolCallContext(
+                tool_name=tool_name,
+                action=action,
+                params=params or {},
+            )
+            decision = lifecycle.run_before(ctx)
+            if decision and not decision.proceed and decision.short_circuit_result is not None:
+                return _build_operation_envelope(tool_name, action, params, decision.short_circuit_result, duration_ms=0)
+
             t0 = time.perf_counter()
             try:
                 result = fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
+            except Exception as exc:
+                duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+                lifecycle.run_on_error(ctx, exc, duration_ms)
+                raise
             duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
             enveloped = _build_operation_envelope(
                 tool_name, action, params, result, duration_ms=duration_ms)
+            enveloped = lifecycle.run_after(ctx, enveloped, duration_ms)
             _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
             return enveloped
 
@@ -16120,8 +16189,15 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Open a multi-step execution trace so subsequent tool calls thread under this execution ID.
       end_execution(execution_id?, verification?, status?, notes?) -> {success, trace}
         — Conclude an execution trace and compute final rollups.
+      export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?) -> {success, path, bytes}
+        — Write a Markdown or JSON audit report for an execution trace (no connection needed).
       clear_executions(dry_run?) -> {success, cleared}
         — Clear the in-memory execution trace buffer.
+      inspect_operation(tool?, target_action?, target_params?) -> {tool, action, risk, destructive, blast_radius, confirmation_required, snapshot_available, recognised, reasons, pre_state, pre_state_available}
+        — Name-based heuristic, NOT a simulation: it never touches the project and does not validate params. recognised=false means no rule matched; snapshot_available=null means rollback was not determined, not that none exists.
+        — Pre-flight risk assessment and blast radius inspection for any tool action before execution (no connection needed).
+      list_lifecycle_hooks() -> {success, hooks, count}
+        — List active agent tool execution lifecycle hooks and their enabled status (no connection needed).
     """
     p = _params(params)
 
@@ -16249,12 +16325,47 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if not trace:
             return _err("No active or matching execution to end", code="NOT_FOUND", category="state")
         return {"success": True, "trace": trace}
+    if action == "export_execution_report":
+        exec_id = p.get("execution_id") or p.get("id")
+        report_format = p.get("format") or p.get("report_format") or "markdown"
+        include_steps = _setup_bool(p.get("include_steps", p.get("includeSteps")), True)
+        overwrite = _setup_bool(p.get("overwrite"), False)
+        try:
+            res = _execution_trace.export_execution_report(
+                execution_id=exec_id,
+                report_format=report_format,
+                output_path=p.get("path") or p.get("output_path") or p.get("outputPath"),
+                overwrite=overwrite,
+                include_steps=include_steps,
+            )
+        except FileExistsError as exc:
+            return _err(str(exc), code="REPORT_EXISTS", category="invalid_input")
+        except ValueError as exc:
+            return _err(str(exc), code="INVALID_REPORT_FORMAT", category="invalid_input")
+        except OSError as exc:
+            return _err(
+                "Could not write execution report",
+                code="REPORT_WRITE_FAILED",
+                category="io",
+                reason=str(exc),
+            )
+        if not res:
+            return _err(f"No execution trace found for id: {exec_id or 'latest'}", code="NOT_FOUND", category="state")
+        return res
     if action == "clear_executions":
         dry_run = _setup_bool(p.get("dry_run", p.get("dryRun")), False)
         if dry_run:
             return {"success": True, "dry_run": True, "count": len(_execution_trace.list_recent_executions(100))}
         res = _execution_trace.clear_executions()
         return res
+    if action == "inspect_operation":
+        target_tool = p.get("tool") or p.get("tool_name") or "timeline"
+        target_action = p.get("target_action") or p.get("action") or p.get("op") or "delete_clips"
+        target_params = p.get("target_params") or p.get("params") or {}
+        return _execution_lifecycle.inspect_operation(target_tool, target_action, target_params)
+    if action == "list_lifecycle_hooks":
+        hooks = _execution_lifecycle.list_lifecycle_hooks()
+        return {"success": True, "hooks": hooks, "count": len(hooks)}
 
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
@@ -16470,7 +16581,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","clear_executions","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/execution_lifecycle.py

@@ -0,0 +1,496 @@
+"""Universal MCP Tool Execution Lifecycle and Hook Pipeline.
+
+Provides a pluggable, server-wide lifecycle middleware for all compound MCP tools.
+Every tool invocation (synchronous or asynchronous) passes through three distinct
+lifecycle phases:
+
+  1. Pre-flight (run_before):
+     - Risk classification and blast radius calculation (low -> critical)
+     - Resolve state inspection (pre-flight timeline duration, track count, project)
+     - Safe dry-run simulation interception for non-native dry-run actions
+  2. Execution / Error tracking (run_on_error):
+     - Catches exceptions, records duration, informs error observers
+  3. Post-flight (run_after):
+     - Readback verification and contradiction evaluation
+     - State drift detection (unintended timeline duration/structure shifts)
+     - Correlated execution trace aggregation
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple
+
+logger = logging.getLogger("resolve-mcp.execution-lifecycle")
+
+
+class RiskLevel(str, enum.Enum):
+    """Categorized risk level for tool operations."""
+    LOW = "low"            # Read-only queries, info probes, status checks
+    MEDIUM = "medium"      # Reversible edits, markers, non-destructive properties
+    HIGH = "high"          # Deletions, ripples, timeline restructuring, batch edits
+    CRITICAL = "critical"  # Project deletion, database resets, permanent loss
+
+
+class BlastRadius(str, enum.Enum):
+    """Scope of impact when an operation executes."""
+    ITEM = "item"          # Single clip, single marker, node
+    TRACK = "track"        # Single track or stem
+    TIMELINE = "timeline"  # Entire active timeline
+    PROJECT = "project"    # Entire Resolve project or Media Pool
+    SYSTEM = "system"      # System preferences, filesystem, host process
+
+
+@dataclass
+class RiskAssessment:
+    """Calculated risk evaluation for a tool action."""
+    level: RiskLevel = RiskLevel.LOW
+    destructive: bool = False
+    blast_radius: BlastRadius = BlastRadius.ITEM
+    confirmation_required: bool = False
+    #: None = not determined. The classifier reads action names; it does not
+    #: know whether timeline_versioning would archive a predecessor, and False
+    #: would assert "no rollback" as a finding it never made.
+    snapshot_available: Optional[bool] = None
+    #: False when no rule matched, i.e. the fields below are name-based
+    #: defaults rather than an assessment of this specific operation.
+    recognised: bool = True
+    reasons: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "level": self.level.value,
+            "destructive": self.destructive,
+            "blast_radius": self.blast_radius.value,
+            "confirmation_required": self.confirmation_required,
+            "snapshot_available": self.snapshot_available,
+            "recognised": self.recognised,
+            "reasons": list(self.reasons),
+        }
+
+
+@dataclass
+class ToolCallContext:
+    """Contextual metadata describing an in-flight tool invocation."""
+    tool_name: str
+    action: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    execution_id: Optional[str] = None
+    risk: RiskAssessment = field(default_factory=RiskAssessment)
+    pre_state: Optional[Dict[str, Any]] = None
+    post_state: Optional[Dict[str, Any]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookDecision:
+    """Decision returned by a pre-flight hook."""
+    proceed: bool = True
+    short_circuit_result: Optional[Dict[str, Any]] = None
+    reason: Optional[str] = None
+
+
+class LifecycleHook:
+    """Base class for all MCP tool lifecycle hooks."""
+    name: str = "base_hook"
+    enabled: bool = True
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        """Runs before tool invocation. Can short-circuit or modify context."""
+        return None
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        """Runs after successful tool execution. Can enrich result or emit telemetry."""
+        return None
+
+    def on_error(
+        self, ctx: ToolCallContext, exc: Exception, duration_ms: int
+    ) -> None:
+        """Runs when tool execution raises an unhandled exception."""
+        pass
+
+
+# ─── Built-in Hook Implementations ──────────────────────────────────────────
+
+
+class RiskClassificationHook(LifecycleHook):
+    """Evaluates tool + action + params to classify danger level and blast radius."""
+    name = "risk_classification"
+
+    _CRITICAL_ACTIONS: Set[Tuple[str, str]] = {
+        ("project_manager", "delete_project"),
+        ("project_manager", "close_project_without_saving"),
+        ("media_pool", "delete_timelines"),
+        ("media_pool", "delete_clips"),
+    }
+
+    _HIGH_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        ("timeline", "delete_clips"),
+        ("timeline", "delete_clip_by_id"),
+        ("timeline", "delete_markers"),
+        ("timeline", "ripple_delete"),
+        ("timeline", "cut_clip"),
+        ("edit_engine", "execute_selects"),
+        ("edit_engine", "auto_cut_silence"),
+        ("edit_engine", "ripple_trim"),
+        ("project_manager", "save_project_as"),
+    }
+
+    _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
+
+    @classmethod
+    def classify(cls, tool_name: str, action: str, params: Dict[str, Any]) -> RiskAssessment:
+        reasons: List[str] = []
+        destructive = False
+        level = RiskLevel.LOW
+        radius = BlastRadius.ITEM
+        conf_required = False
+        recognised = True
+
+        pair = (tool_name, action)
+
+        if pair in cls._CRITICAL_ACTIONS:
+            level = RiskLevel.CRITICAL
+            destructive = True
+            radius = BlastRadius.PROJECT if "project" in tool_name else BlastRadius.TIMELINE
+            conf_required = True
+            reasons.append(f"Action '{action}' is permanently destructive across {radius.value}")
+        elif pair in cls._HIGH_RISK_ACTIONS or action.startswith("delete_") or action.startswith("remove_"):
+            level = RiskLevel.HIGH
+            destructive = True
+            if params.get("ripple", False):
+                radius = BlastRadius.TIMELINE
+                reasons.append("Ripple mode alters downstream timeline synchronization")
+            else:
+                radius = BlastRadius.ITEM
+            conf_required = True
+            reasons.append(f"Destructive timeline edit: {action}")
+        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"}:
+            level = RiskLevel.LOW
+            destructive = False
+            radius = BlastRadius.ITEM
+        else:
+            # Everything the rules do not recognise. This is a heuristic over
+            # action NAMES, so "unrecognised" covers both a real action nobody
+            # listed and an action that does not exist — and it must not come
+            # back as a confident "medium, not destructive". The guard exists
+            # for hallucinated calls; answering one with reassurance is the
+            # failure it was built to prevent.
+            level = RiskLevel.MEDIUM
+            destructive = action.startswith("reset_") or action.startswith("clear_")
+            radius = BlastRadius.ITEM
+            recognised = False
+            reasons.append(
+                f"'{tool_name}.{action}' matches no risk rule. This assessment is a "
+                "name-based default, not a finding — treat the risk as unestablished "
+                "and check the tool's own documented behaviour before proceeding."
+            )
+
+        return RiskAssessment(
+            level=level,
+            destructive=destructive,
+            blast_radius=radius,
+            confirmation_required=conf_required,
+            snapshot_available=None,
+            reasons=reasons,
+            recognised=recognised,
+        )
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        ctx.risk = self.classify(ctx.tool_name, ctx.action, ctx.params)
+        return None
+
+
+class ResolveStateInspectionHook(LifecycleHook):
+    """Captures pre-flight Resolve project and timeline state non-blockingly."""
+    name = "resolve_state_inspection"
+
+    def __init__(self, state_provider: Optional[Callable[[], Optional[Dict[str, Any]]]] = None):
+        self._state_provider = state_provider
+
+    def before_tool_call(self, ctx: ToolCallContext) -> Optional[HookDecision]:
+        if self._state_provider is None:
+            return None
+        try:
+            state = self._state_provider()
+            if state:
+                ctx.pre_state = state
+                ctx.risk.snapshot_available = True
+        except Exception as exc:
+            logger.debug(f"Pre-flight state inspection skipped: {exc}")
+        return None
+
+
+class ReadbackVerificationHook(LifecycleHook):
+    """Evaluates readback verification data attached to operation results."""
+    name = "readback_verification"
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        if not isinstance(result, dict):
+            return None
+
+        # Check if result carries a verification block
+        verif = result.get("verification")
+        if isinstance(verif, dict):
+            contradiction = verif.get("contradiction", False)
+            verified = verif.get("verified", False)
+            if contradiction:
+                logger.warning(
+                    f"Readback contradiction detected on {ctx.tool_name}.{ctx.action}: {verif}"
+                )
+            return {
+                "readback_checked": True,
+                "verified": verified,
+                "contradiction": contradiction,
+            }
+
+        # Track unverified destructive operations
+        if ctx.risk.destructive and "verification" not in result:
+            return {
+                "readback_checked": False,
+                "status": "unverified",
+                "notice": f"Destructive operation {ctx.tool_name}.{ctx.action} completed without readback verification",
+            }
+        return None
+
+
+class DriftDetectionHook(LifecycleHook):
+    """Detects unexpected timeline duration or track structure drift."""
+    name = "drift_detection"
+
+    _DURATION_ALTERING_ACTIONS = {
+        "ripple_delete", "ripple_insert", "auto_cut_silence", "execute_selects",
+        "delete_clips", "cut_clip", "delete_item", "ripple_trim"
+    }
+
+    def __init__(self, state_provider: Optional[Callable[[], Optional[Dict[str, Any]]]] = None):
+        self._state_provider = state_provider
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        if not ctx.pre_state or self._state_provider is None:
+            return None
+
+        try:
+            post_state = self._state_provider()
+            if not post_state:
+                return None
+            ctx.post_state = post_state
+
+            pre_dur = ctx.pre_state.get("duration_frames")
+            post_dur = post_state.get("duration_frames")
+
+            # Check if duration changed on a non-duration-altering action
+            if (
+                pre_dur is not None
+                and post_dur is not None
+                and pre_dur != post_dur
+                and ctx.action not in self._DURATION_ALTERING_ACTIONS
+            ):
+                warning = (
+                    f"Timeline duration drifted unexpectedly from {pre_dur} to {post_dur} frames "
+                    f"during non-duration altering action '{ctx.action}'"
+                )
+                logger.warning(warning)
+                return {
+                    "drift_detected": True,
+                    "drift_warnings": [warning],
+                    "duration_delta_frames": post_dur - pre_dur,
+                }
+        except Exception as exc:
+            logger.debug(f"Drift detection evaluation skipped: {exc}")
+        return None
+
+
+class ProvenanceTraceHook(LifecycleHook):
+    """Correlates tool lifecycle events into the active execution trace."""
+    name = "provenance_trace"
+
+    def after_tool_call(
+        self, ctx: ToolCallContext, result: Any, duration_ms: int
+    ) -> Optional[Dict[str, Any]]:
+        return {
+            "execution_id": ctx.execution_id,
+            "duration_ms": duration_ms,
+            "risk_level": ctx.risk.level.value,
+        }
+
+
+# ─── Pipeline Coordinator ───────────────────────────────────────────────────
+
+
+class LifecyclePipeline:
+    """Thread-safe coordinator running registered lifecycle hooks."""
+
+    def __init__(self):
+        self._hooks: List[LifecycleHook] = []
+        self._lock = threading.RLock()
+        self._register_default_hooks()
+
+    def _register_default_hooks(self):
+        """The hooks that ship enabled. All of them OBSERVE; none short-circuit.
+
+        `HookDecision(proceed=False)` exists so a deliberately registered hook
+        can gate a call, and `register_hook` is public for that. Nothing
+        shipping uses it, on purpose: a hook that replaces a tool's result is
+        answering on behalf of code that never ran.
+
+        The original of this pipeline shipped a dry-run interceptor that did
+        exactly that — any `dry_run: true` call outside a four-entry allowlist
+        was short-circuited with a synthesised `success: true`. Against 273
+        `dry_run` references in `src/server.py` it hijacked actions with real
+        dry-run paths (`setup.set_defaults`, `resolve_control.clear_executions`),
+        and it answered `success: true` for an invalid enum value and for adding
+        a marker with no timeline in existence. `dry_run` is the one thing an
+        editor reaches for before a destructive edit; a version of it that
+        always succeeds is worse than none, because it is trusted.
+        `test_no_default_hook_short_circuits` keeps it that way.
+        """
+        self._hooks.append(RiskClassificationHook())
+        self._hooks.append(ResolveStateInspectionHook())
+        self._hooks.append(ReadbackVerificationHook())
+        self._hooks.append(DriftDetectionHook())
+        self._hooks.append(ProvenanceTraceHook())
+
+    def register_hook(self, hook: LifecycleHook) -> None:
+        with self._lock:
+            # Replace existing hook with same name if present
+            self._hooks = [h for h in self._hooks if h.name != hook.name]
+            self._hooks.append(hook)
+
+    def set_state_provider(self, provider: Callable[[], Optional[Dict[str, Any]]]) -> None:
+        """Configures state provider callable on inspection and drift hooks."""
+        with self._lock:
+            for hook in self._hooks:
+                if isinstance(hook, (ResolveStateInspectionHook, DriftDetectionHook)):
+                    hook._state_provider = provider
+
+    def run_before(self, ctx: ToolCallContext) -> HookDecision:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                decision = hook.before_tool_call(ctx)
+                if decision and not decision.proceed:
+                    return decision
+            except Exception as exc:
+                logger.error(f"Error in hook '{hook.name}.before_tool_call': {exc}", exc_info=True)
+        return HookDecision(proceed=True)
+
+    def run_after(self, ctx: ToolCallContext, result: Any, duration_ms: int) -> Any:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        contributions: Dict[str, Any] = {}
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                contrib = hook.after_tool_call(ctx, result, duration_ms)
+                if contrib and isinstance(contrib, dict):
+                    contributions[hook.name] = contrib
+            except Exception as exc:
+                logger.error(f"Error in hook '{hook.name}.after_tool_call': {exc}", exc_info=True)
+
+        # Attach telemetry into operation envelope or result if it's a dict
+        if isinstance(result, dict) and contributions:
+            if "_operation" in result and isinstance(result["_operation"], dict):
+                result["_operation"].setdefault("lifecycle", {}).update(contributions)
+        return result
+
+    def run_on_error(self, ctx: ToolCallContext, exc: Exception, duration_ms: int) -> None:
+        with self._lock:
+            hooks = list(self._hooks)
+
+        for hook in hooks:
+            if not hook.enabled:
+                continue
+            try:
+                hook.on_error(ctx, exc, duration_ms)
+            except Exception as hook_exc:
+                logger.error(f"Error in hook '{hook.name}.on_error': {hook_exc}", exc_info=True)
+
+    def list_hooks(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            return [
+                {
+                    "name": h.name,
+                    "enabled": h.enabled,
+                    "class": h.__class__.__name__,
+                }
+                for h in self._hooks
+            ]
+
+    def inspect_operation(
+        self, tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Inspects pre-flight risk, blast radius, and state before execution."""
+        p = params or {}
+        assessment = RiskClassificationHook.classify(tool_name, action, p)
+        pre_state = None
+        for hook in self._hooks:
+            if isinstance(hook, ResolveStateInspectionHook) and hook._state_provider:
+                try:
+                    pre_state = hook._state_provider()
+                except Exception:
+                    pass
+                break
+
+        return {
+            "success": True,
+            "tool": tool_name,
+            "action": action,
+            "risk": assessment.to_dict(),
+            "destructive": assessment.destructive,
+            "blast_radius": assessment.blast_radius.value,
+            "confirmation_required": assessment.confirmation_required,
+            # One value, from one place. This previously reported
+            # `assessment.snapshot_available or (pre_state is not None)` at the
+            # top level while `risk.snapshot_available` stayed False — the same
+            # response answering "can I roll this back?" both ways. Reading a
+            # project name is not a restorable snapshot, and the classifier
+            # never sets the flag, so the honest answer is "not determined".
+            "snapshot_available": assessment.snapshot_available,
+            "reasons": assessment.reasons,
+            "recognised": assessment.recognised,
+            "pre_state": pre_state,
+            # Whether pre_state reflects a live Resolve at all, so a caller can
+            # tell "no project open" from "never asked".
+            "pre_state_available": pre_state is not None,
+        }
+
+
+# Global singleton pipeline
+_GLOBAL_PIPELINE = LifecyclePipeline()
+
+
+def get_lifecycle_pipeline() -> LifecyclePipeline:
+    return _GLOBAL_PIPELINE
+
+
+def inspect_operation(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    return _GLOBAL_PIPELINE.inspect_operation(tool_name, action, params)
+
+
+def list_lifecycle_hooks() -> List[Dict[str, Any]]:
+    return _GLOBAL_PIPELINE.list_hooks()
+
+
+def classify_operation_risk(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None
+) -> RiskAssessment:
+    return RiskClassificationHook.classify(tool_name, action, params or {})
+

package/src/utils/execution_trace.py

@@ -26,11 +26,12 @@ import collections
 import json
 import logging
 import os
+import re
 import threading
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Deque, Dict, List, Optional
+from typing import Any, Deque, Dict, List, Optional, Union
 
 logger = logging.getLogger("resolve-mcp.execution-trace")
 
@@ -135,8 +136,12 @@ def _merge_verification(
         status = "passed"
         passed = True
     else:
+        # None, not True. Nothing reported any evidence either way, and
+        # collapsing that into a boolean makes the rollup assert a pass it
+        # never observed — which then reaches a human as "Passed: yes" in an
+        # exported audit report.
         status = "unverified"
-        passed = True
+        passed = None
 
     return {
         "status": status,
@@ -174,7 +179,10 @@ def begin_execution(
         "changes": None,
         "verification": {
             "status": "unverified",
-            "passed": True,
+            # None, not True. "Nothing was checked" is not "everything passed",
+            # and the difference reaches a human in an exported audit report —
+            # see _execution_report_markdown.
+            "passed": None,
             "contradiction": False,
             "checks": [],
         },
@@ -313,7 +321,7 @@ def record_step(
                 "changes": None,
                 "verification": {
                     "status": "unverified",
-                    "passed": True,
+                    "passed": None,  # see above: unknown, not passed
                     "contradiction": False,
                     "checks": [],
                 },
@@ -338,7 +346,7 @@ def record_step(
                     "changes": None,
                     "verification": {
                         "status": "unverified",
-                        "passed": True,
+                        "passed": None,  # see above: unknown, not passed
                         "contradiction": False,
                         "checks": [],
                     },
@@ -466,6 +474,247 @@ def clear_executions() -> Dict[str, Any]:
     return {"success": True, "cleared": count}
 
 
+# ── Audit Reports ───────────────────────────────────────────────────────────
+
+def _report_format(report_format: str) -> str:
+    fmt = str(report_format or "markdown").strip().lower()
+    if fmt in {"md", "markdown"}:
+        return "markdown"
+    if fmt == "json":
+        return "json"
+    raise ValueError("format must be markdown or json")
+
+
+def _report_extension(report_format: str) -> str:
+    return ".md" if _report_format(report_format) == "markdown" else ".json"
+
+
+def _report_filename(execution_id: str, report_format: str) -> str:
+    safe_id = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(execution_id or "execution")).strip("._")
+    if not safe_id:
+        safe_id = "execution"
+    return f"{safe_id}{_report_extension(report_format)}"
+
+
+def execution_report_dir() -> str:
+    """Directory used for generated execution audit reports."""
+    override = os.environ.get("RESOLVE_MCP_TRACE_REPORT_DIR")
+    if override:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    return str(_REPO_ROOT / "logs" / "execution-reports")
+
+
+def _default_report_path(trace: Dict[str, Any], report_format: str) -> str:
+    return str(Path(execution_report_dir()) / _report_filename(trace["execution_id"], report_format))
+
+
+def _format_ms(value: Any) -> str:
+    try:
+        return f"{max(0, int(value))} ms"
+    except (TypeError, ValueError):
+        return "0 ms"
+
+
+def _scalar(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, sort_keys=True, ensure_ascii=False)
+    return str(value)
+
+
+def _markdown_row(*cells: Any) -> str:
+    escaped = []
+    for cell in cells:
+        text = _scalar(cell).replace("\n", " ").replace("|", "\\|")
+        escaped.append(text)
+    return "| " + " | ".join(escaped) + " |"
+
+
+def _execution_report_json(trace: Dict[str, Any], *, include_steps: bool = True) -> Dict[str, Any]:
+    """Return a stable, compact report object derived from safe trace summaries."""
+    out = {
+        "execution_id": trace.get("execution_id"),
+        "request": trace.get("request"),
+        "status": trace.get("status"),
+        "started_at": trace.get("started_at"),
+        "ended_at": trace.get("ended_at"),
+        "duration_ms": trace.get("duration_ms", 0),
+        "initiator": trace.get("initiator"),
+        "is_active": trace.get("is_active", False),
+        "tools": trace.get("tools", []),
+        "changes": trace.get("changes"),
+        "verification": trace.get("verification", {}),
+        "warnings": trace.get("warnings", []),
+    }
+    if trace.get("notes"):
+        out["notes"] = trace.get("notes")
+    if include_steps:
+        out["steps"] = trace.get("steps", [])
+    return out
+
+
+def _execution_report_markdown(trace: Dict[str, Any], *, include_steps: bool = True) -> str:
+    report = _execution_report_json(trace, include_steps=include_steps)
+    lines = [
+        "# Execution Audit Report",
+        "",
+        _markdown_row("Field", "Value"),
+        _markdown_row("---", "---"),
+        _markdown_row("Execution ID", report.get("execution_id")),
+        _markdown_row("Request", report.get("request")),
+        _markdown_row("Status", report.get("status")),
+        _markdown_row("Started", report.get("started_at")),
+        _markdown_row("Ended", report.get("ended_at")),
+        _markdown_row("Duration", _format_ms(report.get("duration_ms"))),
+        _markdown_row("Initiator", report.get("initiator")),
+        "",
+        "## Tool Summary",
+        "",
+    ]
+
+    tools = report.get("tools") or []
+    if tools:
+        lines.extend([
+            _markdown_row("Tool", "Calls", "Duration"),
+            _markdown_row("---", "---:", "---:"),
+        ])
+        for tool in tools:
+            lines.append(_markdown_row(tool.get("tool"), tool.get("count", 0), _format_ms(tool.get("duration_ms"))))
+    else:
+        lines.append("No tool calls recorded.")
+
+    lines.extend(["", "## Changes", ""])
+    changes = report.get("changes")
+    if isinstance(changes, dict) and changes:
+        lines.extend([
+            _markdown_row("Change", "Value"),
+            _markdown_row("---", "---"),
+        ])
+        for key in sorted(changes):
+            lines.append(_markdown_row(key, changes[key]))
+    else:
+        lines.append("No semantic changes recorded.")
+
+    verification = report.get("verification") or {}
+    lines.extend([
+        "",
+        "## Verification",
+        "",
+        _markdown_row("Field", "Value"),
+        _markdown_row("---", "---"),
+        _markdown_row("Status", verification.get("status")),
+        _markdown_row("Passed", _verification_passed_label(verification)),
+        _markdown_row("Contradiction", verification.get("contradiction")),
+        _markdown_row("Checks", len(verification.get("checks") or [])),
+    ])
+
+    warnings = report.get("warnings") or []
+    lines.extend(["", "## Warnings", ""])
+    if warnings:
+        lines.extend(f"- {_scalar(w)}" for w in warnings)
+    else:
+        lines.append("No warnings recorded.")
+
+    if report.get("notes"):
+        lines.extend(["", "## Notes", "", _scalar(report["notes"])])
+
+    if include_steps:
+        lines.extend(["", "## Steps", ""])
+        steps = report.get("steps") or []
+        if steps:
+            lines.extend([
+                _markdown_row("#", "Timestamp", "Operation", "Status", "Duration"),
+                _markdown_row("---:", "---", "---", "---", "---:"),
+            ])
+            for step in steps:
+                lines.append(_markdown_row(
+                    step.get("seq"),
+                    step.get("timestamp"),
+                    step.get("operation"),
+                    step.get("status"),
+                    _format_ms(step.get("duration_ms")),
+                ))
+        else:
+            lines.append("No steps recorded.")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _verification_passed_label(verification: Dict[str, Any]) -> str:
+    """How the Passed row reads when nothing was actually verified.
+
+    A report that prints `Status: unverified` beside `Passed: yes` is read by a
+    human as "it passed" — the two lines are inches apart and only one of them
+    is scanned. Unverified means no evidence was reported, which is a question
+    still open, not a clean bill of health; an audit document is the last place
+    that distinction should be left to the reader.
+    """
+    passed = verification.get("passed")
+    if passed is None:
+        return "not established — no checks recorded"
+    return "yes" if passed else "no"
+
+
+def render_execution_report(
+    trace: Dict[str, Any],
+    *,
+    report_format: str = "markdown",
+    include_steps: bool = True,
+) -> Union[str, Dict[str, Any]]:
+    """Render an execution trace as a Markdown or JSON audit report."""
+    fmt = _report_format(report_format)
+    if fmt == "json":
+        return _execution_report_json(trace, include_steps=include_steps)
+    return _execution_report_markdown(trace, include_steps=include_steps)
+
+
+def export_execution_report(
+    execution_id: Optional[str] = None,
+    *,
+    report_format: str = "markdown",
+    output_path: Optional[str] = None,
+    overwrite: bool = False,
+    include_steps: bool = True,
+) -> Optional[Dict[str, Any]]:
+    """Write an execution audit report to disk.
+
+    The export is built from trace summaries, not raw tool arguments/results.
+    """
+    trace = get_execution_trace(execution_id)
+    if not trace:
+        return None
+
+    fmt = _report_format(report_format)
+    path = output_path or _default_report_path(trace, fmt)
+    real_path = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
+    if os.path.exists(real_path) and not overwrite:
+        raise FileExistsError(f"Report already exists: {real_path}")
+
+    rendered = render_execution_report(trace, report_format=fmt, include_steps=include_steps)
+    os.makedirs(os.path.dirname(real_path), exist_ok=True)
+    if fmt == "json":
+        payload = json.dumps(rendered, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+    else:
+        payload = str(rendered)
+    with open(real_path, "w", encoding="utf-8") as fh:
+        fh.write(payload)
+
+    return {
+        "success": True,
+        "execution_id": trace["execution_id"],
+        "format": fmt,
+        "path": real_path,
+        "bytes": len(payload.encode("utf-8")),
+        "included_steps": bool(include_steps),
+    }
+
+
 # ── Persistence (Best-Effort) ────────────────────────────────────────────────
 
 def trace_log_path() -> str: