@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/editor/pause.cs

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>editor.pause — 切换暂停状态。</summary>
+    public class EditorPauseTool : IUnityCliTool<EditorPauseTool.Request, EditorPauseTool.Response>
+    {
+        public sealed class Request { }
+        public sealed class Response { public PlayModeResult Result { get; set; } public EditorStateInfo State { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.pause", Summary = "Toggle Play Mode pause state and return its observed terminal readback.", Description = "Toggle EditorApplication.isPaused and succeed only when the readback is the inverse of the pre-call state.", Group = "editor",DestructiveHint = false, SideEffects = new[] { "session-affecting" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Toggle pause", Input = new Request { } } } };
+
+        public async System.Threading.Tasks.ValueTask<Response> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            EditorToolSupport.EnsureEditorNotBusy("editor.pause");
+            var before = EditorApplication.isPaused;
+            var expectedPaused = !before;
+            ctx.CommitEffect();
+            EditorApplication.isPaused = expectedPaused;
+            var stable = await ctx.Wait.UntilStable(
+                () => EditorApplication.isPaused == expectedPaused,
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)),
+                ct: ct);
+            if (!stable)
+                throw new UnityCliBridge.BridgeCommandException("E_PLAYMODE_PAUSE_STATE_MISMATCH", "Unity did not apply the requested pause-state toggle.", "Inspect Play Mode state before retrying.");
+
+            // 末次读回避免把同一帧的瞬态状态作为成功结果。
+            var observedPaused = EditorApplication.isPaused;
+            if (observedPaused != expectedPaused)
+                throw new UnityCliBridge.BridgeCommandException("E_PLAYMODE_PAUSE_STATE_MISMATCH", "Unity did not apply the requested pause-state toggle.", "Inspect Play Mode state before retrying.");
+            var state = EditorToolSupport.BuildEditorState();
+            return new Response { Result = new PlayModeResult { Changed = observedPaused != before, IsPlaying = state.PlayMode.IsPlaying, IsPaused = observedPaused }, State = state, PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.pause" } } };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/play.cs

@@ -0,0 +1,43 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>editor.play — 进入 Play Mode。</summary>
+    public class EditorPlayTool : IUnityCliTool<EditorPlayTool.Request, EditorPlayTool.Response>
+    {
+        public sealed class Request { }
+        public sealed class Response { public PlayModeResult Result { get; set; } public EditorStateInfo State { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.play", Summary = "Enter Unity Play Mode and return only after the Editor reaches a stable playing state.", Description = "Set EditorApplication.isPlaying=true, absorb the PlayMode transition or same-session reload, and return the stable Editor state. Success proves isPlaying=true and the central PlayMode transition flag is false.", Group = "editor",DestructiveHint = false, SideEffects = new[] { "session-affecting" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Enter play mode", Input = new Request { } } } };
+        public async System.Threading.Tasks.ValueTask<Response> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            // before 采集一次后按 requestId 存 SessionState：PlayMode 过渡触发 domain reload，
+            // 同一请求重跑时 before 必须仍是第一次 effect 前的值，Changed 语义才跨 reload 成立。
+            var beforeKey = "unity-cli.play.before." + ctx.RequestId;
+            var rawBefore = SessionState.GetString(beforeKey, null);
+            bool before;
+            if (string.IsNullOrEmpty(rawBefore))
+            {
+                before = EditorApplication.isPlaying;
+                SessionState.SetString(beforeKey, before ? "1" : "0");
+            }
+            else before = rawBefore == "1";
+            EditorToolSupport.EnsureEditorNotBusy("editor.play");
+            ctx.CommitEffect();
+            EditorApplication.isPaused = false;
+            EditorApplication.isPlaying = true;
+            var stable = await ctx.Wait.UntilStable(
+                () => EditorApplication.isPlaying && !UnityCliBridge.IsPlayModeChanging(),
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)),
+                ct: ct);
+            if (!stable || !EditorApplication.isPlaying || UnityCliBridge.IsPlayModeChanging())
+                throw new UnityCliBridge.BridgeCommandException("E_PLAY_MODE_TERMINAL_NOT_OBSERVED", "Play Mode did not reach a stable playing state.", "Inspect editor.state before deciding whether to submit a new request.");
+            return new Response { Result = new PlayModeResult { Changed = !before, IsPlaying = true, IsPaused = EditorApplication.isPaused }, State = EditorToolSupport.BuildEditorState(), PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.play" } } };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/redo.cs

@@ -0,0 +1,56 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>editor.redo — 执行 Redo。</summary>
+    public class EditorRedoTool : IUnityCliTool<EditorRedoTool.Request, EditorRedoTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public UnityCliCompletionProbe CompletionProbe { get; set; } }
+        public sealed class Result { public bool Performed { get; set; } public EditorStateInfo State { get; set; } public UnityCliCompletionProbeReadback Completion { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.redo", Summary = "Perform one shared Redo entry and prove the declared object state.",
+            Description = "Call Undo.PerformRedo() exactly once. completionProbe must identify an eligible read Tool and a before/after state for the affected resource; the Redo callback alone is not completion proof.",
+            Group = "editor", DestructiveHint = false, SideEffects = new[] { "undo-redo-replay", "undo-stack" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample
+                {
+                    Description = "Redo an Undo-recorded Main Camera x move from 0 to 1.",
+                    Input = new Request
+                    {
+                        CompletionProbe = new UnityCliCompletionProbe
+                        {
+                            ReadTool = "scene.gameobject", Input = new Dictionary<string, object> { { "target", "Main Camera" } },
+                            Assertions = new List<UnityCliCompletionAssertion>
+                            {
+                                new UnityCliCompletionAssertion { Path = "/gameObject/transform/position/x", Operator = "approx", Before = 0.0, After = 1.0, Tolerance = 0.0001 }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            EditorToolSupport.EnsureEditorNotBusy("editor.redo");
+            var performed = false;
+            Undo.UndoRedoCallback callback = () => performed = true;
+            Undo.undoRedoPerformed += callback;
+            try
+            {
+                var completion = ctx.RunCompletionProbe(r == null ? null : r.CompletionProbe, () =>
+                {
+                    Undo.PerformRedo();
+                    if (!performed) throw new UnityCliBridge.BridgeCommandException("E_REDO_NOT_PERFORMED", "Unity did not perform a Redo operation.", "Ensure the shared Redo stack contains an entry, then retry.");
+                });
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Performed = true, State = EditorToolSupport.BuildEditorState(), Completion = completion, PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "undo-redo-replay", Action = "redo" } } });
+            }
+            finally { Undo.undoRedoPerformed -= callback; }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/resolution.cs

@@ -0,0 +1,34 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>editor.resolution — 设置 PlayerSettings 分辨率。</summary>
+    public class EditorResolutionTool : IUnityCliTool<EditorResolutionTool.Request, EditorResolutionTool.Result>
+    {
+        public sealed class Request { public int? Width { get; set; } public int? Height { get; set; } public bool? Fullscreen { get; set; } }
+        public sealed class Result { public ResolutionInfo Resolution { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.resolution", Summary = "Set PlayerSettings default screen width, height, and fullscreen mode.", Description = "Update PlayerSettings.defaultScreenWidth/Height and fullScreenMode.", Group = "editor",DestructiveHint = true, SideEffects = new[] { "settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set 1920x1080", Input = new Request { Width = 1920, Height = 1080 } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            EditorToolSupport.EnsureEditorNotBusy("editor.resolution");
+            var width = Math.Max(1, r.Width ?? PlayerSettings.defaultScreenWidth);
+            var height = Math.Max(1, r.Height ?? PlayerSettings.defaultScreenHeight);
+            ctx.CommitEffect();
+            PlayerSettings.defaultScreenWidth = width;
+            PlayerSettings.defaultScreenHeight = height;
+            if (r.Fullscreen.HasValue) PlayerSettings.fullScreenMode = r.Fullscreen.Value ? FullScreenMode.FullScreenWindow : FullScreenMode.Windowed;
+            var observedWidth = PlayerSettings.defaultScreenWidth;
+            var observedHeight = PlayerSettings.defaultScreenHeight;
+            var observedMode = PlayerSettings.fullScreenMode;
+            if (observedWidth != width || observedHeight != height || (r.Fullscreen.HasValue && observedMode != (r.Fullscreen.Value ? FullScreenMode.FullScreenWindow : FullScreenMode.Windowed)))
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_RESOLUTION_STATE_MISMATCH", "PlayerSettings resolution readback did not match the request.", "Inspect Player Settings and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Resolution = new ResolutionInfo { Width = observedWidth, Height = observedHeight, FullScreenMode = observedMode.ToString() }, PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.resolution" } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/search.cs

@@ -0,0 +1,55 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>运行Unity Search provider查询并返回有界页。</summary>
+    public sealed class EditorSearchTool : IUnityCliTool<EditorSearchRequest, EditorSearchResult>
+    {
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.search",
+            Summary = "Run a bounded Unity Search query with explicit provider metadata and paging.",
+            Description = "Uses UnityEditor.Search directly across active Unity Search providers. providers accepts at most 16 exact active provider IDs; omission uses the active provider set. offset accepts 0..10000 and limit defaults to 50 with a maximum of 200. At most offset+limit+1 items are scanned and only the requested page is retained. This is provider-level Unity Search, not an alias for asset.search or go.find.",
+            Group = "editor",
+            DestructiveHint = false,
+            SupportsDryRun = false,
+            SideEffects = System.Array.Empty<string>(),
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Find Material items through Unity Search.", Input = new EditorSearchRequest { Query = "t:Material", Limit = 20 } },
+                new ToolExample { Description = "Query one exact provider page.", Input = new EditorSearchRequest { Query = "Main Camera", Providers = new List<string> { "scene" }, Offset = 0, Limit = 50 } }
+            }
+        };
+
+        /// <summary>同步Search context在方法内创建和释放，输出只保留bounded page。</summary>
+        public System.Threading.Tasks.ValueTask<EditorSearchResult> ExecuteAsync(EditorSearchRequest request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ct.ThrowIfCancellationRequested();
+            return new System.Threading.Tasks.ValueTask<EditorSearchResult>(EditorSearchToolSupport.Search(request));
+        }
+    }
+
+    public sealed class EditorSearchRequest
+    {
+        [UnityCliRequired]
+        public string Query { get; set; }
+        public List<string> Providers { get; set; }
+        public long? Offset { get; set; }
+        public long? Limit { get; set; }
+    }
+
+    public sealed class EditorSearchResult
+    {
+        public long ReturnedCount { get; set; }
+        public bool HasMore { get; set; }
+        public long? NextOffset { get; set; }
+        public List<EditorSearchItem> Results { get; set; }
+        public List<EditorSearchProvider> Providers { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/selection/set.cs

@@ -0,0 +1,37 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.Compilation;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>editor.selection.set — 设置 Editor 选择。</summary>
+    public class EditorSelectionSetTool : IUnityCliTool<EditorSelectionSetTool.Request, EditorSelectionSetTool.Result>
+    {
+        public sealed class Request { public long? InstanceId { get; set; } public string Target { get; set; } public string Path { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public string Selected { get; set; } public string TypeName { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.selection.set", Summary = "Set the active selection in the Unity Editor.", Description = "Set Selection.activeObject by instanceId or target path. dryRun=true previews.", Group = "editor",DestructiveHint = false, SupportsDryRun = true, SideEffects = new[] { "editor-selection" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Select by path", Input = new Request { Target = "Player" } } } };
+        // 设置选择后按实例标识验证 Unity 的活动选择。
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var dryRun = ctx.DryRun;
+            var target = r.Target ?? r.Path;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, Selected = target ?? "<instanceId>" });
+            UnityEngine.Object obj = null;
+            if (r.InstanceId.HasValue && r.InstanceId.Value != 0) obj = EditorUtility.InstanceIDToObject((int)r.InstanceId.Value);
+            else if (!string.IsNullOrEmpty(target)) obj = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(target);
+            if (obj == null) throw new UnityCliBridge.BridgeCommandException("E_SELECTION_TARGET_NOT_FOUND", "Selection target not found.", "Pass a valid instanceId or path.");
+            ctx.CommitEffect();
+            Selection.activeObject = obj;
+            var selected = Selection.activeObject;
+            if (selected == null || selected.GetInstanceID() != obj.GetInstanceID())
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_SELECTION_STATE_MISMATCH", "Unity did not select the requested object.", "Inspect the Editor selection and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Selected = selected.name, TypeName = selected.GetType().Name });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/selection.cs

@@ -0,0 +1,153 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>editor.selection 只读 Tool：只读当前 Editor Selection。</summary>
+        public sealed class EditorSelectionTool : IUnityCliTool<EditorSelectionTool.Request, EditorSelectionTool.Result>
+        {
+            public sealed class Request { }
+
+            public sealed class Result
+            {
+                public string ActiveObject { get; set; }
+                public bool HasActiveObject { get; set; }
+                public string ActiveGameObject { get; set; }
+                public bool HasActiveGameObject { get; set; }
+                public string ActiveTransform { get; set; }
+                public bool HasActiveTransform { get; set; }
+                public SelectionObjectInfo ActiveObjectDetail { get; set; }
+                public SelectionObjectInfo ActiveGameObjectDetail { get; set; }
+                public SelectionObjectInfo ActiveTransformDetail { get; set; }
+                public List<string> Objects { get; set; }
+                public List<SelectionObjectInfo> ObjectDetails { get; set; }
+                public List<string> GameObjects { get; set; }
+                public List<SelectionObjectInfo> GameObjectDetails { get; set; }
+                public List<string> AssetGUIDs { get; set; }
+            }
+
+            public sealed class SelectionObjectInfo
+            {
+                public string Name { get; set; }
+                public long InstanceId { get; set; }
+                public string Type { get; set; }
+                public string FullName { get; set; }
+                public string AssetPath { get; set; }
+                public string AssetGUID { get; set; }
+                public string HierarchyPath { get; set; }
+                public GameObjectRef GameObject { get; set; }
+                public TransformInfo Transform { get; set; }
+                public List<ComponentSummary> Components { get; set; }
+            }
+
+            public sealed class GameObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
+            public sealed class TransformInfo { public VectorInfo Position { get; set; } public VectorInfo Rotation { get; set; } public VectorInfo Scale { get; set; } }
+            public sealed class VectorInfo { public double X { get; set; } public double Y { get; set; } public double Z { get; set; } }
+            public sealed class ComponentSummary { public string Type { get; set; } public string FullName { get; set; } public bool Enabled { get; set; } }
+
+            // 返回只读 Tool 的发现元数据。
+            public ToolDescriptor Describe() => new()
+            {
+                Name = "editor.selection", Summary = "Read current Editor selection names and reusable object references without changing selection.",
+                Description = "Read the current Unity Editor selection in Hierarchy or Project Browser. Returns name arrays plus reusable object details: instanceId, type, asset path/GUID, hierarchy path, GameObject reference, transform, and component summaries. It does not select, focus, ping, or modify anything.",
+                DestructiveHint = false,
+                Group = "editor", Target = "editor", PlayModeSupport = "supported",
+                Examples = new[] { new ToolExample { Description = "Read the current selection", Input = new Request { } } }
+            };
+
+            /// <summary>读取当前选择，不修改 Selection 或资产。</summary>
+            public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+            {
+                var activeObject = Selection.activeObject;
+                var activeGameObject = Selection.activeGameObject;
+                var activeTransform = Selection.activeTransform;
+                var objects = Selection.objects ?? new UnityEngine.Object[0];
+                var gameObjects = Selection.gameObjects ?? new GameObject[0];
+                var result = new Result
+                {
+                    ActiveObject = activeObject == null ? null : activeObject.name, HasActiveObject = activeObject != null,
+                    ActiveGameObject = activeGameObject == null ? null : activeGameObject.name, HasActiveGameObject = activeGameObject != null,
+                    ActiveTransform = activeTransform == null ? null : activeTransform.name, HasActiveTransform = activeTransform != null,
+                    ActiveObjectDetail = SelectionObjectInfoFrom(activeObject), ActiveGameObjectDetail = SelectionObjectInfoFrom(activeGameObject), ActiveTransformDetail = SelectionObjectInfoFrom(activeTransform),
+                    Objects = new List<string>(), ObjectDetails = new List<SelectionObjectInfo>(), GameObjects = new List<string>(), GameObjectDetails = new List<SelectionObjectInfo>(), AssetGUIDs = new List<string>()
+                };
+                foreach (var obj in objects)
+                {
+                    if (obj == null) continue;
+                    result.Objects.Add(obj.name);
+                    result.ObjectDetails.Add(SelectionObjectInfoFrom(obj));
+                    var assetGuid = SelectionAssetGuid(obj);
+                    if (!string.IsNullOrEmpty(assetGuid)) result.AssetGUIDs.Add(assetGuid);
+                }
+                foreach (var gameObject in gameObjects)
+                {
+                    result.GameObjects.Add(gameObject == null ? null : gameObject.name);
+                    if (gameObject != null) result.GameObjectDetails.Add(SelectionObjectInfoFrom(gameObject));
+                }
+                return new System.Threading.Tasks.ValueTask<Result>(result);
+            }
+        }
+
+        // 将选中对象映射为可复用引用；仅查询对象与 AssetDatabase 元数据。
+        private static EditorSelectionTool.SelectionObjectInfo SelectionObjectInfoFrom(UnityEngine.Object obj)
+        {
+            if (obj == null) return null;
+            var gameObject = SelectionObjectGameObject(obj);
+            var info = new EditorSelectionTool.SelectionObjectInfo
+            {
+                Name = obj.name, InstanceId = obj.GetInstanceID(), Type = obj.GetType().Name, FullName = obj.GetType().FullName,
+                AssetPath = NormalizeAssetPath(AssetDatabase.GetAssetPath(obj)), AssetGUID = SelectionAssetGuid(obj),
+                Components = new List<EditorSelectionTool.ComponentSummary>()
+            };
+            if (gameObject == null) return info;
+            info.HierarchyPath = HierarchyPath(gameObject);
+            info.GameObject = new EditorSelectionTool.GameObjectRef { Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = info.HierarchyPath };
+            info.Transform = SelectionTransformInfoFrom(gameObject.transform);
+            foreach (var component in gameObject.GetComponents<Component>())
+            {
+                info.Components.Add(new EditorSelectionTool.ComponentSummary
+                {
+                    Type = component == null ? "MissingScript" : component.GetType().Name,
+                    FullName = component == null ? null : component.GetType().FullName,
+                    Enabled = component != null && ComponentEnabled(component)
+                });
+            }
+            return info;
+        }
+
+        // 读取 Transform 世界位置、欧拉角和本地缩放。
+        private static EditorSelectionTool.TransformInfo SelectionTransformInfoFrom(Transform transform)
+        {
+            return new EditorSelectionTool.TransformInfo { Position = SelectionVectorInfoFrom(transform.position), Rotation = SelectionVectorInfoFrom(transform.eulerAngles), Scale = SelectionVectorInfoFrom(transform.localScale) };
+        }
+
+        // 将 Vector3 转成协议 DTO。
+        private static EditorSelectionTool.VectorInfo SelectionVectorInfoFrom(Vector3 value)
+        {
+            return new EditorSelectionTool.VectorInfo { X = value.x, Y = value.y, Z = value.z };
+        }
+
+        // 从任意 Unity 对象解析所属 GameObject；资产对象无所属对象。
+        private static GameObject SelectionObjectGameObject(UnityEngine.Object obj)
+        {
+            if (obj is GameObject gameObject) return gameObject;
+            if (obj is Component component) return component.gameObject;
+            return null;
+        }
+
+        // 读取选中资产 GUID；场景对象或非资产对象无 GUID。
+        private static string SelectionAssetGuid(UnityEngine.Object obj)
+        {
+            if (obj == null) return null;
+            var assetPath = AssetDatabase.GetAssetPath(obj);
+            if (string.IsNullOrEmpty(assetPath)) return null;
+            var guid = AssetDatabase.AssetPathToGUID(assetPath);
+            return string.IsNullOrEmpty(guid) ? null : guid;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/stop.cs

@@ -0,0 +1,43 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>editor.stop — 退出 Play Mode。</summary>
+    public class EditorStopTool : IUnityCliTool<EditorStopTool.Request, EditorStopTool.Response>
+    {
+        public sealed class Request { }
+        public sealed class Response { public PlayModeResult Result { get; set; } public EditorStateInfo State { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.stop", Summary = "Exit Unity Play Mode and return only after the Editor reaches stable Edit Mode.", Description = "Set EditorApplication.isPlaying=false, absorb the PlayMode transition or same-session reload, and return the stable Editor state. Success proves isPlaying=false and the central PlayMode transition flag is false.", Group = "editor",DestructiveHint = false, SideEffects = new[] { "session-affecting" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Exit play mode", Input = new Request { } } } };
+        public async System.Threading.Tasks.ValueTask<Response> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            // before 采集一次后按 requestId 存 SessionState：PlayMode 过渡触发 domain reload，
+            // 同一请求重跑时 before 必须仍是第一次 effect 前的值，Changed 语义才跨 reload 成立。
+            var beforeKey = "unity-cli.stop.before." + ctx.RequestId;
+            var rawBefore = SessionState.GetString(beforeKey, null);
+            bool before;
+            if (string.IsNullOrEmpty(rawBefore))
+            {
+                before = EditorApplication.isPlaying;
+                SessionState.SetString(beforeKey, before ? "1" : "0");
+            }
+            else before = rawBefore == "1";
+            EditorToolSupport.EnsureEditorNotBusy("editor.stop");
+            ctx.CommitEffect();
+            EditorApplication.isPaused = false;
+            EditorApplication.isPlaying = false;
+            var stable = await ctx.Wait.UntilStable(
+                () => !EditorApplication.isPlaying && !UnityCliBridge.IsPlayModeChanging(),
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)),
+                ct: ct);
+            if (!stable || EditorApplication.isPlaying || UnityCliBridge.IsPlayModeChanging())
+                throw new UnityCliBridge.BridgeCommandException("E_EDIT_MODE_TERMINAL_NOT_OBSERVED", "The Editor did not reach stable Edit Mode.", "Inspect editor.state before deciding whether to submit a new request.");
+            return new Response { Result = new PlayModeResult { Changed = before, IsPlaying = false, IsPaused = false }, State = EditorToolSupport.BuildEditorState(), PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.stop" } } };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/tool-states.cs

@@ -0,0 +1,140 @@
+#if UNITY_EDITOR
+using System;
+using System.Globalization;
+using System.Reflection;
+using UnityEditor;
+
+namespace UnityCli.Tools.Editor
+{
+    /// <summary>
+    /// editor.tool-states 只读 Tool：读取 Editor transform 工具和 snap/grid 状态。
+    /// </summary>
+    public class EditorToolStatesTool : IUnityCliTool<EditorToolStatesTool.Request, EditorToolStatesTool.Result>
+    {
+        public sealed class Request { }
+
+        public sealed class TransformState
+        {
+            public string ActiveTool { get; set; }
+            public string PivotMode { get; set; }
+            public string PivotRotation { get; set; }
+        }
+
+        public sealed class SnapState
+        {
+            public bool MoveSnapEnabled { get; set; }
+            public bool RotationSnapEnabled { get; set; }
+            public bool ScaleSnapEnabled { get; set; }
+            public float MoveSnap { get; set; }
+            public float RotationSnap { get; set; }
+            public float ScaleSnap { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public TransformState Transform { get; set; }
+            public SnapState Snap { get; set; }
+            public bool GridAvailable { get; set; }
+        }
+
+        // ── desc:只声明人工字段,source=built-in 表示进入只读 Tool 表 ──
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.tool-states",
+            Summary = "Read Editor transform, pivot, snap, and grid tool state.",
+            Description = "Read Unity Editor transform tool settings, pivot mode/rotation, snap settings, and grid availability. This is not MCP tool discovery; it observes editor tool configuration only.",
+            DestructiveHint = false,
+            Group = "editor",
+            Target = "editor",
+            PlayModeSupport = "supported",
+            Examples = new[] { new ToolExample { Description = "Read transform tool and snap settings", Input = new Request { } } }
+        };
+
+        /// <summary>
+        /// 读取 transform 工具与 snap 设置；只观察状态，不切换工具、不修改网格或吸附设置。
+    /// </summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var snapSettingsType = FindType("UnityEditor.EditorSnapSettings");
+            var moveSnapEnabled = snapSettingsType != null ? BoolMemberValue(snapSettingsType, null, "snapMoveEnabled") : null;
+            var rotationSnapEnabled = snapSettingsType != null ? BoolMemberValue(snapSettingsType, null, "snapRotationEnabled") : null;
+            var scaleSnapEnabled = snapSettingsType != null ? BoolMemberValue(snapSettingsType, null, "snapScaleEnabled") : null;
+            var moveSnap = snapSettingsType != null ? FloatMemberValue(snapSettingsType, null, "moveSnap") : null;
+            var rotationSnap = snapSettingsType != null ? FloatMemberValue(snapSettingsType, null, "rotationSnap") : null;
+            var scaleSnap = snapSettingsType != null ? FloatMemberValue(snapSettingsType, null, "scaleSnap") : null;
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Transform = new TransformState
+                {
+                    ActiveTool = UnityEditor.Tools.current.ToString(),
+                    PivotMode = UnityEditor.Tools.pivotMode.ToString(),
+                    PivotRotation = UnityEditor.Tools.pivotRotation.ToString()
+                },
+                Snap = new SnapState
+                {
+                    MoveSnapEnabled = moveSnapEnabled ?? false,
+                    RotationSnapEnabled = rotationSnapEnabled ?? false,
+                    ScaleSnapEnabled = scaleSnapEnabled ?? false,
+                    MoveSnap = moveSnapEnabled.HasValue && moveSnapEnabled.Value && moveSnap.HasValue ? moveSnap.Value : 0f,
+                    RotationSnap = rotationSnapEnabled.HasValue && rotationSnapEnabled.Value && rotationSnap.HasValue ? rotationSnap.Value : 0f,
+                    ScaleSnap = scaleSnapEnabled.HasValue && scaleSnapEnabled.Value && scaleSnap.HasValue ? scaleSnap.Value : 0f
+                },
+                GridAvailable = snapSettingsType != null
+            });
+        }
+
+        // 在当前 AppDomain 中查找 Unity 内部类型；找不到时返回 null，让输出降级为 gridAvailable=false。
+        private static Type FindType(string fullName)
+        {
+            var type = Type.GetType(fullName);
+            if (type != null) return type;
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                try
+                {
+                    type = assembly.GetType(fullName);
+                    if (type != null) return type;
+                }
+                catch
+                {
+                    // 忽略无法反射的编辑器程序集，继续查找其它程序集。
+                }
+            }
+            return null;
+        }
+
+        // 读取 bool 类型的 public/private static/instance 成员；反射失败时返回 null。
+        private static bool? BoolMemberValue(Type type, object instance, string memberName)
+        {
+            var prop = type.GetProperty(memberName, BindingFlags.Instance | BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (prop != null)
+            {
+                try { return Convert.ToBoolean(prop.GetValue(instance, null), CultureInfo.InvariantCulture); } catch { return null; }
+            }
+            var field = type.GetField(memberName, BindingFlags.Instance | BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (field != null)
+            {
+                try { return Convert.ToBoolean(field.GetValue(instance), CultureInfo.InvariantCulture); } catch { return null; }
+            }
+            return null;
+        }
+
+        // 读取 float 类型的 public/private static/instance 成员；反射失败时返回 null。
+        private static float? FloatMemberValue(Type type, object instance, string memberName)
+        {
+            var prop = type.GetProperty(memberName, BindingFlags.Instance | BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (prop != null)
+            {
+                try { return Convert.ToSingle(prop.GetValue(instance, null), CultureInfo.InvariantCulture); } catch { return null; }
+            }
+            var field = type.GetField(memberName, BindingFlags.Instance | BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (field != null)
+            {
+                try { return Convert.ToSingle(field.GetValue(instance), CultureInfo.InvariantCulture); } catch { return null; }
+            }
+            return null;
+        }
+    }
+}
+#endif