@alpsckr/unitycli 0.4.2 → 0.4.4

package/unitypkg/Editor/ProjectTools/ProjectToolRegistry.cs

@@ -3,13 +3,11 @@ using System;
 using System.CodeDom.Compiler;
 using System.Collections.Generic;
 using System.Globalization;
-using System.IO;
 using System.Linq;
 using System.Net;
 using System.Reflection;
 using System.Security.Cryptography;
 using System.Text;
-using System.Text.RegularExpressions;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.CSharp;
@@ -29,45 +27,32 @@ namespace UnityCli
 {
     public static partial class UnityCliBridge
     {
-        private const string ProjectToolFingerprintAlgorithm = "unity-cli-project-tool-fingerprint-v2";
         private const string OfficialAttributeToolPrefix = "UnityPipeline_";
         private const string OfficialAttributeToolGroup = "UnityPipeline";
-        private static readonly Dictionary<string, RegisteredTool> ProjectTools = new Dictionary<string, RegisteredTool>(StringComparer.Ordinal);
-        private static Dictionary<string, RegisteredTool> discoveryTools;
-        private static RegistryOwnershipResolver registryOwnership;
+        private static UnityCliPublishedToolCatalog publishedProjectToolCatalog;
+        private static UnityCliToolCatalogHealthSnapshot projectToolCatalogHealth = new UnityCliToolCatalogHealthSnapshot(
+            false, 0, "catalog was not initialized", "Let Unity compile and reload the domain before retrying.");
+        private static int projectToolCatalogConstructionCount;
+        private static readonly byte[] projectToolCatalogCursorSecret = CreateProjectToolCatalogCursorSecret();
+        internal static IUnityCliToolCatalogSnapshotReader ProjectToolCatalogSnapshotReader { get; } = new PublishedToolCatalogSnapshotReader();
+        internal static IUnityCliToolCatalogHealthSnapshotReader ProjectToolCatalogHealthSnapshotReader { get; } = new PublishedToolCatalogHealthSnapshotReader();
 
-        private static void RegisterProjectTool(RegisteredTool definition)
+        private sealed class PublishedToolCatalogSnapshotReader : IUnityCliToolCatalogSnapshotReader
         {
-            if (definition == null || string.IsNullOrWhiteSpace(definition.Name) || string.IsNullOrWhiteSpace(definition.Summary) || definition.InvokeAsync == null)
-            {
-                throw new ArgumentException("Tool registration requires name, summary, and a typed async invoker.");
-            }
-            var target = discoveryTools ?? ProjectTools;
-            if (target.ContainsKey(definition.Name)) throw new InvalidOperationException("Duplicate tool registration: " + definition.Name);
-            if (definition.RequestType == null || definition.ResultType == null || string.IsNullOrWhiteSpace(definition.InputSchema) || string.IsNullOrWhiteSpace(definition.OutputSchema))
-            {
-                throw new ArgumentException("Tool registration requires request/result types and derived schemas: " + definition.Name);
-            }
-            if (definition.RequiredInput == null)
-            {
-                definition.RequiredInput = new string[0];
-            }
-            definition.Group = string.IsNullOrEmpty(definition.Group) ? ProjectToolGroupFromName(definition.Name) : definition.Group;
-            definition.Target = string.IsNullOrEmpty(definition.Target) ? "editor" : definition.Target;
-            definition.AvailabilityScope = string.IsNullOrEmpty(definition.AvailabilityScope) ? (definition.Target == "runtime" ? "playModeSession" : "editorSession") : definition.AvailabilityScope;
-            definition.PlayModeSupport = NormalizeProjectToolPlayModeSupport(definition.PlayModeSupport, definition.Target);
-            if (!string.Equals(definition.ContractProfile, "native", StringComparison.Ordinal)
-                && !string.Equals(definition.ContractProfile, "official-attribute", StringComparison.Ordinal))
-            {
-                throw new ArgumentException("Tool registration requires a known contract profile: " + definition.Name);
-            }
+            public UnityCliToolCatalogSnapshot Read() { return ReadPublishedProjectToolCatalogSnapshot(); }
+        }
+
+        private sealed class PublishedToolCatalogHealthSnapshotReader : IUnityCliToolCatalogHealthSnapshotReader
+        {
+            public UnityCliToolCatalogHealthSnapshot Read() { return Volatile.Read(ref projectToolCatalogHealth); }
+        }
+
+        private static void RegisterProjectTool(UnityCliToolCatalogBuilder builder, RegisteredTool definition, UnityCliToolProviderKind providerKind)
+        {
+            if (builder == null) throw new ArgumentNullException("builder");
+            if (definition == null) throw new ArgumentNullException("definition");
             ValidateOfficialAttributeNamespace(definition);
-            definition.DefaultTimeoutMs = definition.DefaultTimeoutMs <= 0 ? 30000 : definition.DefaultTimeoutMs;
-            definition.MaxTimeoutMs = definition.MaxTimeoutMs <= 0 ? 600000 : definition.MaxTimeoutMs;
-            definition.RegisteredBy = string.IsNullOrEmpty(definition.RegisteredBy) ? "unity-editor-package" : definition.RegisteredBy;
-            definition.DescriptorSource = string.IsNullOrEmpty(definition.DescriptorSource) ? "runtime-registration" : definition.DescriptorSource;
-            RefreshProjectToolFingerprint(definition);
-            target.Add(definition.Name, definition);
+            builder.Add(definition, providerKind);
         }
 
         /// <summary>保留namespace只属于official attribute投影；任一owner违规使整轮pending registry作废。</summary>
@@ -82,51 +67,125 @@ namespace UnityCli
                 throw new InvalidOperationException("Native Tool cannot use the reserved UnityPipeline_ name prefix or UnityPipeline group: " + definition.Name + ".");
         }
 
-        private static void DiscoverProjectTools()
+        /// <summary>InitializeOnLoad静态构造函数调用一次；局部pending完整成功后才原子发布。</summary>
+        private static void InitializeProjectToolCatalog()
         {
-            if (projectToolsDiscovered) return;
-
-            var pending = new Dictionary<string, RegisteredTool>(StringComparer.Ordinal);
+            if (projectToolCatalogConstructionCount != 0) return;
+            projectToolCatalogConstructionCount = 1;
+            var startedAt = DateTime.UtcNow;
+            var builder = new UnityCliToolCatalogBuilder();
             try
             {
-                discoveryTools = pending;
-                var assemblies = AppDomain.CurrentDomain.GetAssemblies();
-                var officialRoots = ConfigureOfficialAuthoringApi(assemblies);
-                var candidates = ToolProviderAssemblies(assemblies, officialRoots);
-                registryOwnership = RegistryOwnershipResolver.Load(candidates);
-                WriteLog("tool_discovery_started assemblies=" + assemblies.Length.ToString(CultureInfo.InvariantCulture)
-                    + " candidates=" + candidates.Count.ToString(CultureInfo.InvariantCulture));
-                foreach (var assembly in candidates)
-                {
-                    Type[] types;
-                    try { types = assembly.GetTypes(); }
-                    catch (ReflectionTypeLoadException exception) { throw new InvalidOperationException("Unable to inspect every type in Tool provider assembly " + assembly.FullName + ".", exception); }
-                    catch (Exception exception) { throw new InvalidOperationException("Unable to inspect Tool provider assembly " + assembly.FullName + ".", exception); }
-                    foreach (var type in types)
-                    {
-                        if (type == null) continue;
-                        TryRegisterInterfaceProjectTool(assembly, type);
-                        TryRegisterOfficialAttributeTools(assembly, type);
-                    }
-                }
-                WriteLog("tool_discovery_completed candidates=" + candidates.Count.ToString(CultureInfo.InvariantCulture)
-                    + " tools=" + pending.Count.ToString(CultureInfo.InvariantCulture));
-
-                ProjectTools.Clear();
-                foreach (var item in pending) ProjectTools.Add(item.Key, item.Value);
-                projectToolsDiscovered = true;
+                CollectProjectToolCatalog(AppDomain.CurrentDomain.GetAssemblies(), builder);
+                PublishProjectToolCatalog(builder, (long)Math.Ceiling((DateTime.UtcNow - startedAt).TotalMilliseconds));
             }
             catch (Exception exception)
             {
-                // 失败前从未写入公开 registry；下一次请求可在 Unity reload 后重新发现。
-                throw new BridgeCommandException("E_TOOL_REGISTRY_UNHEALTHY", "Tool registry discovery failed: " + exception.Message,
-                    new Dictionary<string, object> { { "registry", "tools" } },
-                    new[] { "Fix the extension manifest or capability implementation, then retry discovery.", "Run unitycli extensions doctor --project <path> to inspect extension installation state." }, true, 1000);
+                builder.Abort();
+                var failure = BoundedCatalogDiagnostic(ExceptionChain(exception));
+                Volatile.Write(ref projectToolCatalogHealth, new UnityCliToolCatalogHealthSnapshot(
+                    false, 0, failure, "Fix the Tool definition, then let Unity compile and reload the domain before retrying."));
+                WriteLog("tool_catalog_initialization_failed error=" + failure);
             }
-            finally
+        }
+
+        /// <summary>生产与大目录fixture共享同一assembly筛选、owner解析、类型扫描和pending table构造。</summary>
+        private static void CollectProjectToolCatalog(Assembly[] assemblies, UnityCliToolCatalogBuilder builder)
+        {
+            if (assemblies == null) throw new ArgumentNullException("assemblies");
+            if (builder == null) throw new ArgumentNullException("builder");
+            var officialRoots = ConfigureOfficialAuthoringApi(assemblies);
+            var candidates = ToolProviderAssemblies(assemblies, officialRoots);
+            builder.BeginDiscovery(assemblies.Length, candidates.Count);
+            var ownership = RegistryOwnershipResolver.Load(candidates);
+            foreach (var assembly in candidates)
+            {
+                builder.RecordProviderMetadata(assembly.GetName().FullName);
+                Type[] types;
+                try { types = assembly.GetTypes(); }
+                catch (ReflectionTypeLoadException exception) { throw new InvalidOperationException("Unable to inspect every type in Tool provider assembly " + assembly.FullName + ".", exception); }
+                catch (Exception exception) { throw new InvalidOperationException("Unable to inspect Tool provider assembly " + assembly.FullName + ".", exception); }
+                foreach (var type in types)
+                {
+                    if (type == null) continue;
+                    TryRegisterInterfaceProjectTool(builder, ownership, assembly, type);
+                    TryRegisterOfficialAttributeTools(builder, ownership, assembly, type);
+                }
+            }
+            ownership.ValidateComplete();
+        }
+
+        private static bool ProjectToolCatalogReady()
+        {
+            return Volatile.Read(ref publishedProjectToolCatalog) != null;
+        }
+
+        /// <summary>候选完整 Publish 后才替换唯一 slot；任何第 N 项失败都保留既有 publication。</summary>
+        private static UnityCliToolCatalogSnapshot PublishProjectToolCatalog(UnityCliToolCatalogBuilder builder, long elapsedMilliseconds)
+        {
+            var candidate = builder.Publish(elapsedMilliseconds, WriteProjectToolCatalogInitializedLog);
+            Volatile.Write(ref publishedProjectToolCatalog, candidate);
+            Volatile.Write(ref projectToolCatalogHealth, new UnityCliToolCatalogHealthSnapshot(
+                true, candidate.Snapshot.ToolCount, string.Empty, string.Empty));
+            return candidate.Snapshot;
+        }
+
+        /// <summary>候选提交前写入唯一 aggregate success log；失败时旧 publication 保持不变。</summary>
+        private static void WriteProjectToolCatalogInitializedLog(UnityCliToolCatalogSnapshot snapshot)
+        {
+            WriteLog("tool_catalog_initialized assemblies=" + snapshot.AssemblyCount.ToString(CultureInfo.InvariantCulture)
+                + " providers=" + snapshot.ProviderAssemblyCount.ToString(CultureInfo.InvariantCulture)
+                + " tools=" + snapshot.ToolCount.ToString(CultureInfo.InvariantCulture)
+                + " builtIn=" + snapshot.BuiltInToolCount.ToString(CultureInfo.InvariantCulture)
+                + " extension=" + snapshot.ExtensionToolCount.ToString(CultureInfo.InvariantCulture)
+                + " projectInterface=" + snapshot.ProjectInterfaceToolCount.ToString(CultureInfo.InvariantCulture)
+                + " officialAttribute=" + snapshot.OfficialAttributeToolCount.ToString(CultureInfo.InvariantCulture)
+                + " elapsedMs=" + snapshot.ElapsedMilliseconds.ToString(CultureInfo.InvariantCulture));
+        }
+
+        /// <summary>执行入口读取唯一 published executable table；失败 domain 内绝不重建。</summary>
+        private static UnityCliPublishedToolCatalog ReadPublishedProjectToolCatalog()
+        {
+            var catalog = Volatile.Read(ref publishedProjectToolCatalog);
+            if (catalog != null) return catalog;
+            var health = ProjectToolCatalogHealthSnapshotReader.Read();
+            throw new BridgeCommandException(
+                "E_TOOL_REGISTRY_UNHEALTHY",
+                "Tool catalog initialization failed in the current Unity domain: " + health.Failure,
+                new Dictionary<string, object> { { "registry", "tools" } },
+                new[] { health.NextAction },
+                true,
+                1000);
+        }
+
+        private static UnityCliToolCatalogSnapshot ReadPublishedProjectToolCatalogSnapshot()
+        {
+            return ReadPublishedProjectToolCatalog().Snapshot;
+        }
+
+        /// <summary>doctor 专用只读 health，不取得 invoker、schema 对象或 preflight 聚合。</summary>
+        private static object ProjectToolCatalogHealth(UnityCli.Protocol.BridgeRequest request)
+        {
+            RequireProjectToolCatalogInputKeys(request);
+            var health = ProjectToolCatalogHealthSnapshotReader.Read();
+            var result = new Dictionary<string, object>
+            {
+                { "ready", health.Ready },
+                { "toolCount", (long)health.ToolCount }
+            };
+            if (!health.Ready)
             {
-                discoveryTools = null;
+                result["failure"] = BoundedCatalogDiagnostic(health.Failure);
+                result["nextActions"] = new[] { health.NextAction };
             }
+            return result;
+        }
+
+        private static string BoundedCatalogDiagnostic(string value)
+        {
+            const int maxChars = 4096;
+            if (string.IsNullOrEmpty(value) || value.Length <= maxChars) return value ?? string.Empty;
+            return value.Substring(0, maxChars) + " [truncated]";
         }
 
         /// <summary>
@@ -161,7 +220,7 @@ namespace UnityCli
             return assemblies.Where(assembly => reachable.Contains(assembly.GetName().FullName)).ToList();
         }
 
