davinci-resolve-mcp 2.208.1 → 2.209.1

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 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.209.1 — the test suite no longer writes to the security audit log
+
+### Fixed
+
+- **Running the suite appended fabricated events to `logs/security-audit.jsonl`.**
+  The destructive-op audit log added in v2.209.0 defaults to that path, which is
+  correct for an install and wrong for a test run: any test exercising a
+  `@destructive_op`-wrapped handler wrote a genuine-looking record.
+  `tests/test_tool_argument_validation` walks every tool, so a single run added
+  24 synthetic `delete_timelines` / `reset_all_grades` / `apply_cuts` entries,
+  and repeated runs accumulated 216.
+
+  A security log is read to establish what actually happened, so synthetic rows
+  in it are worse than a missing feature — at the point someone needs to trust
+  the file they are indistinguishable from real events. `tests/offline_guard`
+  now redirects the audit path to a temp file for the whole run, covering both
+  the pytest and `python -m unittest` entry points, and only replaces the
+  *default*: a test that configures `destructive.audit_log_path` still gets its
+  own path. A regression test asserts the active path is never inside the repo.
+
+  No released behaviour changes — the default remains `logs/security-audit.jsonl`
+  for real installs. Anyone who ran the v2.209.0 suite should expect synthetic
+  rows in their local file; they carry temp-directory `project_root` values.
+
+## What's New in v2.209.0 — safe operations policy
+
+### Added
+
+- **Destructive operations now carry explicit security metadata** — wrapped
+  destructive tool calls receive an `operation_id` plus a `security` block with
+  a `risk_level` (`low`, `medium`, `high`, or `critical`) and a
+  `risk_established` flag. The existing version-on-mutate and confirm-token
+  gates stay intact, but callers now have a stable policy surface to inspect
+  and display before or after a Resolve mutation.
+
+  Levels come from the same classifier that backs pre-flight
+  `inspect_operation`, so the gate and the inspection surface cannot disagree
+  about a call. `risk_established` is false when the classifier matched no rule
+  and the level is a name-based default rather than a finding — true today for
+  80 of the 108 registered destructive actions, which is a gap to close by
+  classifying them, not by gating them.
+- **Safe mode blocks high-risk destructive calls when enabled** —
+  `setup(action="set_defaults", params={"destructive": {"safe_mode": true}})`
+  blocks `high` and `critical` actions before the underlying Resolve handler
+  runs. Reviewed one-off calls can proceed with `allow_risky_operation=true`.
+  Unclassified actions are reported, not blocked.
+- **Security audit JSONL for destructive calls** — allowed, blocked, and
+  pending-confirmation destructive calls write audit events to
+  `logs/security-audit.jsonl` by default. Confirmation tokens are redacted in
+  the audit payload.
+
+### Changed
+
+- **Risk classification is now one table, not two** — the marker and
+  clip-colour actions classify as `low` instead of falling through the name
+  heuristic as unrecognised `medium`, and `timeline.lift_range`,
+  `timeline.overwrite_range`, `timeline.apply_cuts`, `timeline.delete_track`,
+  `media_pool.delete_folders` and `graph.reset_all_grades` are now classified
+  `high` wherever risk is reported, including pre-flight inspection.
+- **`setup` exposes destructive defaults** — `destructive.require_confirm_token`,
+  `destructive.safe_mode`, `destructive.audit_log`, and
+  `destructive.audit_log_path` are now visible through `schema`, persisted by
+  `set_defaults`, and reset by `clear_defaults`.
+
 ## What's New in v2.208.1 — #188: variant item counts come from the timeline
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.208.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.209.1-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)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.208.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.209.1-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.208.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.209.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.208.1"
+VERSION = "2.209.1"
 # 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.208.1",
+  "version": "2.209.1",
   "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.208.1"
+VERSION = "2.209.1"
 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.208.1"
+VERSION = "2.209.1"
 
 import base64
 import os
@@ -1248,7 +1248,12 @@ def _ai_governance_gate(op: str, p: Dict[str, Any]) -> Optional[Dict[str, Any]]:
 def _destructive_preference_provider(key: str) -> Any:
     """Reader for C6 preferences out of the existing media-analysis prefs file."""
     try:
