Merge branch 'worktree-hooks-b-bash-seam' into worktree-hooks-c-interception

# Conflicts:
#	docs/architecture.md
#	docs/cordis-catalog/events-and-services.md
#	docs/core-data-structures/tools.md
#	packages/core/tools/README.md
#	packages/core/tools/src/index.ts

packages/core/session/src/index.ts

@@ -16,6 +16,7 @@ import { SurfaceManager, isSurfaceEligibleType } from './surface.ts'
 
 export * from './types.ts'
 export { isJsonValue } from './json.ts'
+export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
 export type { SurfaceNode } from './surface.ts'
 export { isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'

packages/core/session/src/json.ts

@@ -13,6 +13,16 @@
  * @module @deepseek-ai/dsh-session/json
  */
 
+/**
+ * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
+ * number, a string, an array of such values, or a plain object whose values are
+ * such values. The static type companion to {@link isJsonValue} (which validates
+ * the same shape at runtime). Use it to type a payload that must survive
+ * session-log persistence and replay byte-identically — e.g. a tool's private
+ * presentation `meta`.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
 /**
  * Whether `value` is losslessly JSON-serializable: only `null`, finite numbers,
  * booleans, strings, plain arrays, and plain objects of such values. Rejects

packages/core/session/src/types.ts

@@ -231,7 +231,16 @@ export interface SessionEventMap {
    */
   'assistant/message': { turn: number; step: number; content: ContentBlock[]; usage?: TokenUsage }
   'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string }
-  'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string } }
+  /**
+   * A completed tool call's model-facing result, plus an optional tool-private
+   * `meta` presentation payload. `meta` is opaque to the core (`unknown` — the
+   * producing tool owns its shape and reads it back in `presentResult`) but MUST
+   * be JSON-serializable: `Session.append` runtime-validates all event data with
+   * `isJsonValue`, so a non-serializable `meta` is rejected at the source, and the
+   * durable log reproduces the identical card on replay. Absent unless the tool
+   * attaches one (e.g. `dsh-tool-fs` carries its result-time contextual diff here).
+   */
+  'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
   /**