-        private static void TryRegisterInterfaceProjectTool(Assembly assembly, Type type)
+        private static void TryRegisterInterfaceProjectTool(UnityCliToolCatalogBuilder builder, RegistryOwnershipResolver ownershipResolver, Assembly assembly, Type type)
         {
             if (type == null || type.IsAbstract || type.IsInterface) return;
 
@@ -207,12 +266,12 @@ namespace UnityCli
                 throw new InvalidOperationException("Tool descriptor is incomplete: " + type.FullName + ".");
 
             RegisteredTool definition;
-            var ownership = registryOwnership.Resolve(type);
+            var ownership = ownershipResolver.Resolve(type, descriptor.Name);
             try
             {
                 var factory = typeof(UnityCliBridge).GetMethod("CreateRegisteredTool", BindingFlags.Static | BindingFlags.NonPublic)
                     .MakeGenericMethod(reqType, resType);
-                definition = (RegisteredTool)factory.Invoke(null, new[] { instance, descriptor, assembly, type });
+                definition = (RegisteredTool)factory.Invoke(null, new object[] { instance, descriptor, ownership });
             }
             catch (Exception exception)
             {
@@ -220,72 +279,54 @@ namespace UnityCli
                 WriteLog("custom_tool_registration_failed type=" + type.FullName + " error=" + diagnostics);
                 throw new InvalidOperationException("Tool registration failed: " + type.FullName + ": " + diagnostics, exception);
             }
-            RegisterProjectTool(definition);
-            WriteLog("custom_tool_registered name=" + descriptor.Name + " source=IUnityCliTool type=" + type.FullName);
+            var providerKind = string.Equals(ownership.Source, "built-in", StringComparison.Ordinal)
+                ? UnityCliToolProviderKind.BuiltIn
+                : string.Equals(ownership.Source, "extension", StringComparison.Ordinal)
+                    ? UnityCliToolProviderKind.Extension
+                    : UnityCliToolProviderKind.ProjectInterface;
+            RegisterProjectTool(builder, definition, providerKind);
         }
 
         // 展开反射包装异常，确保 registry 失败能指向具体 schema/descriptor 根因。
         private static string ExceptionChain(Exception exception)
         {
+            const int maxDepth = 8;
             var messages = new List<string>();
-            for (var current = exception; current != null; current = current.InnerException)
+            for (var current = exception; current != null && messages.Count < maxDepth; current = current.InnerException)
             {
                 messages.Add(current.GetType().Name + ": " + current.Message);
             }
-            return string.Join(" -> ", messages.ToArray());
+            return BoundedCatalogDiagnostic(string.Join(" -> ", messages.ToArray()));
         }
 
-        private static RegisteredTool CreateRegisteredTool<TReq, TRes>(object instance, ToolDescriptor descriptor, Assembly assembly, Type implementationType)
+        private static RegisteredTool CreateRegisteredTool<TReq, TRes>(object instance, ToolDescriptor descriptor, RegistryToolOwnership ownership)
         {
             var tool = (IUnityCliTool<TReq, TRes>)instance;
-            var ownership = registryOwnership.Resolve(implementationType);
             var completion = ResolveToolCompletionContract(descriptor, ownership);
-            return new RegisteredTool
-            {
-                Name = descriptor.Name,
-                Summary = descriptor.Summary,
-                Description = descriptor.Description,
-                Group = string.IsNullOrEmpty(descriptor.Group) ? "custom" : descriptor.Group,
-                Descriptor = descriptor,
-                Source = ownership,
-                Ownership = ownership,
-                InputSchema = UnityCliSchemaDeriver.DeriveSchema(typeof(TReq)),
-                OutputSchema = UnityCliSchemaDeriver.DeriveSchema(typeof(TRes)),
-                DestructiveHint = descriptor.DestructiveHint,
-                SideEffects = descriptor.SideEffects ?? Array.Empty<string>(),
-                SupportsDryRun = descriptor.SupportsDryRun,
-                Permissions = descriptor.Permissions ?? Array.Empty<string>(),
-                RequiresPackages = descriptor.RequiresPackages ?? Array.Empty<string>(),
-                Examples = descriptor.Examples ?? Array.Empty<ToolExample>(),
-                Target = string.IsNullOrEmpty(descriptor.Target) ? "editor" : descriptor.Target,
-                PlayModeSupport = string.IsNullOrEmpty(descriptor.PlayModeSupport) ? "editor-only" : descriptor.PlayModeSupport,
-                ContractProfile = "native",
-                DefaultTimeoutMs = descriptor.DefaultTimeoutMs <= 0 ? 30000 : descriptor.DefaultTimeoutMs,
-                MaxTimeoutMs = descriptor.MaxTimeoutMs <= 0 ? 600000 : descriptor.MaxTimeoutMs,
-                RequiredInput = Array.Empty<string>(),
-                RegisteredBy = "unity-editor-package",
-                DescriptorSource = "IUnityCliTool",
-                Assembly = assembly.GetName().Name,
-                Method = implementationType.FullName + ".ExecuteAsync",
-                Fingerprint = descriptor.Fingerprint,
-                PinnedFingerprint = descriptor.Fingerprint,
-                ExpectedFingerprint = descriptor.Fingerprint,
-                RequestType = typeof(TReq),
-                ResultType = typeof(TRes),
-                CompletionContract = completion,
-                InvokeAsync = async (request, context, cancellationToken) => (object)await tool.ExecuteAsync((TReq)request, context, cancellationToken)
-            };
+            return new RegisteredTool(
+                descriptor,
+                ownership,
+                UnityCliSchemaDeriver.DeriveSchema(typeof(TReq)),
+                UnityCliSchemaDeriver.DeriveSchema(typeof(TRes)),
+                string.IsNullOrEmpty(descriptor.Target) || descriptor.Target != "runtime" ? "editorSession" : "playModeSession",
+                "native",
+                typeof(TReq),
+                typeof(TRes),
+                completion,
+                null,
+                async (request, context, cancellationToken) => (object)await tool.ExecuteAsync((TReq)request, context, cancellationToken));
         }
 
         /// <summary>built-in/Extension 只信任生成 registry；自定义 Tool 必须提供完整机器契约。</summary>