-        return _read_media_analysis_preferences().get(key)
+        prefs = _read_media_analysis_preferences()
+        if key.startswith("destructive."):
+            destructive = prefs.get("destructive")
+            if isinstance(destructive, dict):
+                return destructive.get(key.split(".", 1)[1])
+        return prefs.get(key)
     except Exception:
         return None
 
@@ -15425,6 +15430,101 @@ def _setup_defaults_snapshot() -> Dict[str, Any]:
         "general": _setup_general_defaults(),
         "media_analysis": _setup_media_analysis_defaults(),
         "updates": _setup_updates_defaults(),
+        "destructive": _setup_destructive_defaults(),
+    }
+
+
+def _setup_destructive_defaults() -> Dict[str, Any]:
+    prefs = _read_media_analysis_preferences()
+    destructive = prefs.get("destructive") if isinstance(prefs.get("destructive"), dict) else {}
+    return {
+        "require_confirm_token": _setup_bool(destructive.get("require_confirm_token"), True),
+        "safe_mode": _setup_bool(destructive.get("safe_mode"), False),
+        "audit_log": _setup_bool(destructive.get("audit_log"), True),
+        "audit_log_path": destructive.get("audit_log_path") or os.path.join(project_dir, "logs", "security-audit.jsonl"),
+        "preferences_path": _media_analysis_preferences_path(),
+    }
+
+
+def _setup_set_destructive_defaults(destructive_defaults: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
+    if not destructive_defaults:
+        return {"changed": False, "recognized": False}
+
+    alias_to_key = {
+        "require_confirm_token": "require_confirm_token",
+        "requireconfirmtoken": "require_confirm_token",
+        "confirm_token": "require_confirm_token",
+        "confirmtoken": "require_confirm_token",
+        "safe_mode": "safe_mode",
+        "safemode": "safe_mode",
+        "audit_log": "audit_log",
+        "auditlog": "audit_log",
+        "audit_log_path": "audit_log_path",
+        "auditlogpath": "audit_log_path",
+    }
+    requested: Dict[str, Any] = {}
+    for key, value in destructive_defaults.items():
+        normalized_key = alias_to_key.get(_setup_text_key(key).replace("_", ""))
+        if not normalized_key:
+            normalized_key = alias_to_key.get(_setup_text_key(key))
+        if normalized_key:
+            requested[normalized_key] = value
+    if not requested:
+        return {"changed": False, "recognized": False}
+
+    try:
+        preferences = _read_media_analysis_preferences_strict()
+    except ConfigParseError as exc:
+        return _err(f"Refusing to update destructive defaults: {exc}. The preferences file exists but is unparseable; fix or delete it to avoid wiping saved settings.")
+
+    before = _setup_destructive_defaults()
+    next_preferences = dict(preferences)
+    destructive = dict(next_preferences.get("destructive") if isinstance(next_preferences.get("destructive"), dict) else {})
+    updates: Dict[str, Dict[str, Any]] = {}
+
+    def clear_requested(raw: Any) -> bool:
+        return raw is None or (not isinstance(raw, bool) and _setup_text_key(raw) in _SETUP_CHOICE_CLEAR_VALUES)
+
+    for key, raw_value in requested.items():
+        if clear_requested(raw_value):
+            destructive.pop(key, None)
+            updates[key] = {"before": before.get(key), "after": _setup_destructive_defaults().get(key), "cleared": True}
+        elif key in {"require_confirm_token", "safe_mode", "audit_log"}:
+            normalized = _setup_bool(raw_value, before.get(key, False))
+            destructive[key] = normalized
+            updates[key] = {"before": before.get(key), "after": normalized}
+        elif key == "audit_log_path":
+            path = os.path.realpath(os.path.abspath(os.path.expanduser(str(raw_value))))
+            destructive[key] = path
+            updates[key] = {"before": before.get(key), "after": path}
+
+    if dry_run:
+        return {
+            "changed": True,
+            "recognized": True,
+            "updates": updates,
+            "before": before,
+            "after": {**before, **{key: row.get("after") for key, row in updates.items()}},
+            "dry_run": True,
+        }
+
+    updated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    for key, row in updates.items():
+        if not row.get("cleared"):
+            destructive[f"{key}_updated_at"] = updated_at
+        else:
+            destructive.pop(f"{key}_updated_at", None)
+    next_preferences["destructive"] = destructive
+    _write_media_analysis_preferences(next_preferences)
+    after = _setup_destructive_defaults()
+    return {
+        "changed": before != after,
+        "recognized": True,
+        "updates": updates,
+        "before": before,
+        "after": after,
+        "updated_at": updated_at,
+        "preferences_path": _media_analysis_preferences_path(),
     }
 
 
@@ -15939,6 +16039,25 @@ def _setup_clear_defaults(keys: Any, dry_run: bool) -> Dict[str, Any]:
             return result["media_analysis"]
         result["cleared"].extend(media_clear_keys[key] for key in media_payload)
 
+    destructive_clear_keys = {
+        "require_confirm_token": "destructive.require_confirm_token",
+        "safe_mode": "destructive.safe_mode",
+        "audit_log": "destructive.audit_log",
+        "audit_log_path": "destructive.audit_log_path",
+    }
+    destructive_payload: Dict[str, Any] = {}
+    if clear_all or "destructive" in normalized_keys:
+        destructive_payload = {key: "clear" for key in destructive_clear_keys}
+    else:
+        for key, label in destructive_clear_keys.items():
+            if key in normalized_keys or label in normalized_keys:
+                destructive_payload[key] = "clear"
+    if destructive_payload:
+        result["destructive"] = _setup_set_destructive_defaults(destructive_payload, dry_run)
+        if result["destructive"].get("error"):
+            return result["destructive"]
+        result["cleared"].extend(destructive_clear_keys[key] for key in destructive_payload)
+
     if clear_all or normalized_keys & {"updates", "updates.mode", "update_mode", "mcp_update_policy"}:
         result["updates"] = _setup_set_updates_defaults({"mode": "prompt"}, dry_run)
         if result["updates"].get("error"):
@@ -15993,12 +16112,13 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     Actions:
       schema() -> {defaults, actions}
       get_defaults() -> {defaults}
-      set_defaults(defaults?|media_analysis?|updates?|dry_run?) -> {defaults, changes}
+      set_defaults(defaults?|media_analysis?|updates?|destructive?|dry_run?) -> {defaults, changes}
       clear_defaults(keys?, dry_run?) -> {defaults, cleared}
 
     Current defaults:
       media_analysis.*: analysis, metadata, marker, reporting, and workflow defaults
       updates.*: MCP update policy, interval, and snooze defaults
+      destructive.*: confirm-token, safe-mode, and audit-log defaults
     """
     p = _params(params)
     if action in {"schema", "capabilities", "options"}:
@@ -16069,6 +16189,26 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                     "current": _get_envelope_mode(),
                     "storage": _server_preferences_path(),
                 },
+                "destructive.require_confirm_token": {
+                    "description": "Require one-time confirmation tokens for registered high-risk destructive actions.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.safe_mode": {
+                    "description": "When enabled, safe mode blocks high/dangerous destructive actions unless allow_risky_operation=true is passed.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.audit_log": {
+                    "description": "Write JSONL security audit records for destructive operations.",
+                    "values": [True, False],
+                    "storage": _media_analysis_preferences_path(),
+                },
+                "destructive.audit_log_path": {
+                    "description": "Absolute path for the JSONL security audit log.",
+                    "values": "absolute or expandable path",
+                    "storage": _media_analysis_preferences_path(),
+                },
             },
         }
 
@@ -16097,6 +16237,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 for key, value in merged.items()
                 if key not in {"updates", "mcp_updates", "mcpUpdates", "dry_run", "dryRun"}
                 and key not in _general_keys
+                and key != "destructive"
             },
             **({
                 "timed_markers_default": _first_param(
@@ -16146,6 +16287,43 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 )
             } if any(key in merged for key in ("snooze_hours", "snoozeHours", "update_snooze_hours", "updateSnoozeHours")) else {}),
         }
+        destructive_defaults = {
+            **_setup_nested(merged, "destructive"),
+            **({
+                "require_confirm_token": _first_param(
+                    merged,
+                    "require_confirm_token",
+                    "requireConfirmToken",
+                    "confirm_token",
+                    "confirmToken",
+                    default=None,
+                )
+            } if any(key in merged for key in ("require_confirm_token", "requireConfirmToken", "confirm_token", "confirmToken")) else {}),
+            **({
+                "safe_mode": _first_param(
+                    merged,
+                    "safe_mode",
+                    "safeMode",
+                    default=None,
+                )
+            } if any(key in merged for key in ("safe_mode", "safeMode")) else {}),
+            **({
+                "audit_log": _first_param(
+                    merged,
+                    "audit_log",
+                    "auditLog",
+                    default=None,
+                )
+            } if any(key in merged for key in ("audit_log", "auditLog")) else {}),
+            **({
+                "audit_log_path": _first_param(
+                    merged,
+                    "audit_log_path",
+                    "auditLogPath",
+                    default=None,
+                )
+            } if any(key in merged for key in ("audit_log_path", "auditLogPath")) else {}),
+        }
 
         general_result = _setup_set_general_defaults(general_defaults, dry_run)
         if general_result.get("error"):
@@ -16156,9 +16334,16 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
         update_result = _setup_set_updates_defaults(update_defaults, dry_run)
         if update_result.get("error"):
             return update_result
-        recognized = (bool(general_result.get("recognized"))
-                      or bool(media_result.get("recognized"))
-                      or bool(update_result.get("recognized")))
+        destructive_result = _setup_set_destructive_defaults(destructive_defaults, dry_run)
+        if destructive_result.get("error"):
+            return destructive_result
+        recognized = (
+            bool(general_result.get("recognized"))
+            or
+            bool(media_result.get("recognized"))
+            or bool(update_result.get("recognized"))
+            or bool(destructive_result.get("recognized"))
+        )
         if not recognized:
             return _err("set_defaults did not receive a recognized default to set")
 
@@ -16168,6 +16353,7 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 "general": general_result,
                 "media_analysis": media_result,
                 "updates": update_result,
+                "destructive": destructive_result,
             },
             defaults=_setup_defaults_snapshot(),
         )

package/src/utils/destructive_hook.py

@@ -25,14 +25,26 @@ every tool that owns destructive actions is decorated.
 from __future__ import annotations
 
 import functools
+import json
 import logging
+import os
+import time
+import uuid
 from typing import Any, Callable, Dict, FrozenSet, Optional, Tuple
 
 from src.utils import analysis_runs, brain_edits, media_pool_changes, timeline_versioning
+from src.utils.execution_lifecycle import RiskAssessment, RiskLevel, classify_operation_risk
 
 logger = logging.getLogger("resolve-mcp.destructive-hook")
 
 
+#: Risk levels safe mode refuses. Names come from `RiskLevel`; a second
+#: vocabulary here would let the gate and the reported level disagree.
+SAFE_MODE_BLOCKED_RISK_LEVELS: FrozenSet[str] = frozenset({
+    RiskLevel.HIGH.value, RiskLevel.CRITICAL.value,
+})
+
+
 # ── Destructive action registry ──────────────────────────────────────────────
 #
 # Tool name → frozenset of action strings that mutate the working timeline (or
@@ -300,6 +312,26 @@ def is_strict_required(tool_name: str, action: str, params: Optional[Dict[str, A
     return False
 
 
+def assess_action_risk(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None,
+) -> RiskAssessment:
+    """Classify a call for the safe-operations policy.
+
+    Classification lives in `execution_lifecycle`, which the pre-flight
+    inspection surface already uses. Deriving it a second time here would let
+    `inspect_operation` and the safe-mode gate disagree about the same call —
+    the gate blocking what inspection called reversible, or the reverse.
+    """
+    return classify_operation_risk(tool_name, action, params or {})
+
+
+def risk_level_for_action(
+    tool_name: str, action: str, params: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Return the security risk level for a call, as a `RiskLevel` value."""
+    return assess_action_risk(tool_name, action, params).level.value
+
+
 # ── Provider hooks ───────────────────────────────────────────────────────────
 
 _ProjectRootProvider = Callable[[], Optional[Tuple[Any, Any, str, Optional[str]]]]
@@ -360,6 +392,163 @@ def _read_preference(key: str, default: Any = None) -> Any:
     return default if value is None else value
 
 
+def _coerce_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "off"}:
+            return False
+        return default
+    return bool(value)
+
+
+def _safe_mode_enabled() -> bool:
+    return _coerce_bool(_read_preference("destructive.safe_mode", False), False)
+
+
+def _audit_enabled() -> bool:
+    return _coerce_bool(_read_preference("destructive.audit_log", True), True)
+
+
+def _audit_log_path() -> str:
+    configured = _read_preference("destructive.audit_log_path", None)
+    if configured:
+        return os.path.expanduser(str(configured))
+    project_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    return os.path.join(project_dir, "logs", "security-audit.jsonl")
+
+
+def _safe_params_for_audit(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    if not isinstance(params, dict):
+        return None
+    redacted = dict(params)
+    for key in ("confirm_token", "confirmToken"):
+        if key in redacted:
+            redacted[key] = "<redacted>"
+    return redacted
+
+
+def _audit_security_event(
+    *,
+    operation_id: str,
+    tool_name: str,
+    action: str,
+    risk_level: str,
+    status: str,
+    params: Optional[Dict[str, Any]],
+    recognised: bool = True,
+    reason: Optional[str] = None,
+    project_root: Optional[str] = None,
+    analysis_run_id: Optional[str] = None,
+) -> None:
+    if not _audit_enabled():
+        return
+    event = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "operation_id": operation_id,
+        "tool": tool_name,
+        "action": action,
+        "risk_level": risk_level,
+        "risk_established": recognised,
+        "status": status,
+        "reason": reason,
+        "analysis_run_id": analysis_run_id,
+        "project_root": project_root,
+        "params": _safe_params_for_audit(params),
+    }
+    path = _audit_log_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, sort_keys=True, default=str) + "\n")
+    except Exception as exc:
+        logger.warning("security audit log write failed: %s", exc)
+
+
+def _security_block_response(
+    *,
+    operation_id: str,
+    tool_name: str,
+    action: str,
+    risk_level: str,
+    recognised: bool = True,
+) -> Dict[str, Any]:
+    return {
+        "success": False,
+        "status": "blocked_by_security_policy",
+        "operation_id": operation_id,
+        "security": {
+            "risk_level": risk_level,
+            "risk_established": recognised,
+            "safe_mode": True,
+            "blocked": True,
+            "policy": "destructive.safe_mode",
+        },
+        "error": {
+            "message": (
+                f"Safe mode blocked {risk_level}-risk action "
+                f"'{tool_name}.{action}'. "
+                "Re-call with params.allow_risky_operation=true, or disable "
+                "destructive.safe_mode in setup defaults."
+            ),
+            "code": "SAFE_MODE_BLOCKED",
+            "category": "destructive_blocked",
+            "retryable": False,
+            "remediation": (
+                "Pass allow_risky_operation=true for this call after review, or "
+                "set destructive.safe_mode=false if this session should allow "
+                "high-risk destructive actions."
+            ),
+        },
+    }
+
+
+def _annotate_security(
+    result: Any,
+    *,
+    operation_id: str,
+    risk_level: str,
+    blocked: bool = False,
+    recognised: bool = True,
+) -> Any:
+    if isinstance(result, dict):
+        result.setdefault("operation_id", operation_id)
+        result.setdefault("security", {
+            "risk_level": risk_level,
+            "risk_established": recognised,
+            "safe_mode": _safe_mode_enabled(),
+            "blocked": blocked,
+        })
+    return result
+
+
+def _safe_mode_allows(
+    risk_level: str,
+    params: Optional[Dict[str, Any]],
+    recognised: bool = True,
+) -> bool:
+    """Whether safe mode lets this call through.
+
+    Only an established HIGH or CRITICAL is blocked. Failing closed on
+    `recognised=False` was measured and rejected: 80 of the 108 registered
+    destructive actions match no risk rule today, `timeline.add_track` and
+    `timeline.duplicate` among them, so it would block three quarters of all
+    edits and teach users to leave safe mode off — weaker in practice than a
+    narrow gate they keep on. The unclassified actions are reported via
+    `risk_established` instead, and want classifying rather than blanket-gating.
+    """
+    if not _safe_mode_enabled():
+        return True
+    if risk_level not in SAFE_MODE_BLOCKED_RISK_LEVELS:
+        return True
+    if isinstance(params, dict) and params.get("allow_risky_operation") is True:
+        return True
+    return False
+
+
 def _resolve_versioning_context() -> Optional[Tuple[Any, Any, str, Optional[str]]]:
     if _PROVIDER is None:
         return None
