Merge branch 'codex/tool-json-schema-dsl' into codex/canonical-tool-output

# Conflicts:
#	docs/config-catalog.md
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/agent-loop/tests/contract-regressions.spec.ts
#	packages/ui/acp/src/index.ts
#	packages/ui/tui/src/index.ts

scripts/gen-cordis-catalog.ts

@@ -35,6 +35,7 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  HookContext: 'core.md',
   LlmCallConfig: 'core.md',
   LlmModelContext: 'core.md',
   LlmFailure: 'llm-streaming.md',
@@ -45,9 +46,13 @@ export const LINK_MAP: Record<string, string> = {
   PromptDecision: 'core.md',
   RequestError: 'core.md',
   RequestErrorDecision: 'core.md',
+  PreparedReferencedMessage: 'session-reference.md',
+  SessionReferenceCandidate: 'session-reference.md',
+  SessionReferenceInput: 'session-reference.md',
   SessionEvent: 'core.md',
   SessionId: 'core.md',
   SessionStartSource: 'core.md',
+  SessionSurfaceSnapshot: 'session-query.md',
   ApprovalOutcome: 'approval.md',
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',

scripts/gen-doc-graphs.ts

@@ -137,8 +137,17 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session-query',
     title: 'Exact session-history reads and traces',
     mode: 'seam',
+    consumers: ['session-reference'],
     note: 'Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces.',
   },
+  {
+    key: 'sessionReferences',
+    pkg: 'session-reference',
+    title: 'Cross-session snapshot preparation',
+    mode: 'core',
+    consumers: ['tui', 'acp'],
+    note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
+  },
   {
     key: 'sessionTitle',
     pkg: 'session-title',
@@ -907,7 +916,7 @@ function renderLifecycle(): string {
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
     `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
-    '  Hooks-->>Driver: allow, block, or add context',
+    '  Hooks-->>Driver: authoritative allow, block, or add context',
     `  Driver->>Session: ${mermaidCode('user/message')} or rejected ${mermaidCode('turn/end')}`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
     `  Driver-->>Driver: ${mermaidCode('agent/pre-step')} serial checkpoint`,
@@ -935,7 +944,7 @@ function renderLifecycle(): string {
     `      Driver->>Session: ${mermaidCode('tool/result')}`,
     '    end',
     '  end',
-    '  Driver->>Session: post-tool context and steering',
+    '  Driver->>Session: post-tool context and steering (no prompt-submit)',
     `  Driver->>Hooks: ${mermaidCode('agent/post-step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/end')}`,
     `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
@@ -950,6 +959,8 @@ function renderLifecycle(): string {
     '',
     '`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and a fresh retry step, and returns retry only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
+    'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
+    '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),

scripts/type-equiv.manifest.json

@@ -66,6 +66,11 @@
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "SendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AgentCancelCause",
@@ -283,6 +288,11 @@
       "symbol": "TokenSurfaceNode",
       "source": "packages/llm/token-meter/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.md",
+      "symbol": "PromptMessageData",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SessionEventMap",
@@ -379,6 +389,11 @@
       "symbol": "SessionRecord",
       "source": "packages/session-query/session-query/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session-query.md",
+      "symbol": "SessionSurfaceSnapshot",
+      "source": "packages/session-query/session-query/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-query.md",
       "symbol": "SessionEventRecord",
@@ -419,6 +434,26 @@
       "symbol": "SessionEventTrace",
       "source": "packages/session-query/session-query/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceInput",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceCandidate",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "PreparedReferencedMessage",
+      "source": "packages/context/session-reference/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/session-reference.md",
+      "symbol": "SessionReferenceErrorCode",
+      "source": "packages/context/session-reference/src/config.ts"
+    },
     {
       "doc": "docs/core-data-structures/session-title.md",
       "symbol": "SessionTitleProviderId",