-        private static UnityCliToolCompletionContract ResolveToolCompletionContract(ToolDescriptor descriptor, string ownership)
+        private static UnityCliToolCompletionContract ResolveToolCompletionContract(ToolDescriptor descriptor, RegistryToolOwnership ownership)
         {
             UnityCliToolCompletionContract generated;
             if (UnityCliToolCompletionRegistry.TryGet(descriptor.Name, out generated))
             {
                 var generatedExtension = generated.DescriptorOwner.StartsWith("extension:", StringComparison.Ordinal);
-                if ((generatedExtension && !string.Equals(ownership, "extension", StringComparison.Ordinal))
-                    || (!generatedExtension && !string.Equals(generated.DescriptorOwner, ownership, StringComparison.Ordinal)))
+                if ((generatedExtension && (!string.Equals(ownership.Source, "extension", StringComparison.Ordinal)
+                        || !string.Equals(generated.DescriptorOwner, "extension:" + ownership.ExtensionId, StringComparison.Ordinal)))
+                    || (!generatedExtension && !string.Equals(generated.DescriptorOwner, ownership.Source, StringComparison.Ordinal)))
                     throw new InvalidOperationException("Completion contract owner mismatch for " + descriptor.Name + ".");
                 var descriptorMutation = descriptor.DestructiveHint
                     || descriptor.SupportsDryRun
@@ -314,7 +355,7 @@ namespace UnityCli
                 || (descriptor.SideEffects != null && descriptor.SideEffects.Length > 0)
                 || string.Equals(descriptor.PlayModeSupport, "session-affecting", StringComparison.Ordinal);
             return new UnityCliToolCompletionContract(
-                descriptor.Name, "project", "direct-terminal", custom.ExecutionClass, custom.CompletionPredicate,
+                descriptor.Name, ownership.Source, "direct-terminal", custom.ExecutionClass, custom.CompletionPredicate,
                 custom.ProofSource, custom.ReloadPolicy, custom.TimeoutError, custom.OutcomeUnknownPolicy,
                 custom.CompletionDriverId, mutation ? "required" : "none", mutation);
         }
@@ -323,24 +364,373 @@ namespace UnityCli
         private static UnityCliToolCompletionContract ResolveRegisteredCustomToolCompletionContract(string toolName)
         {
             if (string.IsNullOrWhiteSpace(toolName)) return null;
-            DiscoverProjectTools();
             RegisteredTool definition;
-            return ProjectTools.TryGetValue(toolName, out definition) ? definition.CompletionContract : null;
+            return ReadPublishedProjectToolCatalog().ExecutableTools.TryGetValue(toolName, out definition) ? definition.CompletionContract : null;
+        }
+
+        private sealed class ProjectToolCatalogArgs
+        {
+            public string Group { get; set; }
+            public string Keyword { get; set; }
+            public int Limit { get; set; }
+            public string ExpectedCatalogGeneration { get; set; }
+            public string[] ReservedNames { get; set; }
+            public string[] LocalNames { get; set; }
+            public string CursorContext { get; set; }
+            public string CursorToken { get; set; }
+            public string Name { get; set; }
+            public string FallbackName { get; set; }
+        }
+
+        /// <summary>continuation只绑定transport session与listener generation；Tool级identifier不参与stale判定。</summary>
+        private static string ProjectToolCatalogGeneration()
+        {
+            return Sha256Hex(Encoding.UTF8.GetBytes(EditorSessionId() + "\n" + ListenerId + "\n" + CurrentListenerGeneration().ToString(CultureInfo.InvariantCulture)));
         }
 
-        private static string ProjectToolGroupFromName(string name)
+        /// <summary>generation变化时 continuation 必须稳定失败，不能混合两代目录。</summary>
+        private static void RequireProjectToolCatalogGeneration(ProjectToolCatalogArgs args, string generation)
         {
-            if (string.IsNullOrEmpty(name)) return "custom";
-            var dot = name.IndexOf('.');
-            return dot > 0 ? name.Substring(0, dot) : "custom";
+            if (args != null && Utf8ByteCount(args.ExpectedCatalogGeneration) > 128)
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog generation exceeds its bounded string limit.");
+            if (args != null && !string.IsNullOrEmpty(args.ExpectedCatalogGeneration)
+                && !string.Equals(args.ExpectedCatalogGeneration, generation, StringComparison.Ordinal))
+                throw new BridgeCommandException("E_TOOL_CATALOG_CHANGED", "The Tool catalog generation changed before this continuation page was read.", null,
+                    new[] { "Restart this discovery query from its first page against the current Unity generation." });
         }
 
+        /// <summary>package-local names由CLI冻结并传入，Bridge在筛选前执行全registry ownership检查。</summary>
+        private static void RequireNoReservedProjectToolNames(UnityCliToolCatalogSnapshot catalog, ProjectToolCatalogArgs args)
+        {
+            var reservedNames = (args == null ? null : args.ReservedNames) ?? new string[0];
+            if (reservedNames.Length > 4096 || reservedNames.Any(name => string.IsNullOrWhiteSpace(name) || Utf8ByteCount(name) > 256))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog reserved names exceed their bounded item or string limits.");
+            var reserved = new HashSet<string>(reservedNames, StringComparer.Ordinal);
+            var conflict = catalog.Descriptors.Select(tool => tool.Name).FirstOrDefault(reserved.Contains);
+            if (conflict != null)
+                throw new BridgeCommandException("E_TOOL_SCHEMA_CONFLICT", "Tool catalog conflict for " + conflict + ": package-local and live registrations use the same name.",
+                    new Dictionary<string, object> { { "toolName", conflict }, { "reason", "package-local and live registrations use the same name" } },
+                    new[] { "Fix the duplicate Tool registration in the selected Unity project, then retry discovery." });
+        }
+
+        private static IEnumerable<RegisteredToolDescriptor> ProjectToolCatalogDefinitions(UnityCliToolCatalogSnapshot catalog, bool runtimeOnly)
+        {
+            return catalog.Descriptors.Where(definition => !runtimeOnly || definition.Target == "runtime" || definition.Target == "both");
+        }
+
+        private static void RequireProjectToolCatalogInputKeys(UnityCli.Protocol.BridgeRequest request, params string[] allowed)
+        {
+            var input = request.Input as IDictionary<string, object>;
+            if (input == null) throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog input must be an object.");
+            var keys = new HashSet<string>(allowed, StringComparer.Ordinal);
+            var unknown = input.Keys.FirstOrDefault(key => !keys.Contains(key));
+            if (unknown != null) throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog input contains unknown field " + unknown + ".");
+        }
+
+        /// <summary>groups只读取一次published snapshot并返回group/count，不物化descriptor图。</summary>
+        private static object ProjectToolCatalogGroups(UnityCli.Protocol.BridgeRequest request, bool runtimeOnly)
+        {
+            RequireProjectToolCatalogInputKeys(request, "expectedCatalogGeneration", "reservedNames");
+            var catalog = ProjectToolCatalogSnapshotReader.Read();
+            var args = request.DeserializeArgs<ProjectToolCatalogArgs>() ?? new ProjectToolCatalogArgs();
+            RequireNoReservedProjectToolNames(catalog, args);
+            var generation = ProjectToolCatalogGeneration();
+            RequireProjectToolCatalogGeneration(args, generation);
+            var groups = ProjectToolCatalogDefinitions(catalog, runtimeOnly)
+                .GroupBy(definition => definition.Group, StringComparer.Ordinal)
+                .OrderBy(group => group.Key, StringComparer.Ordinal)
+                .Select(group => (object)new Dictionary<string, object> { { "name", group.Key }, { "toolCount", (long)group.Count() } })
+                .ToList();
+            if (groups.Count > 4096)
+                throw new BridgeCommandException("E_TOOL_REGISTRY_UNHEALTHY", "Tool catalog exceeds the bounded group count.", null,
+                    new[] { "Reduce invalid project Tool group fragmentation, then let Unity reload the domain." });
+            var data = new Dictionary<string, object> { { "catalogGeneration", generation }, { "groups", groups } };
+            RequireCatalogDataBudget(data, 2 * 1024 * 1024, "Tool catalog groups exceed the bounded UTF-8 transport size.");
+            return data;
+        }
+
+        /// <summary>summary由目标domain签发opaque continuation；CLI不持有可编辑边界。</summary>
+        private static object ProjectToolCatalogSummary(UnityCli.Protocol.BridgeRequest request, bool runtimeOnly)
+        {
+            RequireProjectToolCatalogInputKeys(request, "group", "keyword", "limit", "expectedCatalogGeneration", "reservedNames",
+                "localNames", "cursorContext", "cursorToken");
+            var summaryInput = request.Input as IDictionary<string, object>;
+            if (!summaryInput.ContainsKey("reservedNames") || !summaryInput.ContainsKey("localNames") || !summaryInput.ContainsKey("cursorContext"))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog summary input is missing its cursor context fields.");
+            var catalog = ProjectToolCatalogSnapshotReader.Read();
+            var args = request.DeserializeArgs<ProjectToolCatalogArgs>() ?? new ProjectToolCatalogArgs();
+            if (args.Limit < 1 || args.Limit > 101)
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog summary limit must be an integer in [1,101].");
+            RequireNoReservedProjectToolNames(catalog, args);
+            var generation = ProjectToolCatalogGeneration();
+            RequireProjectToolCatalogGeneration(args, generation);
+            if (Utf8ByteCount(args.Group) > 256 || Utf8ByteCount(args.Keyword) > 2048)
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog summary filters exceed their bounded UTF-8 string limits.");
+            var tokens = (args.Keyword ?? string.Empty).Split('|').Select(token => token.Trim()).Where(token => token.Length > 0).ToArray();
+            if (tokens.Length > 16 || tokens.Any(token => Utf8ByteCount(token) > 128))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog search accepts at most 16 keywords of at most 128 UTF-8 bytes each.");
+            var matches = ProjectToolCatalogDefinitions(catalog, runtimeOnly)
+                .Where(definition => string.IsNullOrEmpty(args.Group) || string.Equals(definition.Group, args.Group, StringComparison.Ordinal))
+                .Where(definition => tokens.Length == 0 || tokens.Any(token => ProjectToolCatalogMatches(definition, token)))
+                .OrderBy(definition => definition.Name, StringComparer.Ordinal)
+                .ToList();
+            var nativeNames = new HashSet<string>(catalog.Descriptors.Where(definition => definition.ContractProfile != "official-attribute").Select(definition => definition.Name), StringComparer.Ordinal);
+            foreach (var reservedName in args.ReservedNames ?? new string[0]) nativeNames.Add(reservedName);
+
+            var localNames = ValidateCatalogCursorLocalNames(args);
+            var scope = ProjectToolCatalogCursorScope(generation, args, runtimeOnly, localNames);
+            int offset;
+            string boundary;
+            ReadProjectToolCatalogCursor(args.CursorToken, scope, out offset, out boundary);
+            var combinedNames = localNames.Concat(matches.Select(definition => definition.Name)).Distinct(StringComparer.Ordinal).OrderBy(name => name, StringComparer.Ordinal).ToList();
+            if (offset > combinedNames.Count || offset > 0 && !string.Equals(combinedNames[offset - 1], boundary, StringComparison.Ordinal))
+                throw InvalidProjectToolCatalogCursor();
+            var pageNames = combinedNames.Skip(offset).Take(args.Limit).ToList();
+            var pageSet = new HashSet<string>(pageNames, StringComparer.Ordinal);
+            var tools = matches.Where(definition => pageSet.Contains(definition.Name))
+                .Select(definition => (object)ProjectToolRoutingSummaryData(definition, runtimeOnly, nativeNames)).ToList();
+            return BoundSignedCatalogSummaryData(generation, matches.Count, combinedNames, offset, pageNames, tools, scope);
+        }
+
+        /// <summary>签名页在序列化预算内同步裁剪pageNames与live summaries，token指向真实末项。</summary>
+        private static object BoundSignedCatalogSummaryData(
+            string generation, int liveTotal, List<string> combinedNames, int offset, List<string> pageNames,
+            List<object> tools, string scope)
+        {
+            Dictionary<string, object> data;
+            while (true)
+            {
+                var end = offset + pageNames.Count;
+                var boundary = end > 0 ? combinedNames[end - 1] : string.Empty;
+                data = new Dictionary<string, object>
+                {
+                    { "catalogGeneration", generation }, { "total", (long)liveTotal },
+                    { "hasMore", end < combinedNames.Count }, { "tools", tools },
+                    { "pageNames", pageNames.Cast<object>().ToList() },
+                    { "continuationToken", SignProjectToolCatalogCursor(scope, end, boundary) }
+                };
+                if (CatalogDataUtf8Bytes(data) <= 256 * 1024) return data;
+                if (pageNames.Count == 0)
+                    throw new BridgeCommandException("E_TOOL_REGISTRY_UNHEALTHY", "Tool catalog summary cannot fit the bounded UTF-8 transport size.");
+                var removed = pageNames[pageNames.Count - 1];
+                pageNames.RemoveAt(pageNames.Count - 1);
+                var toolIndex = tools.FindLastIndex(value => string.Equals(((Dictionary<string, object>)value)["name"] as string, removed, StringComparison.Ordinal));
+                if (toolIndex >= 0) tools.RemoveAt(toolIndex);
+            }
+        }
+
+        /// <summary>校验CLI提供的已筛选local名称只来自reserved ownership集合。</summary>
+        private static List<string> ValidateCatalogCursorLocalNames(ProjectToolCatalogArgs args)
+        {
+            var values = (args.LocalNames ?? new string[0]).ToList();
+            if (values.Count > 4096 || values.Any(value => string.IsNullOrWhiteSpace(value) || Utf8ByteCount(value) > 256)
+                || !values.SequenceEqual(values.Distinct(StringComparer.Ordinal).OrderBy(value => value, StringComparer.Ordinal)))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog local names must be a bounded ordinally sorted set.");
+            var reserved = new HashSet<string>(args.ReservedNames ?? new string[0], StringComparer.Ordinal);
+            if (values.Any(value => !reserved.Contains(value)))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog local names must be a subset of reserved package-local names.");
+            if (Utf8ByteCount(args.CursorContext) != 64 || args.CursorContext.Any(value => !Uri.IsHexDigit(value)))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog cursor context is invalid.");
+            return values;
+        }
+
+        /// <summary>把目标generation、query和local投影视图绑定到签名scope。</summary>
+        private static string ProjectToolCatalogCursorScope(string generation, ProjectToolCatalogArgs args, bool runtimeOnly, List<string> localNames)
+        {
+            return Sha256Hex(Encoding.UTF8.GetBytes(generation + "\n" + (runtimeOnly ? "runtime" : "editor") + "\n" + args.CursorContext + "\n"
+                + (args.Group ?? string.Empty) + "\n" + (args.Keyword ?? string.Empty) + "\n"
+                + string.Join("\n", localNames) + "\n--reserved--\n" + string.Join("\n", args.ReservedNames ?? new string[0])));
+        }
+
+        /// <summary>验证opaque token并恢复目标签发的序号与前页边界。</summary>
+        private static void ReadProjectToolCatalogCursor(string token, string scope, out int offset, out string boundary)
+        {
+            offset = 0;
+            boundary = string.Empty;
+            if (string.IsNullOrEmpty(token)) return;
+            if (Utf8ByteCount(token) > 8192) throw InvalidProjectToolCatalogCursor();
+            try
+            {
+                var parts = token.Split('.');
+                if (parts.Length != 2) throw InvalidProjectToolCatalogCursor();
+                var payloadBytes = FromBase64Url(parts[0]);
+                var signature = FromBase64Url(parts[1]);
+                byte[] expected;
+                using (var hmac = new HMACSHA256(projectToolCatalogCursorSecret)) expected = hmac.ComputeHash(Encoding.UTF8.GetBytes(parts[0]));
+                if (!FixedTimeEqual(signature, expected)) throw InvalidProjectToolCatalogCursor();
+                var fields = Encoding.UTF8.GetString(payloadBytes).Split('\n');
+                int parsedOffset;
+                if (fields.Length != 3 || !string.Equals(fields[0], scope, StringComparison.Ordinal)
+                    || !int.TryParse(fields[1], NumberStyles.None, CultureInfo.InvariantCulture, out parsedOffset) || parsedOffset < 0)
+                    throw InvalidProjectToolCatalogCursor();
+                offset = parsedOffset;
+                boundary = Encoding.UTF8.GetString(Convert.FromBase64String(fields[2]));
+                if (Utf8ByteCount(boundary) > 256 || (offset == 0) != string.IsNullOrEmpty(boundary))
+                    throw InvalidProjectToolCatalogCursor();
+            }
+            catch (BridgeCommandException) { throw; }
+            catch { throw InvalidProjectToolCatalogCursor(); }
+        }
+
+        /// <summary>使用当前domain secret签发不可由CLI改写的continuation。</summary>
+        private static string SignProjectToolCatalogCursor(string scope, int offset, string boundary)
+        {
+            var payloadText = scope + "\n" + offset.ToString(CultureInfo.InvariantCulture) + "\n"
+                + Convert.ToBase64String(Encoding.UTF8.GetBytes(boundary ?? string.Empty));
+            var payload = ToBase64Url(Encoding.UTF8.GetBytes(payloadText));
+            byte[] signature;
+            using (var hmac = new HMACSHA256(projectToolCatalogCursorSecret)) signature = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
+            return payload + "." + ToBase64Url(signature);
+        }
+
+        /// <summary>统一返回可机器分支的cursor拒绝错误。</summary>
+        private static BridgeCommandException InvalidProjectToolCatalogCursor()
+        {
+            return new BridgeCommandException("E_DISCOVERY_CURSOR_INVALID", "The target rejected an altered or cross-query discovery continuation.", null,
+                new[] { "Restart this exact discovery query from its first page." });
+        }
+
+        /// <summary>secret只活在当前domain内，reload后旧token自然失效。</summary>
+        private static byte[] CreateProjectToolCatalogCursorSecret()
+        {
+            var bytes = new byte[32];
+            using (var random = RandomNumberGenerator.Create()) random.GetBytes(bytes);
+            return bytes;
+        }
+
+        /// <summary>编码URL安全token片段。</summary>
+        private static string ToBase64Url(byte[] value)
+        {
+            return Convert.ToBase64String(value).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+        }
+
+        /// <summary>解码URL安全token片段。</summary>
+        private static byte[] FromBase64Url(string value)
+        {
+            var normalized = value.Replace('-', '+').Replace('_', '/');
+            normalized = normalized.PadRight(normalized.Length + (4 - normalized.Length % 4) % 4, '=');
+            return Convert.FromBase64String(normalized);
+        }
+
+        /// <summary>常量步数比较签名，避免提前返回泄露首个差异位置。</summary>
+        private static bool FixedTimeEqual(byte[] left, byte[] right)
+        {
+            if (left == null || right == null || left.Length != right.Length) return false;
+            var difference = 0;
+            for (var index = 0; index < left.Length; index++) difference |= left[index] ^ right[index];
+            return difference == 0;
+        }
+
+        /// <summary>所有catalog string bound统一按wire UTF-8字节计算。</summary>
+        private static int Utf8ByteCount(string value)
+        {
+            return Encoding.UTF8.GetByteCount(value ?? string.Empty);
+        }
+
+        /// <summary>以真实Bridge serializer计算完整data大小。</summary>
+        private static int CatalogDataUtf8Bytes(object data)
+        {
+            return Encoding.UTF8.GetByteCount(UnityCliSerializer.Serialize(data));
+        }
+
+        /// <summary>完整data超出consumer预算时在返回前失败。</summary>
+        private static void RequireCatalogDataBudget(object data, int maximumBytes, string message)
+        {
+            if (CatalogDataUtf8Bytes(data) > maximumBytes) throw new BridgeCommandException("E_TOOL_REGISTRY_UNHEALTHY", message);
+        }
+
+        private static bool ProjectToolCatalogMatches(RegisteredToolDescriptor definition, string token)
+        {
+            return (definition.Name ?? string.Empty).IndexOf(token, StringComparison.OrdinalIgnoreCase) >= 0
+                || (definition.Summary ?? string.Empty).IndexOf(token, StringComparison.OrdinalIgnoreCase) >= 0
+                || (definition.Description ?? string.Empty).IndexOf(token, StringComparison.OrdinalIgnoreCase) >= 0
+                || (definition.Group ?? string.Empty).IndexOf(token, StringComparison.OrdinalIgnoreCase) >= 0;
+        }
+
+        /// <summary>exact describe只读取一次published snapshot；native未命中时可返回一份指定fallback descriptor。</summary>
+        private static object ProjectToolCatalogDescribe(UnityCli.Protocol.BridgeRequest request, bool runtimeOnly)
+        {
+            if (runtimeOnly) RequireProjectToolCatalogInputKeys(request, "name");
+            else RequireProjectToolCatalogInputKeys(request, "name", "fallbackName");
+            var catalog = ProjectToolCatalogSnapshotReader.Read();
+            var args = request.DeserializeArgs<ProjectToolCatalogArgs>() ?? new ProjectToolCatalogArgs();
+            if (string.IsNullOrWhiteSpace(args.Name) || Utf8ByteCount(args.Name) > 256)
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog describe name is required and must not exceed 256 UTF-8 bytes.");
+            if (args.FallbackName != null && (string.IsNullOrWhiteSpace(args.FallbackName) || Utf8ByteCount(args.FallbackName) > 256
+                || string.Equals(args.Name, args.FallbackName, StringComparison.Ordinal)))
+                throw new BridgeCommandException("E_SCHEMA_INVALID", "Catalog describe fallbackName must be distinct and must not exceed 256 UTF-8 bytes.");
+            var generation = ProjectToolCatalogGeneration();
+            Func<RegisteredToolDescriptor, bool> availableForTarget = tool => !runtimeOnly || tool.Target == "runtime" || tool.Target == "both";
+            var definition = catalog.Descriptors.FirstOrDefault(tool => string.Equals(tool.Name, args.Name, StringComparison.Ordinal) && availableForTarget(tool));
+            if (definition == null && args.FallbackName != null)
+                definition = catalog.Descriptors.FirstOrDefault(tool => string.Equals(tool.Name, args.FallbackName, StringComparison.Ordinal) && availableForTarget(tool));
+            var found = definition != null;
+            var result = new Dictionary<string, object> { { "catalogGeneration", generation }, { "found", found } };
+            if (found)
+            {
+                result["descriptor"] = ProjectToolDescriptorData(definition);
+            }
+            if (CatalogDataUtf8Bytes(result) > 3 * 1024 * 1024)
+                throw new BridgeCommandException("E_TOOL_REGISTRY_UNHEALTHY", "Exact Tool descriptor exceeds the bounded UTF-8 transport size.", null,
+                    new[] { "Reduce the Tool schema or examples, then let Unity reload the domain." });
+            return result;
+        }
+
+        private static Dictionary<string, object> ProjectToolRoutingSummaryData(RegisteredToolDescriptor definition, bool runtimeOnly, HashSet<string> nativeNames)
+        {
+            var commandName = definition.Name;
+            if (definition.ContractProfile == "official-attribute" && definition.Name.StartsWith(OfficialAttributeToolPrefix, StringComparison.Ordinal))
+            {
+                var originalName = definition.Name.Substring(OfficialAttributeToolPrefix.Length);
+                if (!nativeNames.Contains(originalName)) commandName = originalName;
+            }
+            var available = ProjectToolAvailableForCatalog(definition, runtimeOnly);
+            var data = new Dictionary<string, object>
+            {
+                { "name", definition.Name }, { "summary", definition.Summary }, { "group", definition.Group },
+                { "target", definition.Target }, { "contractProfile", definition.ContractProfile },
+                { "commandName", commandName }
+            };
+            if (!available)
+            {
+                data["available"] = false;
+                data["unavailableReason"] = ProjectToolUnavailableForCatalog(definition, runtimeOnly);
+            }
+            return data;
+        }
+
+        private static bool ProjectToolAvailableForCatalog(RegisteredToolDescriptor definition, bool runtimeOnly)
+        {
+            return runtimeOnly ? playModeReady : ToolAvailableNow(definition);
+        }
+
+        private static string ProjectToolUnavailableForCatalog(RegisteredToolDescriptor definition, bool runtimeOnly)
+        {
+            return runtimeOnly && !playModeReady
+                ? "E_RUNTIME_NOT_READY: Enter Play Mode before executing this Tool."
+                : ToolUnavailableReason(definition);
+        }
+
+        private static bool IsProjectToolCatalogReadCommand(string command)
+        {
+            return command == "project-tool.health" || command == "project-tool.groups" || command == "project-tool.summary" || command == "project-tool.describe" || command == "project-tool.list"
+                || command == "runtime-tool.groups" || command == "runtime-tool.summary" || command == "runtime-tool.describe" || command == "runtime-tool.list";
+        }
+
+        private static object ProjectToolGroups(UnityCli.Protocol.BridgeRequest request) { return ProjectToolCatalogGroups(request, false); }
+        private static object ProjectToolSummary(UnityCli.Protocol.BridgeRequest request) { return ProjectToolCatalogSummary(request, false); }
+        private static object ProjectToolDescribe(UnityCli.Protocol.BridgeRequest request) { return ProjectToolCatalogDescribe(request, false); }
+        private static object RuntimeToolGroups(UnityCli.Protocol.BridgeRequest request) { InitializeRuntimeExecutor(); return ProjectToolCatalogGroups(request, true); }
+        private static object RuntimeToolSummary(UnityCli.Protocol.BridgeRequest request) { InitializeRuntimeExecutor(); return ProjectToolCatalogSummary(request, true); }
+        private static object RuntimeToolDescribe(UnityCli.Protocol.BridgeRequest request) { InitializeRuntimeExecutor(); return ProjectToolCatalogDescribe(request, true); }
+
+        /// <summary>完整descriptor导出仅供显式doctor/static capture，不进入公开discovery。</summary>
         private static object ProjectToolList(UnityCli.Protocol.BridgeRequest request)
         {
-            DiscoverProjectTools();
+            var catalog = ReadPublishedProjectToolCatalogSnapshot();
             return new Dictionary<string, object>
             {
-                { "tools", ProjectTools.Values.OrderBy(tool => tool.Name, StringComparer.Ordinal).Select(ProjectToolDescriptorData).ToList() },
+                { "tools", catalog.Descriptors.Select(ProjectToolDescriptorData).ToList() },
                 { "logPath", LogPath() }
             };
         }
@@ -349,33 +739,21 @@ namespace UnityCli
         {
             public string Name { get; set; }
             [UnityCliAnyJson] public object Input { get; set; }
-            public string ExpectedDescriptorFingerprint { get; set; }
             public string ArtifactDir { get; set; }
             public string ProjectPath { get; set; }
         }
 
         private static async ValueTask<object> ProjectToolRun(UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
         {
-            DiscoverProjectTools();
+            var catalog = ReadPublishedProjectToolCatalog();
             var args = request.DeserializeArgs<ProjectToolRunArgs>();
             var name = args.Name;
-            if (string.IsNullOrEmpty(name) || !ProjectTools.ContainsKey(name))
+            if (string.IsNullOrEmpty(name) || !catalog.ExecutableTools.ContainsKey(name))
             {
                 throw new BridgeCommandException("E_TOOL_NOT_FOUND", "Tool not found: " + name, "Run unitycli tools group --instance <id|projectPath|alias> or tools search <keyword> to inspect the connected instance catalog.");
             }
 
-            var definition = ProjectTools[name];
-            // 门禁前刷新 live handler+descriptor 指纹，旧 discovery proof 在 domain reload/descriptor 变化后必须失效。
-            var fingerprintCheck = RefreshProjectToolFingerprint(definition);
-            if (!string.IsNullOrEmpty(args.ExpectedDescriptorFingerprint)
-                && !string.Equals(args.ExpectedDescriptorFingerprint, definition.Fingerprint, StringComparison.Ordinal))
-            {
-                throw new BridgeCommandException(
-                    "E_TOOL_DESCRIPTOR_CHANGED",
-                    "The Tool descriptor changed after discovery: " + name,
-                    new Dictionary<string, object> { { "toolName", name }, { "expectedFingerprint", args.ExpectedDescriptorFingerprint }, { "actualFingerprint", definition.Fingerprint } },
-                    new[] { "Run tools describe again against the selected Unity generation before constructing a new request." });
-            }
+            var definition = catalog.ExecutableTools[name];
             if (EditorApplication.isPlaying && string.Equals(definition.PlayModeSupport, "editor-only", StringComparison.OrdinalIgnoreCase))
             {
                 throw new BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE",
@@ -410,11 +788,6 @@ namespace UnityCli
                     new[] { "Use runtime-tool.run <name> or tools run <name> with a runtime target to execute this tool in Play Mode." });
             }
             var dryRun = request.Execution != null && request.Execution.DryRun == true;
-            if (fingerprintCheck.Blocked)
-            {
-                WriteLog("custom_tool_fingerprint_blocked requestId=" + request.RequestId + " name=" + name + " expected=" + fingerprintCheck.Expected + " actual=" + fingerprintCheck.Actual);
-                throw new BridgeCommandException("E_TOOL_FINGERPRINT_MISMATCH", fingerprintCheck.Message, ProjectToolFingerprintDetails(definition), ProjectToolFingerprintRePinSteps(definition));
-            }
             var timeoutMs = request.ExecutionTimeoutMs(definition.DefaultTimeoutMs, definition.MaxTimeoutMs);
 
             var inputJson = request.RawJsonArg("input") ?? "{}";
@@ -425,11 +798,11 @@ namespace UnityCli
             object result;
             object parsedInput;
             UnityCliProjectToolContext executionContext = null;
+            using (var toolTimeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken))
+            {
             try
             {
                 WriteLog("custom_tool_run requestId=" + request.RequestId + " name=" + name + " timeoutMs=" + timeoutMs.ToString(CultureInfo.InvariantCulture));
-                using (var toolTimeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken))
-                {
                     toolTimeout.CancelAfter(timeoutMs);
                     parsedInput = UnityCliSerializer.Deserialize(inputJson, definition.RequestType);
                     var effectPreparation = PrepareToolEffect(request, definition.CompletionContract, parsedInput);
@@ -448,7 +821,6 @@ namespace UnityCli
                     result = await definition.InvokeAsync(parsedInput, executionContext, toolTimeout.Token);
                     if (toolTimeout.IsCancellationRequested && !executionContext.EffectCommitted)
                         throw new OperationCanceledException(toolTimeout.Token);
-                }
             }
             catch (BridgeCommandException bce)
             {
@@ -480,6 +852,12 @@ namespace UnityCli
                     throw PostEffectExecutionTimeout(name, "invoke", ProjectToolFailureReason(definition, inner.GetType().Name + ": " + inner.Message));
                 throw new BridgeCommandException("E_TOOL_EXECUTION_FAILED", inner.GetType().Name + ": " + inner.Message, "Check Unity Console and UnityCliBridge.log with the returned requestId.");
             }
+            catch (UnityCliRequestBudgetExceededException exception)
+            {
+                if (executionContext != null && executionContext.EffectCommitted)
+                    throw PostEffectExecutionTimeout(name, "request-budget", exception.Message);
+                throw RequestBudgetExceeded(name, exception.Dimension);
+            }
             catch (OperationCanceledException)
             {
                 if (executionContext != null && executionContext.EffectCommitted)
@@ -496,7 +874,10 @@ namespace UnityCli
             // method 返回后仍可能在序列化 getter、schema 或 completion driver 中失败；整个 postcondition 区域必须服从同一 effect 边界。
             try
             {
-                var outputJson = UnityCliSerializer.Serialize(result);
+                var terminalBudget = executionContext.ReadBudget ?? executionContext.UseReadBudget();
+                terminalBudget.CheckpointOrThrow();
+                var outputJson = UnityCliSerializer.Serialize(result, terminalBudget, toolTimeout.Token);
+                terminalBudget.CheckpointOrThrow();
                 var outputError = ValidateProjectToolOutput(definition, outputJson);
                 if (outputError != null)
                 {
@@ -506,9 +887,14 @@ namespace UnityCli
                         new Dictionary<string, object> { { "toolName", definition.Name }, { "path", outputError.Path }, { "expected", outputError.Expected }, { "actual", outputError.Actual } },
                         new[] { "Fix the Tool result DTO or completion driver before retrying." });
                 }
+                terminalBudget.CheckpointOrThrow();
                 var terminalData = CompleteProjectToolSuccess(request, definition, result);
+                terminalBudget.CheckpointOrThrow();
                 RecordToolCompletionEvidence(request, definition, result, terminalData);
-                return terminalData;
+                terminalBudget.CheckpointOrThrow();
+                var terminalJson = SerializeTerminalSuccess(request.RequestId, terminalData, terminalBudget, toolTimeout.Token);
+                terminalBudget.CheckpointOrThrow();
+                return new SerializedBridgeEnvelope(terminalJson);
             }
             catch (BridgeCommandException exception)
             {
@@ -517,6 +903,12 @@ namespace UnityCli
                     throw PostEffectExecutionTimeout(name, "postcondition", ProjectToolFailureReason(definition, exception.Code + ": " + exception.Message));
                 throw;
             }
+            catch (UnityCliRequestBudgetExceededException exception)
+            {
+                if (executionContext != null && executionContext.EffectCommitted)
+                    throw PostEffectExecutionTimeout(name, "request-budget", exception.Message);
+                throw RequestBudgetExceeded(name, exception.Dimension);
+            }
             catch (Exception exception)
             {
                 if (executionContext != null && executionContext.EffectCommitted)
@@ -527,6 +919,34 @@ namespace UnityCli
                     new Dictionary<string, object> { { "toolName", definition.Name }, { "stage", "postcondition" } },
                     new[] { "Fix the Tool result DTO or completion driver before retrying." });
             }