@@ -441,6 +630,29 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
             if not is_destructive(tool_name, action, params):
                 return fn(action, params, *args, **kwargs)
 
+            operation_id = f"op_{uuid.uuid4().hex[:12]}"
+            assessment = assess_action_risk(tool_name, action, params)
+            risk_level = assessment.level.value
+            risk_recognised = assessment.recognised
+            if not _safe_mode_allows(risk_level, params, risk_recognised):
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="blocked",
+                    params=params,
+                    reason="safe_mode",
+                    recognised=risk_recognised,
+                )
+                return _security_block_response(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
+
             # F4 — token-issuance calls don't mutate; skip the archive entirely
             # so that token preview/cancel paths don't litter the version chain.
             # The wrapper still annotates `_versioning` on the result so callers
@@ -453,30 +665,76 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                     will_gate = False
                 if will_gate:
                     result = fn(action, params, *args, **kwargs)
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="pending_confirmation",
+                        params=params,
+                        reason="confirm_token_required",
+                        recognised=risk_recognised,
+                    )
                     if isinstance(result, dict):
                         result.setdefault("_versioning", {
                             "analysis_run_id": None,
                             "archived": False,
                             "skipped_reason": "pending_confirm_token",
                         })
-                    return result
+                    return _annotate_security(
+                        result,
+                        operation_id=operation_id,
+                        risk_level=risk_level,
+                        recognised=risk_recognised,
+                    )
 
             strict = is_strict_required(tool_name, action, params)
 
             ctx = _resolve_versioning_context()
             if ctx is None:
                 if strict:
-                    return {
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="blocked",
+                        params=params,
+                        reason="strict_missing_version_context",
+                        recognised=risk_recognised,
+                    )
+                    return _annotate_security({
                         "success": False,
                         "error": (
                             f"strict mode: '{tool_name}.{action}' refuses to run because the "
                             "version-on-mutate context (project_root) couldn't be resolved. "
                             "Open a project in Resolve, or pass strict=false to override."
                         ),
-                    }
+                    },
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    blocked=True,
+                    recognised=risk_recognised,
+                )
                 # No Resolve / no project — let the underlying handler run; it
                 # will either succeed (e.g. in dry-run) or surface its own error.
-                return fn(action, params, *args, **kwargs)
+                result = fn(action, params, *args, **kwargs)
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="allowed",
+                    params=params,
+                    reason="no_version_context",
+                    recognised=risk_recognised,
+                )
+                return _annotate_security(
+                    result,
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
 
             resolve_h, project_h, project_root, project_name = ctx
             run_id = _extract_analysis_run_id(params, project_root=project_root)
@@ -488,6 +746,17 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
             # wrapper only handles the timeline path.
             if tool_name == "media_pool":
                 result = fn(action, params, *args, **kwargs)
+                _audit_security_event(
+                    operation_id=operation_id,
+                    tool_name=tool_name,
+                    action=action,
+                    risk_level=risk_level,
+                    status="allowed",
+                    params=params,
+                    project_root=project_root,
+                    analysis_run_id=run_id,
+                    recognised=risk_recognised,
+                )
                 try:
                     media_pool_changes.log_media_pool_change(
                         project_root=project_root,
@@ -505,7 +774,12 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                         "category": "media_pool",
                         "initiator": initiator,
                     })
