Merge pull request #7966 from deepseek-harness/refactor/tool-errors-foundation

feat(tools): structured error identity for registry-owned tool failures

scripts/doc-standard.spec.ts

@@ -94,6 +94,7 @@ const PACKAGE_LIBRARIES: Readonly<Record<string, string>> = {
   'packages/util/atomic-write': 'Zero-dependency filesystem write utility.',
   'packages/util/brand': 'Stateless nominal-string and canonical-key constructors.',
   'packages/util/crypto': 'Zero-dependency identifier minting utility.',
+  'packages/util/error': 'Zero-dependency HarnessError base class.',
   'packages/util/deque': 'Zero-dependency circular deque utility.',
   'packages/util/chunked-list': 'Persistent collection operations and checkpoint validation without a plugin surface.',
   'packages/util/code-language': 'Zero-dependency file-extension to syntax-highlighting language table.',

scripts/gen-cordis-catalog.ts

@@ -843,6 +843,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ToolExecutionResult: 'tools.md',
   ToolExecutionToken: 'tools.md',
   ToolGuard: 'tools.md',
+  ToolGuardDenial: 'tools.md',
   ToolRuntime: 'tools.md',
   ToolsService: 'tools.md',
   ToolExecutor: 'tools.md',

scripts/package-dependency-policy.ts

@@ -80,6 +80,8 @@ const PEER_REQUIRED_HOST_EXPORTS = {
   // CUA checks UserQuestionError and preserves AttachmentError from image admission.
   '@deepseek-ai/dsh-attachment': ['admitEncodedImages'],
   '@deepseek-ai/dsh-user-questions': ['UserQuestionError'],
+  // The tool registry and every subclass rely on `instanceof` against one HarnessError class.
+  '@deepseek-ai/dsh-error': ['HarnessError'],
   // `instanceof` checks need the translator's own class instance.
   '@deepseek-ai/dsh-experimental-translator': ['TranslationError'],
   // Stateless; a safe classification would turn the forge panel's forge and worktree peers into dependencies.

scripts/type-equiv.manifest.json

@@ -851,6 +851,11 @@
       "symbol": "ToolGuard",
       "source": "packages/core/tools/src/contracts.ts"
     },
+    {
+      "doc": "docs/subsystems/tools.md",
+      "symbol": "ToolGuardDenial",
+      "source": "packages/core/tools/src/contracts.ts"
+    },
     {
       "doc": "docs/subsystems/tools.md",
       "symbol": "ToolErrorInfo",

scripts/verify-package-readme-limitations.ts

@@ -18,6 +18,7 @@ const CANONICAL = '## Known Limitations and Deferred Work'
 /** Packages audited as having no limitations section, keyed by repo-relative directory. */
 const NO_LIMITATIONS: Readonly<Record<string, string>> = {
   'packages/util/brand': 'Stateless nominal-string and canonical-key helpers have no deferred work.',
+  'packages/util/error': 'A single base class with no behavior beyond its constructor has no deferred work.',
 }
 
 /** A heading that reads as a limitations section — canonical or drifted. */

scripts/verify-package-readme-model-experience.ts

@@ -35,6 +35,7 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
   'packages/core/scope': 'The package is a model-agnostic registration and lifecycle primitive; model-facing consumers own any context selection.',
   'packages/experimental/liveshare-protocol': 'The package only defines wire frames and identity values that its consumers exchange; it registers nothing model-facing.',
   'packages/util/brand': 'The package only constructs plain string values and registers nothing model-facing.',
+  'packages/util/error': 'The package only defines the HarnessError base class; packages that throw it own any model-facing text.',
   'packages/util/home-paths': 'The package only resolves harness-owned host paths; model-facing consumers own any rendered use.',
   'packages/util/launch-environment': 'The package only resolves host environment values; model-facing consumers own any rendered use.',
   'packages/util/workspace-path': 'The package only formats Workspace paths for browser UI; it never constructs model input.',