breakpoint-mcp 1.28.0 → 1.72.7

package/dist/tools/editor/filesystem.js

@@ -1,12 +1,19 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** Project FileSystem dock ops: list / scan / move / mkdir. */
-export function registerFilesystemTools(server, call) {
+export function registerFilesystemTools(server, call, guard) {
     server.registerTool("filesystem_list", {
         title: "List project directory",
         description: "List the subdirectories and files of a directory in the project filesystem (hidden entries like .godot are skipped). Read-only.",
         inputSchema: { path: z.string().optional().describe("Directory res:// path (default res://)") },
-    }, async ({ path }) => call("filesystem.list", path !== undefined ? { path } : {}));
+    }, async ({ path }) => {
+        // 🔴 MEASURED: this LISTED the contents of a directory outside the project root and
+        // named the files it found there. An omitted `path` means res:// and stays legal.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("filesystem.list", path !== undefined ? { path } : {});
+    });
     server.registerTool("filesystem_scan", {
         title: "Rescan filesystem",
         description: "Trigger an editor rescan of the project filesystem so newly added or externally-changed files are picked up. Read-only side effect.",
@@ -21,6 +28,13 @@ export function registerFilesystemTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ from_path, to_path, confirm }) => {
+        // 🔴 THE SHARPEST ROW OF THE MEASUREMENT. This is the only writer in the set
+        // that is destructive on BOTH sides: `res://../…` as `to_path` moved a project
+        // file OUT of the project, and as `from_path` it moved a file the project never
+        // owned IN. Both parameters, therefore, and neither is theoretical.
+        const escaped = guard(from_path, "from_path") ?? guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Move ${from_path} to ${to_path}`);
         if (blocked)
             return blocked;
@@ -30,6 +44,12 @@ export function registerFilesystemTools(server, call) {
         title: "Create directory",
         description: "Create a directory (recursively) in the project filesystem, then rescan. No-op if it already exists.",
         inputSchema: { path: z.string().describe("Directory res:// path to create") },
-    }, async ({ path }) => call("filesystem.create_dir", { path }));
+    }, async ({ path }) => {
+        // 🔴 MEASURED: this CREATED directories outside the project root via `res://../`.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("filesystem.create_dir", { path });
+    });
 }
 //# sourceMappingURL=filesystem.js.map

package/dist/tools/editor/introspection.js

@@ -1,5 +1,33 @@
 import { z } from "zod";
 import { fail } from "./common.js";
+/**
+ * Smallest edge, in pixels, a captured editor viewport may have and still be a
+ * frame rather than a placeholder.
+ *
+ * Godot does not tear down the main-screen tab you are not looking at — it
+ * collapses that tab's SubViewport to its minimum size and keeps rendering it.
+ * `get_texture().get_image()` therefore still succeeds, and the capture returns
+ * a real, valid, **2x2** PNG: correct magic bytes, correct mime, an 81-byte
+ * payload, and a note reading "Captured 2d viewport (2x2)". Every layer above
+ * reports success, and an assistant then *looks at* four pixels and reasons
+ * about the scene from them.
+ *
+ * Measured on Godot 4.7 (session 144), four editor boots, real Metal hardware:
+ * with the Script or 3D tab active, `viewport=2d` returned 2x2/81B; with the 2D
+ * tab active it returned 1297x492/3.6KB. A fresh editor with no saved layout —
+ * the CI condition — boots on the **3D** tab, and opening a `Node2D` scene does
+ * not switch it. So the degenerate case is the DEFAULT, not the exception.
+ *
+ * 8px is deliberately far below any real viewport and far above the collapsed
+ * one: it separates the two populations without guessing at a "reasonable" size.
+ *
+ * Since 1.30.0 the refusal is RECOVERABLE rather than terminal: `main_screen_set`
+ * switches the tab, so the error names the tab that is actually active and the
+ * call that fixes it, and a caller can act on that instead of giving up. The
+ * guard itself is unchanged — this threshold still decides what counts as a
+ * frame; the tab tools only give the caller somewhere to go when it bites.
+ */
+const MIN_RENDERED_VIEWPORT_PX = 8;
 /** Editor selection, ClassDB / docs lookups, and viewport screenshot. */
 export function registerIntrospectionTools(server, call, bridge) {
     server.registerTool("selection_get", { title: "Get selection", description: "Return the paths of the nodes currently selected in the editor.", inputSchema: {} }, async () => call("selection.get"));
@@ -8,6 +36,23 @@ export function registerIntrospectionTools(server, call, bridge) {
         description: "Replace the editor's node selection with the given node paths.",
         inputSchema: { paths: z.array(z.string()).describe("Node paths relative to the scene root") },
     }, async ({ paths }) => call("selection.set", { paths }));
