pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ManageViews.cs

@@ -1,100 +1,115 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class ManageViews : ITool
-{
-    public string Name => "manage_views";
-    public string Label => "Manage Views";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Create a plan, isometric 3D view or section; duplicate or update an existing view. Resolve view-family-type IDs with get_element_types (of_class ViewFamilyType), and level IDs with get_elements. A section uses document internal axes and explicit length units, orthogonal viewing_direction/up vectors, origin, width/height/depth. Duplication options are duplicate, with_detailing or dependent. Optional name, scale and view_template_id apply in the same transaction; -1 removes a template. Incompatible templates or template-controlled scale changes fail without removing the template. preview=true commit-validates then rolls back; created preview IDs are temporary. Use delete_elements to remove views.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            action = new { type = "string", @enum = new[] { "create_plan", "create_3d", "create_section", "duplicate", "update" } },
-            view_id = new { type = "integer", description = "Existing view for duplicate/update." },
-            view_family_type_id = new { type = "integer", description = "Compatible ViewFamilyType for creation." },
-            level_id = new { type = "integer", description = "Level for create_plan." },
-            duplicate_option = new { type = "string", @enum = new[] { "duplicate", "with_detailing", "dependent" } },
-            name = new { type = "string", minLength = 1 }, scale = new { type = "integer", minimum = 1, maximum = 24000 },
-            view_template_id = new { type = "integer", description = "Compatible template ID, or -1 to remove." },
-            unit = ModelEditInputs.LengthUnitSchema,
-            origin = ModelEditInputs.VectorSchema("Section origin in document internal coordinates, in unit."),
-            viewing_direction = ModelEditInputs.VectorSchema("Section viewing direction, dimensionless nonzero vector."),
-            up = ModelEditInputs.VectorSchema("Section up vector, orthogonal to viewing_direction."),
-            width = new { type = "number", exclusiveMinimum = 0 }, height = new { type = "number", exclusiveMinimum = 0 }, depth = new { type = "number", exclusiveMinimum = 0 },
-            preview = ModelEditInputs.PreviewSchema,
-        }, required = new[] { "action" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        string action = JsonArgs.GetString(args, "action") ?? "";
-        if (action is not ("create_plan" or "create_3d" or "create_section" or "duplicate" or "update")) throw new ArgumentException("Unknown view action.");
-        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
-        {
-            ElementId Id(string key) => new(JsonArgs.GetLong(args, key) is long id && id > 0 ? id : throw new ArgumentException($"{key} must be a positive ID."));
-            View view;
-            object? before = null;
-            if (action is "duplicate" or "update")
-            {
-                view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view.");
-                before = Describe(view);
-                if (action == "duplicate")
-                {
-                    var option = (JsonArgs.GetString(args, "duplicate_option") ?? "duplicate") switch
-                    {
-                        "duplicate" => ViewDuplicateOption.Duplicate, "with_detailing" => ViewDuplicateOption.WithDetailing,
-                        "dependent" => ViewDuplicateOption.AsDependent, _ => throw new ArgumentException("Invalid duplicate_option."),
-                    };
-                    if (!view.CanViewBeDuplicated(option)) throw new ArgumentException("This view cannot be duplicated with that option.");
-                    view = (View)doc.GetElement(view.Duplicate(option));
-                }
-            }
-            else if (action == "create_plan") view = ViewPlan.Create(doc, Id("view_family_type_id"), Id("level_id"));
-            else if (action == "create_3d") view = View3D.CreateIsometric(doc, Id("view_family_type_id"));
-            else
-            {
-                double factor = ModelEditInputs.LengthScale(args);
-                var origin = ModelEditInputs.Vector(args, "origin").Multiply(factor);
-                var direction = ModelEditInputs.Vector(args, "viewing_direction");
-                var up = ModelEditInputs.Vector(args, "up");
-                if (direction.GetLength() < 1e-12 || up.GetLength() < 1e-12) throw new ArgumentException("Section directions must be nonzero.");
-                direction = direction.Normalize(); up = up.Normalize();
-                if (Math.Abs(direction.DotProduct(up)) > 1e-8) throw new ArgumentException("Section up and viewing_direction must be orthogonal.");
-                double width = ModelEditInputs.Number(args, "width") * factor, height = ModelEditInputs.Number(args, "height") * factor, depth = ModelEditInputs.Number(args, "depth") * factor;
-                if (width <= 1e-6 || height <= 1e-6 || depth <= 1e-6) throw new ArgumentException("Section dimensions must exceed 0.000001 feet.");
-                var transform = Transform.Identity;
-                transform.Origin = origin; transform.BasisZ = direction; transform.BasisY = up; transform.BasisX = up.CrossProduct(direction).Normalize();
-                using var box = new BoundingBoxXYZ { Transform = transform, Min = new XYZ(-width / 2, -height / 2, 0), Max = new XYZ(width / 2, height / 2, depth), Enabled = true };
-                view = ViewSection.CreateSection(doc, Id("view_family_type_id"), box);
-            }
-            if (args.TryGetProperty("name", out var name))
-            {
-                if (name.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(name.GetString())) throw new ArgumentException("name must be nonempty.");
-                view.Name = name.GetString()!;
-            }
-            if (args.TryGetProperty("view_template_id", out _))
-            {
-                long template = JsonArgs.GetLong(args, "view_template_id") ?? 0;
-                if (template != -1 && (template <= 0 || !view.IsValidViewTemplate(new ElementId(template)))) throw new ArgumentException("view_template_id is not compatible with this view.");
-                view.ViewTemplateId = new ElementId(template);
-            }
-            if (args.TryGetProperty("scale", out var scale))
-            {
-                if (!scale.TryGetInt32(out int value) || value is < 1 or > 24000) throw new ArgumentException("scale must be an integer from 1 to 24000.");
-                var parameter = view.get_Parameter(BuiltInParameter.VIEW_SCALE);
-                if (parameter == null) throw new ArgumentException("This view's scale is unavailable.");
-                if (doc.GetElement(view.ViewTemplateId) is View template && template.GetTemplateParameterIds().Except(template.GetNonControlledTemplateParameterIds()).Contains(parameter.Id))
-                    throw new ArgumentException("This view's scale is controlled by its template.");
-                view.Scale = value;
-            }
-            doc.Regenerate();
-            return new() { ["before"] = before, ["view"] = Describe(view), ["created"] = action != "update", ["id_is_temporary"] = action != "update" && JsonArgs.GetBool(args, "preview", false) };
-        }) }).Payload;
-    }
-    private static object Describe(View view) => new { id = view.Id.Value, unique_id = view.UniqueId, name = view.Name, view_type = view.ViewType.ToString(), template_id = view.ViewTemplateId.Value, scale = view.Scale };
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageViews : ITool
+{
+    public string Name => "manage_views";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "view", "floor plan", "ceiling plan", "section", "3d view", "duplicate view", "dependent view", "view template", "scale", "create view" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Perspective (camera) 3D views", "api", "View3D.CreatePerspective; ViewOrientation3D"),
+        new ToolLimit("Elevation, drafting and legend views", "api", "ElevationMarker.CreateElevationMarker; ViewDrafting.Create"),
+        new ToolLimit("View visibility and graphics (hiding, overrides, crop regions)", "api", "View.SetCategoryHidden; View.HideElements; View.SetElementOverrides; View.CropBox"),
+        new ToolLimit("Deleting views", "tool", "delete_elements"),
+    };
+    public string? Verification => "capture";
+    public string Label => "Manage Views";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create a plan, isometric 3D view or section; duplicate or update an existing view. A duplicate's result reports inherited_state: the source's hidden categories and elements, filters, overrides and template it carries. A name another view of the same type already uses is rejected with that view's ID. Resolve view-family-type IDs with get_element_types (of_class ViewFamilyType), and level IDs with get_elements. A section uses document internal axes and explicit length units, orthogonal viewing_direction/up vectors, origin, width/height/depth. Duplication options are duplicate, with_detailing or dependent. Optional name, scale and view_template_id apply in the same transaction; -1 removes a template. Incompatible templates or template-controlled scale changes fail without removing the template. preview=true commit-validates then rolls back; created preview IDs are temporary. Use delete_elements to remove views.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create_plan", "create_3d", "create_section", "duplicate", "update" } },
+            view_id = new { type = "integer", description = "Existing view for duplicate/update." },
+            view_family_type_id = new { type = "integer", description = "Compatible ViewFamilyType for creation." },
+            level_id = new { type = "integer", description = "Level for create_plan." },
+            duplicate_option = new { type = "string", @enum = new[] { "duplicate", "with_detailing", "dependent" } },
+            name = new { type = "string", minLength = 1 }, scale = new { type = "integer", minimum = 1, maximum = 24000 },
+            view_template_id = new { type = "integer", description = "Compatible template ID, or -1 to remove." },
+            unit = ModelEditInputs.LengthUnitSchema,
+            origin = ModelEditInputs.VectorSchema("Section origin in document internal coordinates, in unit."),
+            viewing_direction = ModelEditInputs.VectorSchema("Section viewing direction, dimensionless nonzero vector."),
+            up = ModelEditInputs.VectorSchema("Section up vector, orthogonal to viewing_direction."),
+            width = new { type = "number", exclusiveMinimum = 0 }, height = new { type = "number", exclusiveMinimum = 0 }, depth = new { type = "number", exclusiveMinimum = 0 },
+            preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("create_plan" or "create_3d" or "create_section" or "duplicate" or "update")) throw new ArgumentException("Unknown view action.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            ElementId Id(string key) => new(JsonArgs.GetLong(args, key) is long id && id > 0 ? id : throw new ArgumentException($"{key} must be a positive ID."));
+            View view;
+            View? source = null;
+            object? before = null;
+            if (action is "duplicate" or "update")
+            {
+                view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view.");
+                before = Describe(view);
+                if (action == "duplicate")
+                {
+                    var option = (JsonArgs.GetString(args, "duplicate_option") ?? "duplicate") switch
+                    {
+                        "duplicate" => ViewDuplicateOption.Duplicate, "with_detailing" => ViewDuplicateOption.WithDetailing,
+                        "dependent" => ViewDuplicateOption.AsDependent, _ => throw new ArgumentException("Invalid duplicate_option."),
+                    };
+                    if (!view.CanViewBeDuplicated(option)) throw new ArgumentException("This view cannot be duplicated with that option.");
+                    source = view;
+                    view = (View)doc.GetElement(view.Duplicate(option));
+                }
+            }
+            else if (action == "create_plan") view = ViewPlan.Create(doc, Id("view_family_type_id"), Id("level_id"));
+            else if (action == "create_3d") view = View3D.CreateIsometric(doc, Id("view_family_type_id"));
+            else
+            {
+                double factor = ModelEditInputs.LengthScale(args);
+                var origin = ModelEditInputs.Vector(args, "origin").Multiply(factor);
+                var direction = ModelEditInputs.Vector(args, "viewing_direction");
+                var up = ModelEditInputs.Vector(args, "up");
+                if (direction.GetLength() < 1e-12 || up.GetLength() < 1e-12) throw new ArgumentException("Section directions must be nonzero.");
+                direction = direction.Normalize(); up = up.Normalize();
+                if (Math.Abs(direction.DotProduct(up)) > 1e-8) throw new ArgumentException("Section up and viewing_direction must be orthogonal.");
+                double width = ModelEditInputs.Number(args, "width") * factor, height = ModelEditInputs.Number(args, "height") * factor, depth = ModelEditInputs.Number(args, "depth") * factor;
+                if (width <= 1e-6 || height <= 1e-6 || depth <= 1e-6) throw new ArgumentException("Section dimensions must exceed 0.000001 feet.");
+                var transform = Transform.Identity;
+                transform.Origin = origin; transform.BasisZ = direction; transform.BasisY = up; transform.BasisX = up.CrossProduct(direction).Normalize();
+                using var box = new BoundingBoxXYZ { Transform = transform, Min = new XYZ(-width / 2, -height / 2, 0), Max = new XYZ(width / 2, height / 2, depth), Enabled = true };
+                view = ViewSection.CreateSection(doc, Id("view_family_type_id"), box);
+            }
+            if (args.TryGetProperty("name", out var name))
+            {
+                if (name.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(name.GetString())) throw new ArgumentException("name must be nonempty.");
+                ElementNames.Assign(view, name.GetString()!);
+            }
+            if (args.TryGetProperty("view_template_id", out _))
+            {
+                long template = JsonArgs.GetLong(args, "view_template_id") ?? 0;
+                if (template != -1 && (template <= 0 || !view.IsValidViewTemplate(new ElementId(template)))) throw new ArgumentException("view_template_id is not compatible with this view.");
+                view.ViewTemplateId = new ElementId(template);
+            }
+            if (args.TryGetProperty("scale", out var scale))
+            {
+                if (!scale.TryGetInt32(out int value) || value is < 1 or > 24000) throw new ArgumentException("scale must be an integer from 1 to 24000.");
+                var parameter = view.get_Parameter(BuiltInParameter.VIEW_SCALE);
+                if (parameter == null) throw new ArgumentException("This view's scale is unavailable.");
+                if (doc.GetElement(view.ViewTemplateId) is View template && template.GetTemplateParameterIds().Except(template.GetNonControlledTemplateParameterIds()).Contains(parameter.Id))
+                    throw new ArgumentException("This view's scale is controlled by its template.");
+                view.Scale = value;
+            }
+            doc.Regenerate();
+            var result = new Dictionary<string, object?> { ["before"] = before, ["view"] = Describe(view), ["created"] = action != "update", ["id_is_temporary"] = action != "update" && JsonArgs.GetBool(args, "preview", false) };
+            // A duplicate carries its source's visibility and graphics (inv:derived-state-reported).
+            if (source != null) result["inherited_state"] = InheritedState.OfView(view, source.Id.Value);
+            return result;
+        }) }).Payload;
+    }
+    private static object Describe(View view) => new { id = view.Id.Value, unique_id = view.UniqueId, name = view.Name, view_type = view.ViewType.ToString(), template_id = view.ViewTemplateId.Value, scale = view.Scale };
+}