+            }
+        }
+
+        /// <summary>最终 envelope 的自描述字节数最多经过8次定点收敛，且每次都服从同一 deadline 与预算。</summary>
+        internal static string SerializeTerminalSuccess(string requestId, object terminalData, UnityCliRequestBudget budget, CancellationToken cancellationToken)
+        {
+            if (budget == null) throw new ArgumentNullException("budget");
+            for (var attempt = 0; attempt < 8; attempt++)
+            {
+                budget.CheckpointOrThrow();
+                long actualBytes;
+                var json = UnityCliSerializer.Serialize(
+                    UnityCli.Protocol.ProtocolEnvelopeFactory.Success(requestId, terminalData),
+                    budget,
+                    cancellationToken,
+                    out actualBytes);
+                if (actualBytes == budget.ActualSerializedUtf8Bytes) return json;
+                budget.ObserveActualSerializedUtf8Bytes(actualBytes);
+            }
+
+            throw new InvalidOperationException("Final envelope UTF-8 byte accounting did not converge.");
+        }
+
+        /// <summary>成功 Tool 已在自身 deadline 与预算内完成最终 envelope 序列化。</summary>
+        private sealed class SerializedBridgeEnvelope
+        {
+            internal SerializedBridgeEnvelope(string json) { Json = json; }
+            internal string Json { get; private set; }
         }
 
         /// <summary>内部 raw discovery 需要 completion contract；公开投影与 static capture 会移除此字段。</summary>