-                return result
+                return _annotate_security(
+                    result,
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    recognised=risk_recognised,
+                )
 
             before_value: Optional[float] = None
             timeline_before_name: Optional[str] = None
@@ -555,7 +829,19 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                 if archive_exc is not None or (
                     not archive_result.get("archived") and not skipped_ok
                 ):
-                    return {
+                    _audit_security_event(
+                        operation_id=operation_id,
+                        tool_name=tool_name,
+                        action=action,
+                        risk_level=risk_level,
+                        status="blocked",
+                        params=params,
+                        reason="strict_archive_failed",
+                        project_root=project_root,
+                        analysis_run_id=run_id,
+                        recognised=risk_recognised,
+                    )
+                    return _annotate_security({
                         "success": False,
                         "error": (
                             f"strict mode: refused '{tool_name}.{action}' because the "
@@ -568,10 +854,26 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                             "archived": False,
                             "strict_block": True,
                         },
-                    }
+                    },
+                    operation_id=operation_id,
+                    risk_level=risk_level,
+                    blocked=True,
+                    recognised=risk_recognised,
+                )
 
             # Run the underlying handler regardless of hook outcome.
             result = fn(action, params, *args, **kwargs)
+            _audit_security_event(
+                operation_id=operation_id,
+                tool_name=tool_name,
+                action=action,
+                risk_level=risk_level,
+                status="allowed",
+                params=params,
+                project_root=project_root,
+                analysis_run_id=run_id,
+                recognised=risk_recognised,
+            )
 
             after_value: Optional[float] = None
             timeline_after_name: Optional[str] = timeline_before_name