package/src/Revit/Tools/MeasureGeometry.cs

@@ -1,54 +1,60 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class MeasureGeometry : ITool
-{
-    public string Name => "measure_geometry";
-    public string Label => "Measure Geometry";
-    public string Tier => "advanced";
-    public string Description => "Measure exact Euclidean distance between two explicit points, or approximate separation between two host elements' model axis-aligned bounding boxes. Required unit applies to point inputs, optional clearance threshold, and all output coordinates/distances. Points use document internal axes. Box gap is a lower bound on geometry separation: zero means enclosing boxes touch/overlap, not a confirmed clash. Bounds can include nonphysical geometry. An optional clearance threshold classifies only box proximity, never a physical clearance failure. Does not traverse linked contents.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            mode = new { type = "string", @enum = new[] { "point_distance", "bounding_box_gap" } }, unit = ModelEditInputs.LengthUnitSchema,
-            point_a = ModelEditInputs.VectorSchema("First point in document internal axes, in unit."), point_b = ModelEditInputs.VectorSchema("Second point in document internal axes, in unit."),
-            element_a_id = new { type = "integer", minimum = 1 }, element_b_id = new { type = "integer", minimum = 1 },
-            clearance = new { type = "number", minimum = 0, description = "Optional box-proximity threshold in unit, only for bounding_box_gap." },
-        }, required = new[] { "mode", "unit" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        double scale = ModelEditInputs.LengthScale(args);
-        string? mode = JsonArgs.GetString(args, "mode"), unit = JsonArgs.GetString(args, "unit");
-        if (mode == "point_distance")
-        {
-            if (args.TryGetProperty("clearance", out _) || args.TryGetProperty("element_a_id", out _) || args.TryGetProperty("element_b_id", out _))
-                throw new ArgumentException("point_distance accepts points, not element IDs or clearance.");
-            var a = ModelEditInputs.Vector(args, "point_a").Multiply(scale); var b = ModelEditInputs.Vector(args, "point_b").Multiply(scale);
-            return new { method = mode, approximate = false, coordinate_system = "document_internal", unit, distance = a.DistanceTo(b) / scale,
-                delta = SpatialBounds.Coordinates(b - a, scale), point_a = SpatialBounds.Coordinates(a, scale), point_b = SpatialBounds.Coordinates(b, scale) };
-        }
-        if (mode != "bounding_box_gap") throw new ArgumentException("Unknown measurement mode.");
-        if (args.TryGetProperty("point_a", out _) || args.TryGetProperty("point_b", out _)) throw new ArgumentException("bounding_box_gap accepts element IDs, not points.");
-        Element Resolve(string key)
-        {
-            long id = JsonArgs.GetLong(args, key) ?? 0;
-            return id > 0 ? doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"{key} {id} was not found.") : throw new ArgumentException($"{key} must be positive.");
-        }
-        var elementA = Resolve("element_a_id"); var elementB = Resolve("element_b_id");
-        var boundsA = SpatialBounds.Of(elementA) ?? throw new ArgumentException($"Element {elementA.Id.Value} has no model bounding box.");
-        var boundsB = SpatialBounds.Of(elementB) ?? throw new ArgumentException($"Element {elementB.Id.Value} has no model bounding box.");
-        var gap = boundsA.Gap(boundsB); double distance = gap.GetLength() / scale;
-        double? clearance = args.TryGetProperty("clearance", out _) ? ModelEditInputs.Number(args, "clearance") : null;
-        if (clearance < 0) throw new ArgumentException("clearance cannot be negative.");
-        return new { method = mode, approximate = true, coordinate_system = "document_internal", unit, distance, axis_gaps = SpatialBounds.Coordinates(gap, scale),
-            boxes_overlap_or_touch = boundsA.Intersects(boundsB), clearance, box_gap_below_clearance = clearance.HasValue ? (bool?)(distance < clearance.Value) : null,
-            interpretation = "Bounding-box gap is a lower bound on geometry separation. Overlap or a gap below clearance identifies candidates for geometry review, not a confirmed clash or clearance failure.",
-            element_a = new { id = elementA.Id.Value, unique_id = elementA.UniqueId, bounds = boundsA.Describe(scale) },
-            element_b = new { id = elementB.Id.Value, unique_id = elementB.UniqueId, bounds = boundsB.Describe(scale) } };
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class MeasureGeometry : ITool
+{
+    public string Name => "measure_geometry";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "distance", "measure", "gap", "clearance", "spacing", "dimension check" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Exact solid-to-solid distance or clash detection", "api", "ElementIntersectsElementFilter; ElementIntersectsSolidFilter; ReferenceIntersector"),
+    };
+    public string Label => "Measure Geometry";
+    public string Tier => "advanced";
+    public string Description => "Measure exact Euclidean distance between two explicit points, or approximate separation between two host elements' model axis-aligned bounding boxes. Required unit applies to point inputs, optional clearance threshold, and all output coordinates/distances. Points use document internal axes. Box gap is a lower bound on geometry separation: zero means enclosing boxes touch/overlap, not a confirmed clash. Bounds can include nonphysical geometry. An optional clearance threshold classifies only box proximity, never a physical clearance failure. Does not traverse linked contents.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            mode = new { type = "string", @enum = new[] { "point_distance", "bounding_box_gap" } }, unit = ModelEditInputs.LengthUnitSchema,
+            point_a = ModelEditInputs.VectorSchema("First point in document internal axes, in unit."), point_b = ModelEditInputs.VectorSchema("Second point in document internal axes, in unit."),
+            element_a_id = new { type = "integer", minimum = 1 }, element_b_id = new { type = "integer", minimum = 1 },
+            clearance = new { type = "number", minimum = 0, description = "Optional box-proximity threshold in unit, only for bounding_box_gap." },
+        }, required = new[] { "mode", "unit" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        double scale = ModelEditInputs.LengthScale(args);
+        string? mode = JsonArgs.GetString(args, "mode"), unit = JsonArgs.GetString(args, "unit");
+        if (mode == "point_distance")
+        {
+            if (args.TryGetProperty("clearance", out _) || args.TryGetProperty("element_a_id", out _) || args.TryGetProperty("element_b_id", out _))
+                throw new ArgumentException("point_distance accepts points, not element IDs or clearance.");
+            var a = ModelEditInputs.Vector(args, "point_a").Multiply(scale); var b = ModelEditInputs.Vector(args, "point_b").Multiply(scale);
+            return new { method = mode, approximate = false, coordinate_system = "document_internal", unit, distance = a.DistanceTo(b) / scale,
+                delta = SpatialBounds.Coordinates(b - a, scale), point_a = SpatialBounds.Coordinates(a, scale), point_b = SpatialBounds.Coordinates(b, scale) };
+        }
+        if (mode != "bounding_box_gap") throw new ArgumentException("Unknown measurement mode.");
+        if (args.TryGetProperty("point_a", out _) || args.TryGetProperty("point_b", out _)) throw new ArgumentException("bounding_box_gap accepts element IDs, not points.");
+        Element Resolve(string key)
+        {
+            long id = JsonArgs.GetLong(args, key) ?? 0;
+            return id > 0 ? doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"{key} {id} was not found.") : throw new ArgumentException($"{key} must be positive.");
+        }
+        var elementA = Resolve("element_a_id"); var elementB = Resolve("element_b_id");
+        var boundsA = SpatialBounds.Of(elementA) ?? throw new ArgumentException($"Element {elementA.Id.Value} has no model bounding box.");
+        var boundsB = SpatialBounds.Of(elementB) ?? throw new ArgumentException($"Element {elementB.Id.Value} has no model bounding box.");
+        var gap = boundsA.Gap(boundsB); double distance = gap.GetLength() / scale;
+        double? clearance = args.TryGetProperty("clearance", out _) ? ModelEditInputs.Number(args, "clearance") : null;
+        if (clearance < 0) throw new ArgumentException("clearance cannot be negative.");
+        return new { method = mode, approximate = true, coordinate_system = "document_internal", unit, distance, axis_gaps = SpatialBounds.Coordinates(gap, scale),
+            boxes_overlap_or_touch = boundsA.Intersects(boundsB), clearance, box_gap_below_clearance = clearance.HasValue ? (bool?)(distance < clearance.Value) : null,
+            interpretation = "Bounding-box gap is a lower bound on geometry separation. Overlap or a gap below clearance identifies candidates for geometry review, not a confirmed clash or clearance failure.",
+            element_a = new { id = elementA.Id.Value, unique_id = elementA.UniqueId, bounds = boundsA.Describe(scale) },
+            element_b = new { id = elementB.Id.Value, unique_id = elementB.UniqueId, bounds = boundsB.Describe(scale) } };
+    }
+}

