davinci-resolve-mcp 4.7.11 → 4.8.1

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 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 v4.8.1 — text modifiers (Follower) attach to TextPlus inputs
+
+### Added
+
+- **`fusion_comp add_modifier(tool_name, input_name, modifier)`** — attach any modifier
+  to a Fusion input and get back the tool Fusion created for it
+  (`modifier_tool`, `modifier_type`), so a TEXT modifier can then be driven with
+  `set_input` / `add_keyframe` on that tool. ([#250](https://github.com/samuelgursky/davinci-resolve-mcp/issues/250), reported by @artpavelalex-ux — the first report filed through this server's own `report_issue` action)
+  The reporter wanted a Follower on a TextPlus `StyledText` for per-character
+  typewriter animation, and `add_keyframe(modifier="Follower")` failed with
+  `FUSION_ADD_MODIFIER_FAILED` because Fusion rejects the attach. **Measured on
+  Studio 19.1.3.7:** `Tool.AddModifier` wants the modifier's REGISTRY ID, not its
+  display name — `AddModifier("StyledText", "Follower")` and `"TextFollower"` return
+  False and attach nothing; `"StyledTextFollower"` returns True, creates a `Follower1`
+  tool of that ID and connects it to the input. The mapping now lives in
+  `_FUSION_MODIFIER_IDS` and both `add_modifier` and `add_keyframe`'s `modifier`
+  parameter use it, so `Follower` works as written. Attachment is verified by
+  readback (the input's connected output), never by AddModifier's bool, which is
+  unreliable through the Lua bridge. An input that already has a modifier is refused
+  with `FUSION_INPUT_ALREADY_CONNECTED` and the existing tool named; a modifier
+  Fusion rejects is reported with the registry-ID remediation rather than claimed.
+  - Rated a LOW bounded reversible edit and registered in the destructive hook, so it
+    gets safe-mode, an audit row, and the timeline archive copy before the edit like
+    every other compound write; `add_keyframe` itself stays on the ratchet backlog.
+  - New `api_truth` entry `Tool.AddModifier` (`verified_on` 19.1.3.7) mapped through
+    `ACTION_SYMBOLS`, so `add_modifier` results carry the fact as a `known_limitation`.
+  - **Live-validated on landing through the real action** on a disposable timeline:
+    `add_modifier(Follower)` → `Follower1` / `StyledTextFollower`; `set_input(Delay=5)`
+    on the returned tool read back `5.0`; a second attach → `FUSION_INPUT_ALREADY_CONNECTED`
+    naming `Follower1`; a bogus modifier → `FUSION_ADD_MODIFIER_FAILED`. Unit tests in
+    `tests/test_fusion_add_modifier.py` against fakes that accept only the registry ID.
+  - Not measured: other text modifiers (the mapping table holds only the Follower),
+    builds other than 19.1.3.7, and whether the per-character transforms the reporter
+    wants animate as expected once driven — that is theirs to confirm.
+
+## What's New in v4.8.0 — one read before planning: `project_manager snapshot`
+
+### Added
+
+- **`project_manager(action="snapshot")`** — a read-only readout of the state an agent
+  inspects before it plans an edit. ([#251](https://github.com/samuelgursky/davinci-resolve-mcp/pull/251), @tpellet)
+  Returns `project`, `timeline` (per-track items), `gaps_overlaps`, `render`
+  (`is_rendering` plus each job's status) and `media_pool` counts in one call, instead
+  of `get_current` + `timeline.get_current` + `probe_timeline_structure` +
+  `detect_gaps_overlaps` + `render.is_rendering` one LLM turn at a time. The
+  motivation is measured: in 8,407 mined agent tool turns from one real project,
+  2,222 were state inspection. It composes the existing helpers, so the values match
+  what those actions already return, and it never switches page, timeline or folder.
+  - `include` picks sections; an unknown name or an empty list is refused rather than
+    widened to everything. `item_limit` (default 200) caps the items returned across
+    tracks and sets `timeline.items_truncated`, while `item_count` and
+    `gaps_overlaps` still cover the whole timeline. A failing section reports
+    `{error}` in its own place; the others still return.
+  - It saves turns and response size, not read time: the timeline sections cost what
+    `probe_timeline_structure` costs and `media_pool` walks every pool clip, so on a
+    large project pass `include` with only the sections you need. `docs/SKILL.md` says
+    so.
+  - Tested against stubs only (16 tests, including parity with the actions it replaces
+    and a sixty-item readout kept under 16 KB); not yet run against a live Resolve.
+
+### Fixed
+
+- **The risk classifier now recognises `project_manager.snapshot` as a LOW read.** Its
+  name carries no read verb, so on the contributed branch it fell to the name-based
+  MEDIUM default with a "risk unestablished" reason on every call — noise on the one
+  read an agent makes before planning. Safe mode would not have blocked it (only an
+  established HIGH/CRITICAL is), but a pure read should not carry that. Explicit
+  verbless reads now live in `RiskClassificationHook._READ_ONLY_PAIRS` beside
+  `dctl.validate_native`; guard test `tests/test_snapshot_read_rule.py` also pins that
+  the table does not widen into a wildcard.
+
 ## What's New in v4.7.11 — `allow_partial_item_delete="false"` no longer lets a range delete take whole clips
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.7.11-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.8.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-37%20(389%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -821,6 +821,19 @@ Key actions: `list`, `list_attributes`, `get_current`,
 `notes`, and `liveCollaborationMode` per project in the current folder without
 loading any of them.
 
+`snapshot(include?, track_types?, item_limit?)` is the one read to make before
+planning: `project`, `timeline` (per-track items), `gaps_overlaps`, `render`
+(`is_rendering` plus each job's status) and `media_pool` counts in a single
+read-only call, instead of `get_current` + `timeline.get_current` +
+`probe_timeline_structure` + `detect_gaps_overlaps` + `render.is_rendering` one
+turn at a time. `include` picks sections, `item_limit` (default 200) caps the
+items returned and sets `timeline.items_truncated`, and a section that fails
+reports `{error}` in its own place. It saves turns and response size, not read
+time: the timeline sections cost what `probe_timeline_structure` costs and
+`media_pool` walks every pool clip, so on a large project pass `include` with
+only the sections you need. Frame fields are `probe_timeline_structure`'s,
+unchanged.
+
 Project / Database / Archive kernel actions (v2.15.0+) add guarded project
 lifecycle, settings, database, preset, and archive boundary helpers:
 
@@ -2025,7 +2038,13 @@ Key actions:
   `get_input(tool_name, input_name, time?)`
 - `get_inputs(tool_name)` / `get_outputs(tool_name)`
 - `set_attrs(tool_name, attrs)` / `get_attrs(tool_name)`
-- `add_keyframe(tool_name, input_name, time, value)`
+- `add_keyframe(tool_name, input_name, time, value, modifier?)` — attaches a
+  BezierSpline (or `modifier`, e.g. `Path` for Point inputs) on first use
+- `add_modifier(tool_name, input_name, modifier)` → `{modifier_tool, modifier_type}`
+  — attach any modifier and get back the tool Fusion created, so a text modifier
+  (`Follower` on a TextPlus `StyledText`) can be driven with `set_input` /
+  `add_keyframe` on that tool (e.g. `Delay`). Fusion wants the registry ID
+  (`StyledTextFollower`, measured on Studio 19.1.3.7); `Follower` is mapped for you
 - `get_position(tool_name)` / `set_position(tool_name, x, y)` — read/write a node's
   position on the FlowView canvas; `set_position` returns a position read-back
 - `copy_tool(tool_name, name?, x?, y?)` — duplicate a node (settings copied via a

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **124**
+- write-style action occurrences scanned: **125**
 - write-style action occurrences with a matching read: **76**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
@@ -13,6 +13,6 @@
 - `set_keyframe_interpolation`
 - `set_node_enabled`
 
-## Low-signal (create/add/insert/apply/import — usually expected): 43 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 44 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_modifier`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.7.11"
+VERSION = "4.8.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": "4.7.11",
+  "version": "4.8.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.7.11"
+VERSION = "4.8.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 377-tool granular server instead
 """
 
-VERSION = "4.7.11"
+VERSION = "4.8.1"
 
 import base64
 import os
@@ -19077,6 +19077,124 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
     return _ok(**_project_lint.lint_report(state))
 
 
+_SNAPSHOT_SECTIONS = ["project", "timeline", "gaps_overlaps", "render", "media_pool"]
+
+# The per-item fields a planning read needs. probe_timeline_structure carries
+# the rest (file path, media status, seconds, clip properties) for a caller
+# that wants them; repeating them here is what makes a 60-item readout too big
+# to be the first call of every turn.
+_SNAPSHOT_ITEM_FIELDS = (
+    "item_index", "timeline_item_id", "name", "start", "end",
+    "source_start", "source_end", "source_fps", "media_pool_item_id",
+)
+
+
+def _project_state_snapshot(r, proj, p: Dict[str, Any]) -> Dict[str, Any]:
+    """One read-only readout of the state an agent inspects before planning.
+
+    Composes the helpers behind project_summary, probe_timeline_structure,
+    detect_gaps_overlaps and the render status actions, so the numbers match
+    what those actions return. Each section fails on its own: an exception is
+    reported as that section's {"error"}, never as a whole-call failure.
+    """
+    include = p.get("include")
+    if include is None:
+        include = list(_SNAPSHOT_SECTIONS)
+    # An empty include is refused: falling back to every section would hand a
+    # caller that filtered down to nothing the most expensive read instead.
+    if not isinstance(include, list) or not include:
+        return _err("include must be a non-empty list", category="invalid_input")
+    unknown = [name for name in include if name not in _SNAPSHOT_SECTIONS]
+    if unknown:
+        return _err(
+            f"Unknown snapshot section(s): {unknown}",
+            code="UNKNOWN_SECTION", category="invalid_input",
+            state={"unknown": unknown, "supported": list(_SNAPSHOT_SECTIONS)},
+        )
+    track_types = p.get("track_types")
+    if track_types is not None and not isinstance(track_types, list):
+        return _err("track_types must be a list", category="invalid_input")
+    try:
+        item_limit = int(p.get("item_limit", 200))
+    except (TypeError, ValueError):
+        return _err("item_limit must be an integer", category="invalid_input")
+    if item_limit < 0:
+        return _err("item_limit must be 0 or greater", category="invalid_input")
+
+    out: Dict[str, Any] = {}
+
+    if "project" in include:
+        try:
+            section = _project_object_summary(proj) or {}
+            section["current_page"] = r.GetCurrentPage()
+            section["timeline_count"] = proj.GetTimelineCount()
+            section["settings"] = {
+                key: _ser(proj.GetSetting(key))
+                for key in ("timelineFrameRate", "timelineResolutionWidth", "timelineResolutionHeight")
+            }
+            out["project"] = section
+        except Exception as exc:
+            out["project"] = {"error": str(exc)}
+
+    if "timeline" in include or "gaps_overlaps" in include:
+        wanted = [name for name in ("timeline", "gaps_overlaps") if name in include]
+        try:
+            tl = proj.GetCurrentTimeline()
+            if not tl:
+                for name in wanted:
+                    out[name] = {"available": False, "error": "No current timeline"}
+            else:
+                snapshot = _timeline_conform_snapshot(
+                    tl, {"track_types": track_types, "include_markers": False})
+                # Gaps are measured on the whole snapshot, before item_limit
+                # trims what is returned.
+                gaps_overlaps = _detect_gaps_overlaps_from_snapshot(
+                    snapshot, {"track_types": track_types})
+                if "timeline" in include:
+                    snapshot.pop("markers", None)
+                    try:
+                        snapshot["fps"] = float(tl.GetSetting("timelineFrameRate"))
+                    except Exception:
+                        snapshot["fps"] = None
+                    remaining = item_limit
+                    for type_payload in snapshot["tracks"].values():
+                        for track in type_payload["tracks"]:
+                            kept = track["items"][:remaining]
+                            remaining -= len(kept)
+                            track["items"] = [
+                                {field: item.get(field) for field in _SNAPSHOT_ITEM_FIELDS}
+                                for item in kept
+                            ]
+                    snapshot["items_returned"] = item_limit - remaining
+                    snapshot["items_truncated"] = snapshot["items_returned"] < snapshot["item_count"]
+                    out["timeline"] = snapshot
+                if "gaps_overlaps" in include:
+                    out["gaps_overlaps"] = gaps_overlaps
+        except Exception as exc:
+            for name in wanted:
+                out.setdefault(name, {"error": str(exc)})
+
+    if "render" in include:
+        try:
+            jobs = []
+            for job in (proj.GetRenderJobList() or []):
+                row = _ser(job)
+                if isinstance(row, dict) and row.get("JobId"):
+                    row["status"] = _ser(proj.GetRenderJobStatus(row["JobId"]))
+                jobs.append(row)
+            out["render"] = {"is_rendering": bool(proj.IsRenderingInProgress()), "jobs": jobs}
+        except Exception as exc:
+            out["render"] = {"error": str(exc)}
+
+    if "media_pool" in include:
+        try:
+            out["media_pool"] = _project_summary(proj)["media_pool"]
+        except Exception as exc:
+            out["media_pool"] = {"error": str(exc)}
+
+    return out
+
+
 @mcp.tool()
 @_guard_missing_params
 @_destructive_op("project_manager")
@@ -19089,6 +19207,19 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Resolve 21.0.4+. Per-project attributes for the current folder without
           loading any project.
       get_current() -> {name, id}
+      snapshot(include?, track_types?, item_limit?) -> {project, timeline, gaps_overlaps, render, media_pool}
+        One read-only readout of what an agent inspects before planning; it never
+        switches page, timeline or folder. include picks sections (default all);
+        item_limit caps the items returned across tracks (default 200) and sets
+        timeline.items_truncated, while item_count and gaps_overlaps still cover
+        the whole timeline. item_limit bounds the response, not the read: the
+        timeline sections cost what probe_timeline_structure costs (they scale
+        with item_count) and media_pool walks every pool clip, so on a large
+        project leave out the sections you do not need. A section that fails
+        reports {error} in its own place; an empty include is refused. Frame
+        fields are probe_timeline_structure's, unchanged: start/end
+        are TimelineItem GetStart/GetEnd record frames; source_start/source_end
+        are file-relative frames at source_fps, source_end exclusive.
       create(name, media_location_path?) -> {success, name}
       load(name) -> {success}
       save() -> {success}
@@ -19181,6 +19312,11 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_current":
         proj = pm.GetCurrentProject()
         return {"name": proj.GetName(), "id": proj.GetUniqueId()} if proj else _err("No project open")
+    elif action == "snapshot":
+        proj = pm.GetCurrentProject()
+        if not proj:
+            return _err("No project open")
+        return _project_state_snapshot(r, proj, p)
     elif action == "create":
         if not p.get("name"):
             return _err("create requires name")
@@ -19280,7 +19416,7 @@ def project_manager(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if not p.get("path"):
             return _err("restore requires path")
         return {"success": bool(pm.RestoreProject(p["path"], p.get("name")))}
-    return _unknown(action, ["list","list_attributes","get_current","create","load","save","close","delete","import_project","export_project","archive","restore","lint","diff_to_spec","plan_spec","apply_spec", *_PROJECT_KERNEL_ACTIONS])
+    return _unknown(action, ["list","list_attributes","get_current","snapshot","create","load","save","close","delete","import_project","export_project","archive","restore","lint","diff_to_spec","plan_spec","apply_spec", *_PROJECT_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -30276,6 +30412,25 @@ def _fusion_keyframe_frames(inp) -> List[float]:
     return sorted(float(frame) for frame in kfs.values())
 
 
+#: Modifier names callers use -> the registry ID `Tool.AddModifier` wants.
+#: Measured on Studio 19.1.3.7 (issue #250) on a TextPlus StyledText input:
+#: AddModifier("StyledText", "Follower") and "TextFollower" return False and
+#: attach nothing; "StyledTextFollower" returns True, creates a `Follower1` tool
+#: of that ID and connects it to the input. Spline modifiers already go by their
+#: registry ID (BezierSpline, Path). Keys are compared case-insensitively.
+_FUSION_MODIFIER_IDS = {
+    "follower": "StyledTextFollower",
+    "textfollower": "StyledTextFollower",
+    "styledtextfollower": "StyledTextFollower",
+}
+
+
+def _fusion_modifier_id(name: Any) -> str:
+    """The registry ID for a modifier a caller named; unknown names pass through."""
+    text = str(name or "").strip()
+    return _FUSION_MODIFIER_IDS.get(text.lower(), text)
+
+
 def _fusion_input_spline(inp):
     """The modifier/spline tool driving `inp`, or None when it is not animated.
 
@@ -30429,7 +30584,17 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       get_input(tool_name, input_name, time?) -> {value}
       set_attrs(tool_name, attrs) -> {success}
       get_attrs(tool_name) -> {attrs}
-      add_keyframe(tool_name, input_name, time, value) -> {success}
+      add_keyframe(tool_name, input_name, time, value, modifier?) -> {success}
+        Attaches a BezierSpline (or `modifier`, e.g. 'Path' for Point inputs)
+        the first time an input is animated. Modifier names are mapped to
+        their registry ID ('Follower' -> 'StyledTextFollower').
+      add_modifier(tool_name, input_name, modifier) -> {success, modifier_tool, modifier_type}
+        Attach any modifier and return the tool Fusion created for it, so a
+        TEXT modifier (Follower on a TextPlus StyledText) can then be driven
+        with set_input / add_keyframe on that tool (e.g. Delay). Refuses an
+        input that already has a modifier. Measured on Studio 19.1.3.7:
+        Fusion wants the registry ID ('StyledTextFollower'); 'Follower' is
+        mapped for you.
       get_keyframes(tool_name, input_name) -> {keyframes}
       delete_keyframe(tool_name, input_name, time) -> {success, time, remaining_keyframes}
         Deletes on the spline attached to the input. Structured errors when the
@@ -30708,7 +30873,8 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                 # input still has no connected output, the assignment on the next
                 # line would set a STATIC value and _ok() would report a keyframe
                 # that does not exist.
-                tool.AddModifier(p["input_name"], p.get("modifier", "BezierSpline"))
+                _modifier_id = _fusion_modifier_id(p.get("modifier", "BezierSpline"))
+                tool.AddModifier(p["input_name"], _modifier_id)
                 try:
                     attached = tool[p["input_name"]].GetConnectedOutput() is not None
                 except Exception:
@@ -30724,14 +30890,86 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                                "Reporting success here would claim a keyframe that "
                                "does not exist.",
                         remediation="Check the input accepts the modifier type "
-                                    f"({p.get('modifier', 'BezierSpline')!r}); Point "
-                                    "inputs take 'Path'.",
+                                    f"({_modifier_id!r}); Point inputs take 'Path'. "
+                                    "A TEXT modifier (Follower) is not a spline: "
+                                    "attach it with add_modifier, then drive the "
+                                    "modifier tool it returns.",
                     )
             tool[p["input_name"]][p["time"]] = p["value"]
             return _ok()
         finally:
             comp.EndUndo(True)
 
+    elif action == "add_modifier":
+        tool = comp.FindTool(p["tool_name"])
+        if not tool:
+            return _err(f"Tool '{p['tool_name']}' not found")
+        input_name = p.get("input_name")
+        requested = p.get("modifier")
+        if not input_name or not requested:
+            return _err("add_modifier requires input_name and modifier",
+                        category="invalid_input")
+        inp = tool[input_name]
+        if not inp:
+            return _err(f"Input '{input_name}' not found on tool '{p['tool_name']}'")
+        modifier_id = _fusion_modifier_id(requested)
+        try:
+            existing = inp.GetConnectedOutput()
+        except Exception:
+            existing = None
+        if existing is not None:
+            existing_tool = existing.GetTool()
+            attrs = (existing_tool.GetAttrs() or {}) if existing_tool else {}
+            return _err(
+                f"'{p['tool_name']}.{input_name}' already has a modifier attached.",
+                code="FUSION_INPUT_ALREADY_CONNECTED", category="precondition",
+                retryable=False,
+                state={"modifier_tool": attrs.get("TOOLS_Name", ""),
+                       "modifier_type": attrs.get("TOOLS_RegID", "")},
+                remediation="Drive the existing modifier tool, or "
+                            "disconnect(tool_name, input_name) first.",
+            )
+        # Same undo bracket as add_keyframe; no comp.Lock() — a lock is for
+        # value writes and this is a graph edit, but see _FUSION_VALUE_WRITE_NOTE
+        # for why writes under a lock are not trusted here.
+        comp.StartUndo(f"Add modifier {modifier_id} to {input_name}")
+        try:
+            tool.AddModifier(input_name, modifier_id)
+            # AddModifier's bool is unreliable through the Lua bridge (an unknown
+            # attribute resolves to None). The readback is the evidence: the
+            # input must now be connected to a modifier tool.
+            try:
+                out = tool[input_name].GetConnectedOutput()
+            except Exception:
+                out = None
+            modifier_tool = out.GetTool() if out else None
+            if modifier_tool is None:
+                return _err(
+                    f"Could not attach {modifier_id!r} to "
+                    f"'{p['tool_name']}.{input_name}': no modifier is connected "
+                    "after AddModifier.",
+                    code="FUSION_ADD_MODIFIER_FAILED", category="api_error",
+                    retryable=False,
+                    reason="Fusion rejects a modifier whose registry ID it does not "
+                           "know for that input type, and reports it only as False.",
+                    remediation="Pass the modifier's REGISTRY ID, not its display "
+                                "name: the text Follower is 'StyledTextFollower' "
+                                "(add_modifier maps 'Follower' to it; measured on "
+                                "Studio 19.1.3.7). Spline modifiers are "
+                                "'BezierSpline' and, for Point inputs, 'Path'.",
+                )
+            attrs = modifier_tool.GetAttrs() or {}
+            return _ok(
+                tool_name=p["tool_name"], input_name=input_name,
+                requested=requested, modifier_id=modifier_id,
+                modifier_tool=attrs.get("TOOLS_Name", ""),
+                modifier_type=attrs.get("TOOLS_RegID", modifier_id),
+                next="Drive the modifier tool with set_input / add_keyframe "
+                     "(e.g. its Delay input for a per-character stagger).",
+            )
+        finally:
+            comp.EndUndo(True)
+
     elif action == "get_keyframes":
         tool = comp.FindTool(p["tool_name"])
         if not tool:
@@ -30921,7 +31159,7 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "add_tool","delete_tool","get_tool_list","find_tool",
         "connect","disconnect","get_inputs","get_outputs",
         "set_input","get_input","set_attrs","get_attrs",
-        "add_keyframe","get_keyframes","delete_keyframe",
+        "add_keyframe","add_modifier","get_keyframes","delete_keyframe",
         "get_comp_info","set_frame_range","get_frame_range","render",
         "start_undo","end_undo",
         "get_position","set_position","copy_tool","auto_arrange",

package/src/utils/api_truth.py

@@ -3414,6 +3414,32 @@ API_TRUTH: List[Dict[str, Any]] = [
         "mitigation": ["project_manager.archive", "project_manager.safe_project_archive",
                        "archive_project"],
     },
+    {
+        "symbol": "Tool.AddModifier",
+        "object": "Fusion Tool",
+        "signature": "(inputName, modifierRegID) -> bool",
+        "reality": "The second argument is the modifier's REGISTRY ID, not its "
+                   "display name. On a TextPlus StyledText input, "
+                   "AddModifier('StyledText', 'Follower') and 'TextFollower' return "
+                   "False and attach nothing; 'StyledTextFollower' returns True, "
+                   "creates a tool named Follower1 of that ID and connects it to the "
+                   "input. Spline modifiers already go by registry ID (BezierSpline, "
+                   "Path). Through the Lua bridge the bool is not reliable evidence; "
+                   "the input's connected-output readback is.",
+        "recommended": "Pass the registry ID. fusion_comp add_modifier maps 'Follower' "
+                       "to 'StyledTextFollower', verifies by readback and returns the "
+                       "created modifier tool so it can be driven with set_input / "
+                       "add_keyframe (Delay for a per-character stagger).",
+        "tags": ["fusion", "naming", "silent-failure"],
+        "verified_on": "DaVinci Resolve Studio 19.1.3.7",
+        "measured": "2026-09-19 on a disposable timeline: "
+                    "InsertFusionCompositionIntoTimeline, AddTool('TextPlus'), then "
+                    "AddModifier('StyledText', X) for X in Follower / "
+                    "StyledTextFollower / TextFollower, with a GetToolList diff and "
+                    "StyledText.GetConnectedOutput().GetTool() readback after each; "
+                    "only StyledTextFollower attached (new tool Follower1).",
+        "mitigation": ["fusion_comp.add_modifier", "fusion_comp.add_keyframe"],
+    },
 
 ]
 
@@ -3474,6 +3500,7 @@ ACTION_SYMBOLS: Dict[Tuple[str, str], List[str]] = {
     ("timeline_item_color", "safe_export_lut"): ["TimelineItem.ExportLUT"],
     ("timeline", "duplicate"): ["Timeline.DuplicateTimeline"],
     ("project_manager", "archive"): ["ProjectManager.ArchiveProject"],
+    ("fusion_comp", "add_modifier"): ["Tool.AddModifier"],
     ("project_manager", "safe_project_archive"): ["ProjectManager.ArchiveProject"],
 }
 

package/src/utils/destructive_hook.py

@@ -96,7 +96,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
     # them. Plus the 21.0 AI deblur, rated MEDIUM: it creates media, and is
     # registered so it is audited and its dry run is honest.
     "folder": frozenset({"remove_motion_blur"}),
-    "fusion_comp": frozenset({"delete_keyframe", "delete_tool"}),
+    "fusion_comp": frozenset({"add_modifier", "delete_keyframe", "delete_tool"}),
     "gallery_stills": frozenset({"delete_stills"}),
     "media_pool_item": frozenset({"remove_motion_blur"}),
     "media_pool_item_markers": frozenset({

package/src/utils/execution_lifecycle.py

@@ -203,6 +203,9 @@ class RiskClassificationHook(LifecycleHook):
     #: 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]] = {
+        # Attaching a modifier to one Fusion input: one undo step, and
+        # disconnect(tool, input) removes it. (#250)
+        ("fusion_comp", "add_modifier"),
         ("dctl", "encrypt_native"),  # Creates a new file; never replaces existing content.
         ("timeline_markers", "add"),
         ("timeline_markers", "update_custom_data"),
@@ -378,6 +381,14 @@ class RiskClassificationHook(LifecycleHook):
         return BlastRadius.TIMELINE, "the timeline node graph (every clip on the timeline)"
 
     _READ_ONLY_PREFIXES = ("get_", "list_", "query_", "probe_", "inspect_", "export_", "check_")
+    #: Reads whose action name carries no read verb. Without an entry here a
+    #: pure read falls to the name-based MEDIUM default and every call reports
+    #: "risk unestablished" — noise on the one call an agent makes before
+    #: planning (project_manager.snapshot, #251).
+    _READ_ONLY_PAIRS = frozenset({
+        ("dctl", "validate_native"),
+        ("project_manager", "snapshot"),
+    })
 
     @classmethod
     def classify(cls, tool_name: str, action: str, params: Dict[str, Any]) -> RiskAssessment:
@@ -448,7 +459,7 @@ class RiskClassificationHook(LifecycleHook):
                 else BlastRadius.ITEM
             )
             reasons.append(f"Recoverable edit to existing state: {action}")
-        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"} or pair == ("dctl", "validate_native"):
+        elif any(action.startswith(p) for p in cls._READ_ONLY_PREFIXES) or action in {"read", "status", "info"} or pair in cls._READ_ONLY_PAIRS:
             level = RiskLevel.LOW
             destructive = False
             radius = BlastRadius.ITEM