+    server.registerTool("main_screen_get", {
+        title: "Get the active main-screen tab",
+        description: "Report which main-screen editor tab is active (2D / 3D / Script / …) and which are available. " +
+            "Read-only. The active tab decides which viewport screenshot_editor can actually capture: Godot " +
+            "collapses the inactive tab's viewport to a few pixels.",
+        inputSchema: {},
+    }, async () => call("main_screen.get"));
+    server.registerTool("main_screen_set", {
+        title: "Switch the main-screen tab",
+        description: "Switch the editor's main-screen tab (2D / 3D / Script / …), matching the name case-insensitively. " +
+            "Use this before screenshot_editor to make the viewport you want to capture the active one — opening " +
+            "a scene does NOT switch the tab. Returns the resulting state, read back from the editor rather than " +
+            "echoed. An unknown name comes back with the live list of available tabs.",
+        inputSchema: {
+            name: z.string().describe('Tab name as the editor reports it, case-insensitive — e.g. "2D", "3D", "Script"'),
+        },
+    }, async ({ name }) => call("main_screen.set", { name }));
     server.registerTool("classdb_get_class", {
         title: "Introspect class",
         description: "Return the parent class, methods, properties, and signals of an engine class via ClassDB.",
@@ -53,11 +98,37 @@ export function registerIntrospectionTools(server, call, bridge) {
     server.registerTool("screenshot_editor", {
         title: "Screenshot editor viewport",
         description: "Capture the 2D or 3D editor viewport as a PNG and return it as image content so the assistant can see the scene. " +
-            "Requires the matching editor tab (2D/3D) to be active and rendered.",
+            "Requires the matching editor tab (2D/3D) to be active: Godot collapses the inactive tab's viewport to a few " +
+            "pixels, and this tool returns a viewport_not_rendered error rather than that placeholder frame. " +
+            "A fresh editor is on the 3D tab and opening a scene does NOT switch it, so to capture 2d reliably call " +
+            'main_screen_set {"name":"2D"} first — or main_screen_get to see which tab is active.',
         inputSchema: { viewport: z.enum(["2d", "3d"]).optional().describe("Which viewport (default 3d)") },
     }, async ({ viewport }) => {
         try {
             const r = (await bridge.request("screenshot.editor_viewport", { viewport: viewport ?? "3d" }));
+            if (r.width < MIN_RENDERED_VIEWPORT_PX || r.height < MIN_RENDERED_VIEWPORT_PX) {
+                // Name the tab that is ACTUALLY active rather than leaving the caller to infer
+                // it from a 2x2. Best-effort: this error must survive an addon too old to answer
+                // (main_screen.* is 1.9.3+), so a failure here degrades the message instead of
+                // replacing a useful "not rendered" error with an unrelated bridge error.
+                let active;
+                try {
+                    const s = (await bridge.request("main_screen.get", {}));
+                    if (s?.active)
+                        active = s.active;
+                }
+                catch { /* older addon, or no main-screen container — fall through */ }
+                return fail({
+                    code: "viewport_not_rendered",
+                    message: `The ${r.viewport} editor viewport measured ${r.width}x${r.height} — a collapsed viewport, not a rendered ` +
+                        `frame. Godot keeps the inactive main-screen tab's viewport alive at its minimum size, so the capture ` +
+                        `"succeeds" and returns a placeholder image. ` +
+                        (active
+                            ? `The editor is on the "${active}" tab. Call main_screen_set {"name":"${r.viewport.toUpperCase()}"} `
+                            : `Switch the editor to the ${r.viewport.toUpperCase()} tab with main_screen_set (opening a scene does NOT switch it) `) +
+                        `and retry — or capture the viewport whose tab is active.`,
+                });
+            }
             return {
                 content: [
                     { type: "image", data: r.base64, mimeType: r.mime },

package/dist/tools/editor/node.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** Scene-tree node authoring: add / delete / reparent / property / group ops. */
-export function registerNodeTools(server, call) {
+export function registerNodeTools(server, call, guard) {
     server.registerTool("node_add", {
         title: "Add node",
         description: "Instance a node of the given class under a parent path (undoable). Returns the new node's path.",
@@ -116,7 +116,12 @@ export function registerNodeTools(server, call) {
             scene_path: z.string().describe("Scene to instance, e.g. res://actors/enemy.tscn"),
             name: z.string().optional().describe("Node name (defaults to the instanced scene's root name)"),
         },
-    }, async ({ parent_path, scene_path, name }) => call("node.instantiate_scene", name !== undefined ? { parent_path, scene_path, name } : { parent_path, scene_path }));
+    }, async ({ parent_path, scene_path, name }) => {
+        const escaped = guard(scene_path, "scene_path");
+        if (escaped)
+            return escaped;
+        return call("node.instantiate_scene", name !== undefined ? { parent_path, scene_path, name } : { parent_path, scene_path });
+    });
     server.registerTool("node_move_child", {
         title: "Move child",
         description: "Reorder a node among its siblings by index (undoable). Negative indices count from the end (-1 = last).",

package/dist/tools/editor/particles.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 /** GPUParticles authoring (process material, amount, lifetime, texture). */
-export function registerParticleTools(server, call) {
+export function registerParticleTools(server, call, guard) {
     server.registerTool("particles_create", {
         title: "Create particles",
         description: "Add a GPUParticles2D/3D node under a parent in the edited scene (undoable). Optional initial amount (> 0), lifetime (> 0), emitting. In-scene and undoable — not gated.",
@@ -91,6 +91,11 @@ export function registerParticleTools(server, call) {
             path: z.string().describe("GPUParticles2D node path relative to the scene root"),
             texture_path: z.string().describe("res:// path to a Texture2D resource"),
         },
-    }, async ({ path, texture_path }) => call("particles.set_texture", { path, texture_path }));
+    }, async ({ path, texture_path }) => {
+        const escaped = guard(texture_path, "texture_path");
+        if (escaped)
+            return escaped;
+        return call("particles.set_texture", { path, texture_path });
+    });
 }
 //# sourceMappingURL=particles.js.map

package/dist/tools/editor/project_input_test.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** InputMap, extended project config (autoloads / export presets / main scene / settings), editor settings, and test-framework detection. */
-export function registerProjectInputTestTools(server, call) {
+export function registerProjectInputTestTools(server, call, guard) {
     server.registerTool("inputmap_add_action", {
         title: "Add input action",
         description: "Define a project input action (ProjectSettings input/<name>) with an empty event list and a deadzone. Set save=true to persist to project.godot. DESTRUCTIVE (project-wide input map) — gated by confirmation.",
@@ -82,6 +82,9 @@ export function registerProjectInputTestTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ name, path, enabled, save, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Add autoload "${name}" -> ${path}${save ? " and save project.godot" : ""}`);
         if (blocked)
             return blocked;
@@ -139,6 +142,9 @@ export function registerProjectInputTestTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, save, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set main scene to ${path}${save ? " and save project.godot" : ""}`);
         if (blocked)
             return blocked;
@@ -182,6 +188,14 @@ export function registerProjectInputTestTools(server, call) {
         inputSchema: {
             dir: z.string().optional().describe("Directory to search (default res://test)"),
         },
-    }, async ({ dir }) => call("test.list", dir !== undefined ? { dir } : {}));
+    }, 
+    // 🔴 MEASURED: `res://../example_evil` returned that directory's `test_*.gd`
+    // files in the reply. A reader's leak is the LISTING, not a file it wrote.
+    async ({ dir }) => {
+        const escaped = guard(dir, "dir");
+        if (escaped)
+            return escaped;
+        return call("test.list", dir !== undefined ? { dir } : {});
+    });
 }
 //# sourceMappingURL=project_input_test.js.map

package/dist/tools/editor/resource.js

@@ -1,7 +1,13 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
-/** Resource (.tres/.res) create / load / save / property / import ops. */
-export function registerResourceTools(server, call) {
+/**
+ * Resource (.tres/.res) create / load / save / property / import ops.
+ *
+ * 🔴 THE GUARD RUNS BEFORE `gate()`, deliberately (163 §3's shape): a call that can
+ * never legally write must not first ask the user to approve writing. It also means
+ * the refusal needs no editor at all, which is what makes the unit tests cheap.
+ */
+export function registerResourceTools(server, call, guard) {
     server.registerTool("resource_create", {
         title: "Create resource",
         description: "Instantiate a Resource subclass and save it as a new file. DESTRUCTIVE (writes a file) — gated by confirmation. Optional initial properties use the tagged-Variant convention.",
@@ -12,6 +18,9 @@ export function registerResourceTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ class_name, to_path, properties, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create ${class_name} resource at ${to_path}`);
         if (blocked)
             return blocked;
@@ -21,7 +30,12 @@ export function registerResourceTools(server, call) {
         title: "Load resource",
         description: "Load a resource file and return its class, resource_name, and inspector-visible property list. Read-only.",
         inputSchema: { path: z.string().describe("Resource res:// path") },
-    }, async ({ path }) => call("resource.load", { path }));
+    }, async ({ path }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("resource.load", { path });
+    });
     server.registerTool("resource_save", {
         title: "Save resource",
         description: "Load a resource and (re-)save it, optionally to a new path and with ResourceSaver flags. DESTRUCTIVE (writes a file) — gated by confirmation. Shares subresources by reference; use resource_duplicate for an independent copy.",
@@ -32,6 +46,13 @@ export function registerResourceTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ from_path, to_path, flags, confirm }) => {
+        // 🔴 BOTH parameters. Measured: `from_path: res://../…` LOADED a resource from
+        // outside the root and saved a copy inside it. Guarding only the destination
+        // would leave this tool half-wired — the failure mode 161, 162 and 163 each
+        // re-learned on a different plane.
+        const escaped = guard(from_path, "from_path") ?? guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Save resource ${from_path}${to_path ? ` to ${to_path}` : ""}`);
         if (blocked)
             return blocked;
@@ -52,6 +73,9 @@ export function registerResourceTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, to_path, deep, confirm }) => {
+        const escaped = guard(path, "path") ?? guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Duplicate resource ${path} to ${to_path}`);
         if (blocked)
             return blocked;
@@ -64,7 +88,12 @@ export function registerResourceTools(server, call) {
             path: z.string().describe("Resource res:// path"),
             property: z.string().describe("Property name"),
         },
-    }, async ({ path, property }) => call("resource.get_property", { path, property }));
+    }, async ({ path, property }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("resource.get_property", { path, property });
+    });
     server.registerTool("resource_set_property", {
         title: "Set resource property",
         description: "Set a single property on a resource file and save it. DESTRUCTIVE (writes a file) — gated by confirmation. The value uses the tagged-Variant convention.",
@@ -75,6 +104,12 @@ export function registerResourceTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, property, value, confirm }) => {
+        // 🔴 MEASURED AGAINST A LIVE 4.7 EDITOR: `res://../example_evil/x.tres` had its
+        // BYTES REWRITTEN outside the project root, and the reply reported `ok`. The
+        // verdict came from the file's hash, not the reply.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set ${property} on ${path}`);
         if (blocked)
             return blocked;
@@ -82,12 +117,17 @@ export function registerResourceTools(server, call) {
     });
     server.registerTool("resource_get_import_settings", {
         title: "Get import settings",
-        description: "Read an asset's import metadata (.import): the importer and its parameters. Read-only. Returns imported=false when the asset has no .import sidecar.",
+        description: "Read an asset's import metadata (.import): the importer and its parameters. Read-only. Returns imported=false when the file exists but has no .import sidecar; errors not_found when the path is not a file (matching resource_load).",
         inputSchema: { path: z.string().describe("Asset res:// path (e.g. res://icon.png)") },
-    }, async ({ path }) => call("resource.get_import_settings", { path }));
+    }, async ({ path }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("resource.get_import_settings", { path });
+    });
     server.registerTool("resource_set_import_settings", {
         title: "Set import settings",
-        description: "Update import parameters in an asset's .import metadata and trigger a reimport. DESTRUCTIVE (rewrites metadata + reimports) — gated by confirmation. Errors if the asset has no .import sidecar.",
+        description: "Update import parameters in an asset's .import metadata and trigger a reimport. DESTRUCTIVE (rewrites metadata + reimports) — gated by confirmation. Errors not_found when the path is not a file, not_imported when the file has no .import sidecar. `settings` echoes every key set; `changed` lists only those whose stored value actually moved, so a no-op is distinguishable from a real edit.",
         inputSchema: {
             path: z.string().describe("Asset res:// path"),
             settings: z.record(z.any()).describe("Import params to set (name -> JSON scalar or __type__-tagged Variant)"),
@@ -95,6 +135,13 @@ export function registerResourceTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, settings, reimport, confirm }) => {
+        // 🔴 MEASURED: `res://../example_evil/g166_icon.png` had its `.import` SIDECAR
+        // REWRITTEN outside the project root — verdict from the sidecar's hash. The other
+        // two spellings answered `reimported: true` while changing nothing out there,
+        // which is a separate reporting problem and is NOT what this guard is for.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set import settings on ${path} and reimport`);
         if (blocked)
             return blocked;

package/dist/tools/editor/scene.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** Scene lifecycle: open / save / new / reload / pack / dependencies. */
-export function registerSceneTools(server, call) {
+export function registerSceneTools(server, call, guard) {
     server.registerTool("scene_get_tree", {
         title: "Get scene tree",
         description: "Return the node tree of the currently edited scene (name, type, path, script, children).",
@@ -11,7 +11,12 @@ export function registerSceneTools(server, call) {
         title: "Open scene",
         description: "Open an existing scene in the editor by res:// path.",
         inputSchema: { path: z.string().describe("Scene path, e.g. res://scenes/main.tscn") },
-    }, async ({ path }) => call("scene.open", { path }));
+    }, async ({ path }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("scene.open", { path });
+    });
     server.registerTool("scene_save", { title: "Save scene", description: "Save the currently edited scene to its existing path.", inputSchema: {} }, async () => call("scene.save"));
     server.registerTool("scene_new", {
         title: "New scene",
@@ -23,6 +28,9 @@ export function registerSceneTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ root_type, path, name, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create and overwrite scene file "${path}"`);
         if (blocked)
             return blocked;
@@ -41,6 +49,12 @@ export function registerSceneTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, confirm }) => {
+        // 🔴 OPTIONAL — an omitted `path` means "the current edited scene" and must stay
+        // legal. `makePathGuard` returns null for undefined; an over-eager mutation that
+        // refuses omission is caught by the sweep.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Reload scene ${path ?? "(current)"} from disk, discarding unsaved changes`);
         if (blocked)
             return blocked;
@@ -68,6 +82,11 @@ export function registerSceneTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, to_path, confirm }) => {
+        // `path` is a NODE path inside the open scene, not a file path — it cannot
+        // express a filesystem escape and is deliberately left alone.
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Pack branch "${path}" to ${to_path}`);
         if (blocked)
             return blocked;
@@ -75,9 +94,14 @@ export function registerSceneTools(server, call) {
     });
     server.registerTool("scene_get_dependencies", {
         title: "Scene dependencies",
-        description: "List the external resource dependencies of a scene file. Read-only. Defaults to the current scene.",
+        description: "List the external resource dependencies of a scene file. Read-only. Defaults to the current scene. `dependencies` are loadable res:// paths; `dependencies_raw` carries the engine's own `uid://…::::res://…` encoding and `dependency_uids` the UID alone (\"\" when the dependency has none) — all three index-aligned.",
         inputSchema: { path: z.string().optional().describe("Scene res:// path; omitted = the current edited scene") },
-    }, async ({ path }) => call("scene.get_dependencies", path !== undefined ? { path } : {}));
+    }, async ({ path }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
+        return call("scene.get_dependencies", path !== undefined ? { path } : {});
+    });
     server.registerTool("scene_save_as", {
         title: "Save scene as",
         description: "Save the current scene to a new res:// path (Save As). DESTRUCTIVE (writes a file) — gated by confirmation.",
@@ -86,6 +110,9 @@ export function registerSceneTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Save the current scene to ${path}`);
         if (blocked)
             return blocked;

package/dist/tools/editor/shader.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** Shader + ShaderMaterial authoring. */
-export function registerShaderTools(server, call) {
+export function registerShaderTools(server, call, guard) {
     server.registerTool("shader_create", {
         title: "Create shader",
         description: "Create a Shader resource with optional initial code and save it as a .gdshader file. DESTRUCTIVE (writes a file) — gated by confirmation.",
@@ -11,6 +11,9 @@ export function registerShaderTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, code, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create shader at ${to_path}`);
         if (blocked)
             return blocked;
@@ -25,6 +28,9 @@ export function registerShaderTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, code, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Overwrite shader code at ${path}`);
         if (blocked)
             return blocked;
@@ -37,7 +43,12 @@ export function registerShaderTools(server, call) {
             path: z.string().describe("Node path relative to the scene root (a CanvasItem or GeometryInstance3D)"),
             shader_path: z.string().optional().describe("res:// path to a Shader to assign to the new material"),
         },
-    }, async ({ path, shader_path }) => call("shadermaterial.create", shader_path !== undefined ? { path, shader_path } : { path }));
+    }, async ({ path, shader_path }) => {
+        const escaped = guard(shader_path, "shader_path");
+        if (escaped)
+            return escaped;
+        return call("shadermaterial.create", shader_path !== undefined ? { path, shader_path } : { path });
+    });
     server.registerTool("shadermaterial_set_shader", {
         title: "Set shader material shader",
         description: "Load a Shader from a res:// path and assign it to the ShaderMaterial on a node's material slot in the edited scene (undoable). The node must already have a ShaderMaterial. In-scene and undoable — not gated.",
@@ -45,7 +56,12 @@ export function registerShaderTools(server, call) {
             path: z.string().describe("Node path relative to the scene root"),
             shader_path: z.string().describe("res:// path to a Shader resource"),
         },
-    }, async ({ path, shader_path }) => call("shadermaterial.set_shader", { path, shader_path }));
+    }, async ({ path, shader_path }) => {
+        const escaped = guard(shader_path, "shader_path");
+        if (escaped)
+            return escaped;
+        return call("shadermaterial.set_shader", { path, shader_path });
+    });
     server.registerTool("shadermaterial_set_param", {
         title: "Set shader material parameter",
         description: "Set a shader uniform parameter on the ShaderMaterial of a node's material slot in the edited scene (undoable). The node must already have a ShaderMaterial. The value uses the tagged-Variant convention. In-scene and undoable — not gated.",

package/dist/tools/editor/spatial.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** 3D & navigation. meshinstance/mesh/light/camera/csg/navregion/navagent mutate the EDITED scene and are undoable + ungated (the node_* model). primitive_mesh_create and the two environment_* tools author a resource on disk, so are file-writers gated by confirmation. */
-export function registerSpatialTools(server, call) {
+export function registerSpatialTools(server, call, guard) {
     server.registerTool("meshinstance_create", {
         title: "Create MeshInstance3D",
         description: "Add a MeshInstance3D under a parent (undoable). Optional 'mesh_path' loads a Mesh resource (e.g. a primitive_mesh_create output) and assigns it. Returns the new node's path.",
@@ -11,6 +11,9 @@ export function registerSpatialTools(server, call) {
             mesh_path: z.string().optional().describe("Mesh resource res:// path to assign to the instance's 'mesh'"),
         },
     }, async ({ parent_path, name, mesh_path }) => {
+        const escaped = guard(mesh_path, "mesh_path");
+        if (escaped)
+            return escaped;
         const params = { parent_path };
         if (name !== undefined)
             params.name = name;
@@ -27,6 +30,9 @@ export function registerSpatialTools(server, call) {
             surface: z.number().int().optional().describe("Surface index, or -1 (default) for material_override"),
         },
     }, async ({ path, material_path, surface }) => {
+        const escaped = guard(material_path, "material_path");
+        if (escaped)
+            return escaped;
         const params = { path, material_path };
         if (surface !== undefined)
             params.surface = surface;
@@ -41,6 +47,9 @@ export function registerSpatialTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, shape, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create ${shape ?? "box"} PrimitiveMesh at ${to_path}`);
         if (blocked)
             return blocked;
@@ -154,6 +163,9 @@ export function registerSpatialTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, background, ambient_color, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create Environment at ${to_path}`);
         if (blocked)
             return blocked;
@@ -173,6 +185,9 @@ export function registerSpatialTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, sky_material, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set sky on Environment ${path}`);
         if (blocked)
             return blocked;

package/dist/tools/editor/tiles.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** TileSet authoring (disk-backed, gated) + TileMapLayer cell painting. */
-export function registerTileTools(server, call) {
+export function registerTileTools(server, call, guard) {
     server.registerTool("tileset_create", {
         title: "Create TileSet",
         description: "Instantiate a TileSet resource and save it as a new .tres file. DESTRUCTIVE (writes a file) — gated by confirmation. tile_size is the base grid cell size in pixels (default 16×16).",
@@ -11,6 +11,9 @@ export function registerTileTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, tile_size, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create TileSet resource at ${to_path}`);
         if (blocked)
             return blocked;
@@ -29,6 +32,9 @@ export function registerTileTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ tileset_path, texture_path, texture_region_size, source_id, margins, separation, confirm }) => {
+        const escaped = guard(tileset_path, "tileset_path") ?? guard(texture_path, "texture_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Add atlas source (${texture_path}) to TileSet ${tileset_path}`);
         if (blocked)
             return blocked;
@@ -54,6 +60,9 @@ export function registerTileTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ tileset_path, source_id, atlas_coords, size, confirm }) => {
+        const escaped = guard(tileset_path, "tileset_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Add tile ${JSON.stringify(atlas_coords)} to source ${source_id} in ${tileset_path}`);
         if (blocked)
             return blocked;
@@ -75,6 +84,9 @@ export function registerTileTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ tileset_path, source_id, atlas_coords, polygon, physics_layer, one_way, confirm }) => {
+        const escaped = guard(tileset_path, "tileset_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set collision on tile ${JSON.stringify(atlas_coords)} in ${tileset_path}`);
         if (blocked)
             return blocked;
@@ -94,6 +106,9 @@ export function registerTileTools(server, call) {
             tileset_path: z.string().optional().describe("TileSet res:// .tres path to bind as tile_set (e.g. from tileset_create)"),
         },
     }, async ({ parent_path, name, tileset_path }) => {
+        const escaped = guard(tileset_path, "tileset_path");
+        if (escaped)
+            return escaped;
         const params = { parent_path };
         if (name !== undefined)
             params.name = name;