@@ -546,6 +966,31 @@ namespace UnityCli
             };
         }
 
+        private static Dictionary<string, object> CompletionContractData(PublishedToolCompletionContract contract)
+        {
+            return new Dictionary<string, object>
+            {
+                { "executionClass", contract.ExecutionClass },
+                { "completionPredicate", contract.CompletionPredicate },
+                { "proofSource", contract.ProofSource },
+                { "reloadPolicy", contract.ReloadPolicy },
+                { "timeoutError", contract.TimeoutError },
+                { "outcomeUnknownPolicy", contract.OutcomeUnknownPolicy },
+                { "completionDriverId", contract.CompletionDriverId },
+                { "journalPolicy", contract.JournalPolicy },
+                { "mutation", contract.Mutation }
+            };
+        }
+
+        private static BridgeCommandException RequestBudgetExceeded(string toolName, string dimension)
+        {
+            return new BridgeCommandException(
+                "E_REQUEST_BUDGET_EXCEEDED",
+                "Tool " + toolName + " exhausted its request-wide Unity main-thread budget before a complete result was available.",
+                new Dictionary<string, object> { { "toolName", toolName }, { "dimension", dimension } },
+                new[] { "Retry with a narrower selector or continue from the returned continuation when available." });
+        }
+
         /// <summary>effect 后无法确认终态的异常统一收敛为执行超时。</summary>
         private static BridgeCommandException PostEffectExecutionTimeout(string toolName, string stage, string reason)
         {
@@ -556,7 +1001,7 @@ namespace UnityCli
                 new[] { "Inspect the affected business state before submitting a new request." });
         }
 