@@ -617,7 +919,12 @@ def destructive_op(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..
                     "before_value": before_value,
                     "after_value": after_value,
                 })
-            return result
+            return _annotate_security(
+                result,
+                operation_id=operation_id,
+                risk_level=risk_level,
+                recognised=risk_recognised,
+            )
 
         wrapper.__wrapped_tool_name__ = tool_name  # type: ignore[attr-defined]
         wrapper.__is_destructive_wrapped__ = True  # type: ignore[attr-defined]

package/src/utils/execution_lifecycle.py

@@ -29,7 +29,7 @@ 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
+    LOW = "low"            # Read-only queries, info probes, and known-reversible edits
     MEDIUM = "medium"      # Reversible edits, markers, non-destructive properties
     HIGH = "high"          # Deletions, ripples, timeline restructuring, batch edits
     CRITICAL = "critical"  # Project deletion, database resets, permanent loss
@@ -139,6 +139,26 @@ class RiskClassificationHook(LifecycleHook):
         ("edit_engine", "auto_cut_silence"),
         ("edit_engine", "ripple_trim"),
         ("project_manager", "save_project_as"),
+        ("media_pool", "delete_folders"),
+        ("timeline", "delete_track"),
+        ("timeline", "lift_range"),
+        ("timeline", "overwrite_range"),
+        ("timeline", "apply_cuts"),
+        ("graph", "reset_all_grades"),
+    }
+
+    #: Mutating, but bounded and trivially reversible — a marker or a clip
+    #: colour. Without this table the name heuristic files them under MEDIUM
+    #: and flags them unrecognised, i.e. it warns that the risk is unestablished
+    #: for the actions whose risk is the best established of any we dispatch.
+    _LOW_RISK_ACTIONS: Set[Tuple[str, str]] = {
+        ("timeline_markers", "add"),
+        ("timeline_markers", "update_custom_data"),
+        ("timeline_item_markers", "add"),
+        ("timeline_item_markers", "add_flag"),
+        ("timeline_item_markers", "clear_flags"),
+        ("timeline_item_markers", "set_clip_color"),
+        ("timeline_item_markers", "clear_clip_color"),
     }
 
     _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
@@ -170,6 +190,11 @@ class RiskClassificationHook(LifecycleHook):
                 radius = BlastRadius.ITEM
             conf_required = True
             reasons.append(f"Destructive timeline edit: {action}")
+        elif pair in cls._LOW_RISK_ACTIONS:
+            level = RiskLevel.LOW
+            destructive = True
+            radius = BlastRadius.ITEM
+            reasons.append(f"Bounded reversible 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