davinci-resolve-mcp 2.207.0 → 2.208.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.207.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)
@@ -280,6 +280,17 @@ reviewable audit artifact with the same summary, defaulting to
 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,

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.207.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.207.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.208.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -174,7 +174,9 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 ### 导出执行审计报告
 
-`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。
+`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"（未确立——没有记录任何检查）**，而不是"通过"。没有证据是一个仍然悬而未决的问题；审计文件恰恰是最不该让读者把它读成"一切正常"的地方。
 

package/docs/SKILL.md

@@ -277,6 +277,24 @@ Example trace shape returned by `resolve_control(action="get_execution_trace")`:
   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.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.207.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.207.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.207.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.207.0"
+VERSION = "2.208.0"
 
 import base64
 import os
@@ -76,6 +76,11 @@ from src.utils.execution_trace import (
     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,
     render_format_id_from_formats as _render_format_id_from_formats,
@@ -887,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.
 
@@ -1501,6 +1537,7 @@ _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",
 }
 
 
@@ -1573,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:
@@ -1588,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
 
@@ -16126,6 +16193,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — 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)
 
@@ -16286,6 +16358,14 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             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":
@@ -16501,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","export_execution_report","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 {})
+