package/src/Revit/Tools/ModelChanges.cs

@@ -0,0 +1,154 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Autodesk.Revit.DB;
+using Autodesk.Revit.DB.Events;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Records what one model-changing tool call did to the document (inv:model-changes-reported)
+    /// and merges a bounded report into its result as model_changes. The bridge dispatcher wraps
+    /// every tool that can write or has model effects, including execute_csharp, so present and
+    /// future tools report created, modified and deleted objects without tool-specific code. New
+    /// views are reported with their visibility state through InheritedState, which covers views
+    /// duplicated in custom code. The Pi extension builds its per-request ledger of objects created
+    /// by the agent from this report.
+    /// </summary>
+    internal sealed class ModelChangeRecorder : IDisposable
+    {
+        public const int ItemCap = 20;
+        public const int NewViewStateCap = 3;
+        private readonly Autodesk.Revit.ApplicationServices.Application _application;
+        private readonly Document _document;
+        private readonly ChangeSet _changes = new();
+        // Family types and parameters are not elements, so DocumentChanged cannot name them;
+        // a family document is compared before and after the call instead.
+        private readonly FamilySnapshot? _familyBefore;
+
+        private ModelChangeRecorder(Autodesk.Revit.ApplicationServices.Application application, Document document)
+        {
+            _application = application; _document = document;
+            _familyBefore = FamilySnapshot.Of(document);
+            _application.DocumentChanged += OnChanged;
+        }
+
+        /// <summary>A recorder for tools that can change the model; null for everything else.</summary>
+        public static ModelChangeRecorder? For(ITool tool, Autodesk.Revit.ApplicationServices.Application application, Document document)
+            => tool.Write || tool.Effects.Contains("model") ? new ModelChangeRecorder(application, document) : null;
+
+        private void OnChanged(object? sender, DocumentChangedEventArgs e)
+        {
+            if (!e.GetDocument().Equals(_document)) return;
+            _changes.Record(e.Operation.ToString(), Ids(e.GetAddedElementIds()), Ids(e.GetModifiedElementIds()), Ids(e.GetDeletedElementIds()));
+        }
+
+        private static IEnumerable<long> Ids(ICollection<ElementId> ids) => ids.Select(id => id.Value).ToList();
+
+        public void Dispose() => _application.DocumentChanged -= OnChanged;
+
+        /// <summary>
+        /// Merge model_changes into an object payload; other payload shapes are returned unchanged.
+        /// The tool has already run: a reporting failure must never turn its result into an error.
+        /// </summary>
+        public object? Attach(object? output)
+        {
+            try
+            {
+                object? payload = output is ToolOutput tool ? tool.Payload : output;
+                if (JsonSerializer.SerializeToNode(payload) is not JsonObject json) return output;
+                bool describesState = json.ToJsonString().Contains("\"inherited_state\"", StringComparison.Ordinal);
+                json["model_changes"] = JsonSerializer.SerializeToNode(Report(!describesState));
+                return output is ToolOutput original ? original with { Payload = json } : json;
+            }
+            catch (Exception error) when (error is not OutOfMemoryException)
+            {
+                return output;
+            }
+        }
+
+        public Dictionary<string, object?> Report(bool includeNewViewState)
+        {
+            // A read through a write-capable tool (a placement listing, a read-only script) changed
+            // nothing: say so in one field instead of empty lists on every call.
+            if (!_changes.Observed) return new() { ["observed"] = false };
+            var added = _changes.Added.Where(id => _document.GetElement(new ElementId(id)) != null).OrderBy(id => id).ToList();
+            var modified = _changes.Modified.Where(id => _document.GetElement(new ElementId(id)) != null).OrderBy(id => id).ToList();
+            var deleted = _changes.Deleted.Where(id => _document.GetElement(new ElementId(id)) == null).OrderBy(id => id).ToList();
+            var report = new Dictionary<string, object?>
+            {
+                ["observed"] = _changes.Observed,
+                ["added"] = Describe(added),
+                ["modified"] = Describe(modified),
+                ["deleted"] = new Dictionary<string, object?> { ["count"] = deleted.Count, ["ids"] = deleted.Take(ItemCap).ToList() },
+            };
+            if (_changes.RolledBack) report["rolled_back"] = true;
+            if (_familyBefore != null && FamilySnapshot.Of(_document) is { } familyAfter && FamilySnapshot.Diff(_familyBefore, familyAfter) is { } family)
+                report["family"] = family;
+            // Revit reports elements it only regenerated (analytical nodes, imports, the project's
+            // internal elements) as modified; round-3 agents relayed those as edits.
+            if (modified.Count > 0)
+                report["modified_note"] = "Modified includes elements Revit updated as a side effect of regeneration. Report as changed only what your edit targeted; reread anything else before claiming it changed.";
+            if (includeNewViewState)
+            {
+                var views = added.Select(id => _document.GetElement(new ElementId(id))).OfType<View>()
+                    .Where(view => !view.IsTemplate && view is not ViewSheet && view is not ViewSchedule).Take(NewViewStateCap)
+                    .Select(view => new Dictionary<string, object?> { ["id"] = view.Id.Value, ["name"] = view.Name, ["view_type"] = view.ViewType.ToString(),
+                        ["state"] = InheritedState.Summarize(InheritedState.ReadView(view, null), InheritedState.NewViewCheck) }).ToList();
+                if (views.Count > 0) report["new_views"] = views;
+            }
+            return report;
+        }
+
+        /// <summary>A family document's types (with every value) and parameter names; null in a project.</summary>
+        internal sealed record FamilySnapshot(Dictionary<string, string> Types, HashSet<string> Parameters)
+        {
+            public static FamilySnapshot? Of(Document doc)
+            {
+                if (!doc.IsFamilyDocument) return null;
+                var manager = doc.FamilyManager;
+                var parameters = manager.Parameters.Cast<FamilyParameter>().OrderBy(p => p.Definition.Name).ToList();
+                string Value(FamilyType type, FamilyParameter parameter)
+                {
+                    try { return type.HasValue(parameter) ? type.AsValueString(parameter) ?? type.AsString(parameter) ?? "" : ""; }
+                    catch (Autodesk.Revit.Exceptions.ApplicationException) { return "?"; }
+                }
+                var types = new Dictionary<string, string>();
+                foreach (FamilyType type in manager.Types)
+                    types[type.Name] = string.Join("|", parameters.Select(p => p.Definition.Name + "=" + Value(type, p)));
+                return new FamilySnapshot(types, parameters.Select(p => p.Definition.Name).ToHashSet());
+            }
+
+            /// <summary>Family types and parameters added, removed or changed; null when none changed.</summary>
+            public static Dictionary<string, object?>? Diff(FamilySnapshot before, FamilySnapshot after)
+            {
+                var added = after.Types.Keys.Except(before.Types.Keys).OrderBy(n => n).ToList();
+                var removed = before.Types.Keys.Except(after.Types.Keys).OrderBy(n => n).ToList();
+                var changed = before.Types.Keys.Where(n => after.Types.TryGetValue(n, out var v) && v != before.Types[n]).OrderBy(n => n).ToList();
+                var parametersAdded = after.Parameters.Except(before.Parameters).OrderBy(n => n).ToList();
+                var parametersRemoved = before.Parameters.Except(after.Parameters).OrderBy(n => n).ToList();
+                if (added.Count + removed.Count + changed.Count + parametersAdded.Count + parametersRemoved.Count == 0) return null;
+                return new Dictionary<string, object?>
+                {
+                    ["types_added"] = added, ["types_removed"] = removed, ["types_changed"] = changed,
+                    ["parameters_added"] = parametersAdded, ["parameters_removed"] = parametersRemoved,
+                };
+            }
+        }
+
+        private Dictionary<string, object?> Describe(IReadOnlyList<long> ids) => new()
+        {
+            ["count"] = ids.Count,
+            ["items"] = ids.Take(ItemCap).Select(id =>
+            {
+                var element = _document.GetElement(new ElementId(id));
+                return new Dictionary<string, object?> { ["id"] = id, ["name"] = SafeName(element), ["category"] = element?.Category?.Name, ["class"] = element?.GetType().Name };
+            }).ToList(),
+        };
+
+        private static string? SafeName(Element? element)
+        {
+            try { return element?.Name; }
+            catch (Autodesk.Revit.Exceptions.InvalidOperationException) { return null; }
+        }
+    }
+}