-        private static Dictionary<string, object> ProjectToolDescriptorData(RegisteredTool definition)
+        private static Dictionary<string, object> ProjectToolDescriptorData(RegisteredToolDescriptor definition)
         {
             var data = new Dictionary<string, object>
             {
@@ -567,22 +1012,21 @@ namespace UnityCli
                 { "supportsDryRun", definition.SupportsDryRun },
                 { "contractProfile", definition.ContractProfile },
                 { "target", definition.Target }, { "availabilityScope", definition.AvailabilityScope }, { "playModeSupport", definition.PlayModeSupport },
-                { "examples", definition.Examples },
+                { "examples", definition.CloneExamples() },
                 { "defaultTimeoutMs", definition.DefaultTimeoutMs },
                 { "completionContract", CompletionContractData(definition.CompletionContract) },
-                { "internalDescriptorFingerprint", definition.Fingerprint },
                 { "available", ToolAvailableNow(definition) }
             };
             if (!(bool)data["available"])
                 data["unavailableReason"] = ToolUnavailableReason(definition);
-            if (definition.SideEffects != null && definition.SideEffects.Length > 0) data["sideEffects"] = definition.SideEffects;
-            if (definition.Permissions != null && definition.Permissions.Length > 0) data["permissions"] = definition.Permissions;
-            if (definition.RequiresPackages != null && definition.RequiresPackages.Length > 0) data["requiresPackages"] = definition.RequiresPackages;
+            if (definition.SideEffects.Count > 0) data["sideEffects"] = definition.SideEffects.ToArray();
+            if (definition.Permissions.Count > 0) data["permissions"] = definition.Permissions.ToArray();
+            if (definition.RequiresPackages.Count > 0) data["requiresPackages"] = definition.RequiresPackages.ToArray();
             return data;
         }
 
         /// <summary>目录始终显示 Tool；available 只描述当前 mode/API 状态，不参与过滤。</summary>
-        private static bool ToolAvailableNow(RegisteredTool definition)
+        private static bool ToolAvailableNow(RegisteredToolDescriptor definition)
         {
             if (BuildProfileApiRequired(definition) && BuildToolSupport.BuildProfileType() == null)
                 return false;
@@ -596,7 +1040,7 @@ namespace UnityCli
         }
 
         /// <summary>按执行门禁优先级返回与 available=false 对应的稳定原因。</summary>
-        private static string ToolUnavailableReason(RegisteredTool definition)
+        private static string ToolUnavailableReason(RegisteredToolDescriptor definition)
         {
             if (definition.Target == "runtime" || definition.PlayModeSupport == "runtime-only")
                 return "E_RUNTIME_NOT_READY: Enter Play Mode before executing this Tool.";
@@ -610,14 +1054,14 @@ namespace UnityCli
         }
 
         /// <summary>这些 Tool 在所有版本注册；版本差异仅通过 availability 与执行错误表达。</summary>
-        private static bool BuildProfileApiRequired(RegisteredTool definition)
+        private static bool BuildProfileApiRequired(RegisteredToolDescriptor definition)
         {
             return definition.Name == "build.profile.create"
                 || definition.Name == "build.profile.modify"
                 || definition.Name == "build.profile.switch";
         }
 
-        private static bool EditorElementCaptureApiRequired(RegisteredTool definition)
+        private static bool EditorElementCaptureApiRequired(RegisteredToolDescriptor definition)
         {
             return definition.Name == "screenshot.editor-element";
         }
@@ -638,301 +1082,6 @@ namespace UnityCli
             return new Dictionary<string, object> { { "result", result } };
         }
 
-        private sealed class ProjectToolFingerprintCheck
-        {
-            public bool Blocked;
-            public string Expected;
-            public string Actual;
-            public string Message;
-        }
-
-        private sealed class ProjectToolPinnedFingerprint
-        {
-            public string Owner;
-            public string Value;
-            public string Algorithm;
-            public string Format;
-            public string Sha256;
-            public bool HardMismatch;
-        }
-
-        private static ProjectToolFingerprintCheck RefreshProjectToolFingerprint(RegisteredTool definition)
-        {
-            var descriptor = ProjectToolDescriptorFingerprintMaterial(definition);
-            definition.DescriptorSha256 = Sha256Hex(descriptor);
-            definition.HandlerSha256 = Sha256Hex(ProjectToolHandlerFingerprintMaterial(definition));
-            definition.Fingerprint = Sha256Hex(ProjectToolFingerprintAlgorithm + "\nhandler=" + definition.HandlerSha256 + "\ndescriptor=" + definition.DescriptorSha256);
-
-            ProjectToolPinnedFingerprint pin;
-            if (string.Equals(definition.Ownership, "project", StringComparison.Ordinal) && !string.IsNullOrEmpty(definition.PinnedFingerprint))
-            {
-                pin = ParseProjectToolPinnedFingerprint("descriptor", definition.PinnedFingerprint);
-            }
-            else if (string.Equals(definition.Ownership, "project", StringComparison.Ordinal))
-            {
-                var baseline = LoadProjectToolExpectedFingerprint(definition.Name);
-                if (string.IsNullOrEmpty(baseline))
-                {
-                    // 首次 project baseline 只能写入携带算法的 v2 pin，无算法 pin 绝不生成。
-                    baseline = FormatProjectToolFingerprint(definition.Fingerprint);
-                    SaveProjectToolExpectedFingerprint(definition.Name, baseline);
-                }
-                pin = ParseProjectToolPinnedFingerprint("project-baseline", baseline);
-            }
-            else
-            {
-                // Built-in 与 Extension 的 expected 由当前安装包生成，不写项目 baseline。
-                pin = ParseProjectToolPinnedFingerprint("installed-package", FormatProjectToolFingerprint(definition.Fingerprint));
-            }
-
-            definition.PinnedFingerprintOwner = pin.Owner;
-            definition.PinnedFingerprintAlgorithm = pin.Algorithm;
-            definition.PinnedFingerprintFormat = pin.Format;
-            definition.ExpectedFingerprint = pin.Value;
-            var matches = !pin.HardMismatch && string.Equals(pin.Sha256, definition.Fingerprint, StringComparison.OrdinalIgnoreCase);
-            // 任一 pin 格式、算法或内容不匹配都使用同一阻断路径。
-            definition.FingerprintStatus = matches ? "match" : "blocked";
-            definition.FingerprintMessage = matches
-                ? "Custom tool fingerprint matches handler code + descriptor."
-                : pin.HardMismatch
-                    ? "Custom tool fingerprint pin uses an unsupported algorithm or format and must be re-pinned."
-                    : "Custom tool fingerprint content differs from its v2 pin.";
-            return new ProjectToolFingerprintCheck
-            {
-                Blocked = !matches,
-                Expected = definition.ExpectedFingerprint,
-                Actual = definition.Fingerprint,
-                Message = definition.FingerprintMessage
-            };
-        }
-
-        /// <summary>解析 project Tool pin；裸 SHA、未知算法和畸形值都不能被当作 v2 expected。</summary>
-        private static ProjectToolPinnedFingerprint ParseProjectToolPinnedFingerprint(string owner, string value)
-        {
-            var pin = new ProjectToolPinnedFingerprint { Owner = owner, Value = value ?? string.Empty, Format = "malformed" };
-            var match = Regex.Match(pin.Value, "^([^:]+):([0-9a-fA-F]{64})$");
-            if (!match.Success)
-            {
-                pin.Format = Regex.IsMatch(pin.Value, "^[0-9a-fA-F]{64}$") ? "bare-sha256" : "malformed";
-                pin.Algorithm = pin.Format == "bare-sha256" ? "none" : "invalid";
-                pin.HardMismatch = true;
-                return pin;
-            }
-            pin.Algorithm = match.Groups[1].Value;
-            pin.Sha256 = match.Groups[2].Value.ToLowerInvariant();
-            pin.Format = string.Equals(pin.Algorithm, ProjectToolFingerprintAlgorithm, StringComparison.Ordinal) ? "valid-v2" : "algorithm-mismatch";
-            pin.HardMismatch = !string.Equals(pin.Algorithm, ProjectToolFingerprintAlgorithm, StringComparison.Ordinal);
-            return pin;
-        }
-
-        private static string FormatProjectToolFingerprint(string sha256)
-        {
-            return ProjectToolFingerprintAlgorithm + ":" + (sha256 ?? string.Empty).ToLowerInvariant();
-        }
-
-
-        private static string LoadProjectToolExpectedFingerprint(string name)
-        {
-            try
-            {
-                var path = ProjectToolExpectedFingerprintPath(name);
-                return File.Exists(path) ? File.ReadAllText(path).Trim() : null;
-            }
-            catch (Exception exception)
-            {
-                WriteLog("custom_tool_fingerprint_baseline_read_failed name=" + name + " error=" + exception.GetType().Name + ": " + exception.Message);
-                return null;
-            }
-        }
-
-        private static void SaveProjectToolExpectedFingerprint(string name, string fingerprint)
-        {
-            try
-            {
-                var path = ProjectToolExpectedFingerprintPath(name);
-                Directory.CreateDirectory(Path.GetDirectoryName(path));
-                File.WriteAllText(path, fingerprint ?? string.Empty);
-            }
-            catch (Exception exception)
-            {
-                WriteLog("custom_tool_fingerprint_baseline_write_failed name=" + name + " error=" + exception.GetType().Name + ": " + exception.Message);
-            }
-        }
-
-        private static string ProjectToolExpectedFingerprintPath(string name)
-        {
-            return Path.Combine(UnityCliTempRoot(), "fingerprints", "tools", SafeProjectToolFingerprintFileName(name) + ".sha256");
-        }
-
-        private static string SafeProjectToolFingerprintFileName(string name)
-        {
-            return Regex.Replace(name ?? "project-tool", "[^A-Za-z0-9_.-]", "_");
-        }
-
-        private static string ProjectToolDescriptorFingerprintMaterial(RegisteredTool definition)
-        {
-            return "name=" + (definition.Name ?? string.Empty)
-                + "\nsummary=" + (definition.Summary ?? string.Empty)
-                + "\ndescription=" + (definition.Description ?? string.Empty)
-                + "\ngroup=" + (definition.Group ?? string.Empty)
-                + "\ninputSchema=" + NormalizeFingerprintJson(definition.InputSchema)
-                + "\noutputSchema=" + NormalizeFingerprintJson(definition.OutputSchema)
-                + "\ndestructiveHint=" + Bool(definition.DestructiveHint)
-                + "\nsupportsDryRun=" + Bool(definition.SupportsDryRun)
-                + "\nsideEffects=" + string.Join(",", (definition.SideEffects ?? new string[0]).OrderBy(value => value, StringComparer.Ordinal).ToArray())
-                + "\npermissions=" + string.Join(",", (definition.Permissions ?? new string[0]).OrderBy(value => value, StringComparer.Ordinal).ToArray())
-                + "\nrequiresPackages=" + string.Join(",", (definition.RequiresPackages ?? new string[0]).OrderBy(value => value, StringComparer.Ordinal).ToArray())
-                + "\ntarget=" + (definition.Target ?? string.Empty)
-                + "\navailabilityScope=" + (definition.AvailabilityScope ?? string.Empty)
-                + "\nplayModeSupport=" + (definition.PlayModeSupport ?? string.Empty)
-                + "\ncontractProfile=" + (definition.ContractProfile ?? string.Empty)
-                + "\ndefaultTimeoutMs=" + definition.DefaultTimeoutMs.ToString(CultureInfo.InvariantCulture)
-                + "\nmaxTimeoutMs=" + definition.MaxTimeoutMs.ToString(CultureInfo.InvariantCulture)
-                + "\nrequiredInput=" + string.Join(",", (definition.RequiredInput ?? new string[0]).OrderBy(value => value, StringComparer.Ordinal).ToArray())
-                + "\nexamples=" + NormalizeFingerprintJson(UnityCliSerializer.Serialize(definition.Examples ?? Array.Empty<ToolExample>()))
-                + "\ncompletion=" + CompletionFingerprintMaterial(definition.CompletionContract)
-                + "\ndescriptorSource=" + (definition.DescriptorSource ?? string.Empty);
-        }
-
-        /// <summary>把 sealed completion contract 纳入 descriptor integrity proof。</summary>
-        private static string CompletionFingerprintMaterial(UnityCliToolCompletionContract contract)
-        {
-            if (contract == null) return string.Empty;
-            return string.Join("|", new[]
-            {
-                contract.ExecutionClass, contract.CompletionPredicate, contract.ProofSource,
-                contract.ReloadPolicy, contract.TimeoutError, contract.OutcomeUnknownPolicy,
-                contract.CompletionDriverId, contract.JournalPolicy, contract.Mutation ? "mutation" : "read-only"
-            }.Select(value => value ?? string.Empty).ToArray());
-        }
-
-        private static string NormalizeProjectToolPlayModeSupport(string value, string target)
-        {
-            if (string.Equals(value, "supported", StringComparison.OrdinalIgnoreCase)) return "supported";
-            if (string.Equals(value, "runtime-only", StringComparison.OrdinalIgnoreCase)) return "runtime-only";
-            if (string.Equals(value, "session-affecting", StringComparison.OrdinalIgnoreCase)) return "session-affecting";
-            if (string.Equals(value, "editor-only", StringComparison.OrdinalIgnoreCase)) return "editor-only";
-            if (string.Equals(value, "unknown", StringComparison.OrdinalIgnoreCase)) return "unknown";
-            return string.Equals(target, "runtime", StringComparison.OrdinalIgnoreCase) ? "runtime-only" : "editor-only";
-        }
-
-        private static string ProjectToolHandlerFingerprintMaterial(RegisteredTool definition)
-        {
-            return "assembly=" + (definition.Assembly ?? string.Empty)
-                + "\nmethod=" + (definition.Method ?? string.Empty)
-                + "\nhandler=" + ProjectToolHandlerSource(definition);
-        }
-
-        private static string ProjectToolHandlerSource(RegisteredTool definition)
-        {
-            try
-            {
-                var typeName = definition.Method;
-                if (string.IsNullOrEmpty(typeName)) return string.Empty;
-                var dot = typeName.LastIndexOf('.');
-                if (dot <= 0) return string.Empty;
-                typeName = typeName.Substring(0, dot);
-                var fileName = typeName.Substring(typeName.LastIndexOf('.') + 1) + ".cs";
-                foreach (var guid in AssetDatabase.FindAssets(Path.GetFileNameWithoutExtension(fileName) + " t:MonoScript"))
-                {
-                    var path = AssetDatabase.GUIDToAssetPath(guid);
-                    if (!string.Equals(Path.GetFileName(path), fileName, StringComparison.OrdinalIgnoreCase)) continue;
-                    var text = File.ReadAllText(path);
-                    if (text.IndexOf(definition.Method.Substring(dot + 1), StringComparison.Ordinal) >= 0)
-                    {
-                        return NormalizeFingerprintText(text);
-                    }
-                }
-            }
-            catch (Exception exception)
-            {
-                WriteLog("custom_tool_fingerprint_source_failed name=" + definition.Name + " error=" + exception.GetType().Name + ": " + exception.Message);
-            }
-            return string.Empty;
-        }
-
-        private static string NormalizeFingerprintText(string value)
-        {
-            return (value ?? string.Empty).Replace("\r\n", "\n").Replace("\r", "\n");
-        }
-
-        private static string NormalizeFingerprintJson(string value)
-        {
-            return Regex.Replace((value ?? string.Empty).Trim(), "\\s+", " ");
-        }
-
-        private static string Sha256Hex(string value)
-        {
-            using (var sha = SHA256.Create())
-            {
-                var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(value ?? string.Empty));
-                var builder = new StringBuilder(bytes.Length * 2);
-                foreach (var b in bytes)
-                {
-                    builder.Append(b.ToString("x2", CultureInfo.InvariantCulture));
-                }
-                return builder.ToString();
-            }
-        }
-
-        private static Dictionary<string, object> ProjectToolFingerprintData(RegisteredTool definition)
-        {
-            return new Dictionary<string, object>
-            {
-                { "currentAlgorithm", ProjectToolFingerprintAlgorithm }, { "actualSha256", definition.Fingerprint },
-                { "pinnedOwner", definition.PinnedFingerprintOwner }, { "pinnedAlgorithm", definition.PinnedFingerprintAlgorithm },
-                { "pinnedFormat", definition.PinnedFingerprintFormat }, { "pinnedValue", definition.ExpectedFingerprint },
-                { "status", definition.FingerprintStatus }, { "message", definition.FingerprintMessage },
-                { "rePinValue", FormatProjectToolFingerprint(definition.Fingerprint) },
-                { "rePinSteps", ProjectToolFingerprintRePinSteps(definition) },
-                { "descriptorSha256", definition.DescriptorSha256 }, { "handlerSha256", definition.HandlerSha256 }
-            };
-        }
-
-        private static string[] ProjectToolFingerprintRePinSteps(RegisteredTool definition)
-        {
-            var value = FormatProjectToolFingerprint(definition.Fingerprint);
-            return definition.PinnedFingerprintOwner == "descriptor"
-                ? new[] { "Review the Tool change.", "Set ToolDescriptor.Fingerprint to " + value + ".", "Run the Tool again." }
-                : new[] { "Review the Tool change.", "Replace the persisted project Tool fingerprint with " + value + ".", "Run the Tool again." };
-        }
-
-
-        private static Dictionary<string, object> ProjectToolFingerprintSummary()
-        {
-            var items = new List<object>();
-            var blocked = 0;
-            foreach (var pair in ProjectTools)
-            {
-                var definition = pair.Value;
-                RefreshProjectToolFingerprint(definition);
-                if (definition.FingerprintStatus == "blocked") blocked++;
-                items.Add(new Dictionary<string, object>
-                {
-                    { "name", definition.Name },
-                    { "fingerprint", ProjectToolFingerprintData(definition) }
-                });
-            }
-            items.Sort((left, right) => StringComparer.Ordinal.Compare(
-                ((Dictionary<string, object>)left)["name"] as string,
-                ((Dictionary<string, object>)right)["name"] as string));
-            return new Dictionary<string, object>
-            {
-                { "algorithm", ProjectToolFingerprintAlgorithm },
-                { "toolCount", (long)ProjectTools.Count },
-                { "blockedCount", (long)blocked },
-                { "tools", items }
-            };
-        }
-
-        private static Dictionary<string, object> ProjectToolFingerprintDetails(RegisteredTool definition)
-        {
-            return new Dictionary<string, object>
-            {
-                { "tool", definition.Name },
-                { "fingerprint", ProjectToolFingerprintData(definition) }
-            };
-        }
     }
 }
 #endif