dsh-bailinghub 0.5.0 → 0.7.0

package/lib/runtime.js

@@ -1,14 +1,23 @@
+import { listArtifacts, deliverArtifact, artifactFailure } from './artifacts.js'
 import { createHash } from 'node:crypto'
 import {
   authorizationEnvelope, authorizedResult, declarationKey,
   sharedDeclarations, unwrapAuthorization,
 } from './authorizations.js'
 import { SessionScopeCoordinator, scopeError, isCrossSystemScope, memberBinding, archiveMembers } from './session-scope.js'
+import { InvocationJournal, scopeFingerprint, metadataHash, recoveryError } from './invocation-journal.js'
+import { SessionTaskCoordinator, taskError } from './session-task.js'
+import { createFileSessionTaskStore } from './session-task-store.js'
+import { createFileInvocationStore } from './invocation-store.js'
 import { ConversationOutbox } from './conversation-outbox.js'
 import { isSystemInfoAuthorizationFailure, projectSystemInfo, SYSTEM_DESCRIPTION_GUIDANCE, targetDirectoryEntry, unknownSystemInfo } from './system-info.js'
 import { projectSubjectDisplay, subjectDisplayLabel, SUBJECT_DISPLAY_GUIDANCE } from './subject-display.js'
+import { describeFailure, isInvocationNotFound, normalizeDiscovery, DISCOVERY_GUIDANCE } from './capability-feedback.js'
+import { VISIBLE_TOOL_LIMIT, RETAINED_TOOL_LIMIT, mergeDiscoveredTools, touchCatalogTool } from './tool-catalog.js'
+import { SessionToolCache } from './session-tool-cache.js'
+import { SESSION_TOOL_GUIDANCE, captureSessionTools, sessionToolView, replaceSessionTools } from './session-tools.js'
 
-const MAX_ACTIVE_TOOLS = 12
+const MAX_ACTIVE_TOOLS = VISIBLE_TOOL_LIMIT
 const TOOL_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
 const INVOCATION_ID = /^[0-9a-f]{64}$/
 const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/
@@ -24,8 +33,11 @@ const PUBLIC_USAGE_ALIASES = {
 }
 const RESERVED_TOOLS = new Set([
   'run_code',
+  'list_generated_artifacts',
+  'upload_generated_artifacts',
   'search_business_capabilities',
   'resume_governed_tool_invocation',
+  'inspect_governed_tool_invocation',
 ])
 const INVOCATION_STATES = new Set([
   'executed',
@@ -190,13 +202,18 @@ function redactText(value) {
   return text
 }
 
-function publicFailure(operation, error) {
-  const name = error instanceof Error && /^[A-Za-z][A-Za-z0-9]*Error$/.test(error.name)
-    ? error.name
-    : 'TransportError'
-  const failure = new Error(`BailingHub ${operation} failed (${name})`)
+function feedbackOperation(operation) {
+  if (operation === 'searchCapabilities') return 'search'
+  if (['search', 'invoke', 'resume', 'inspect'].includes(operation)) return operation
+  return ['status', 'login', 'authorization', 'authorizationTools'].includes(operation) ? 'authorize' : 'tool_dispatch'
+}
+
+function publicFailure(operation, error, context = {}) {
+  const failure = new Error('BailingHub operation failed')
   failure.name = 'BailingHubAgentClientError'
   failure.code = 'BAILINGHUB_AGENT_CLIENT_UNAVAILABLE'
+  failure.feedback = describeFailure(error, { operation: feedbackOperation(operation), ...context })
+  failure.message = failure.feedback.message
   return failure
 }
 
@@ -208,6 +225,7 @@ function acceptedUnknownFailure(operation, invocationId) {
   failure.code = 'BAILINGHUB_ACCEPTED_UNKNOWN'
   failure.disposition = 'accepted_unknown'
   failure.invocationId = invocationId
+  failure.feedback = describeFailure(failure, { operation: 'resume', invocationId })
   return failure
 }
 
@@ -267,7 +285,7 @@ function normalizeRecoveryOptions(options = {}) {
   }
 }
 
-function invocationResult(value, invocationId) {
+function invocationResult(value, invocationId, operation = 'invoke') {
   let normalized
   try {
     normalized = normalizeToolValue(value)
@@ -286,6 +304,14 @@ function invocationResult(value, invocationId) {
   ) {
     return undefined
   }
+  if (normalized.state === 'reconciliation_required') {
+    normalized.feedback = describeFailure({ feedback: normalized.feedback ?? {
+      schema: 'bailing.agent-feedback.v1', category: 'invocation_outcome_unknown', code: 'reconciliation_required',
+      origin: 'core', dispatch: 'unknown', next_action: 'inspect_original', invocation_id: invocationId,
+    } }, { operation, invocationId })
+  } else if (normalized.feedback) {
+    normalized.feedback = describeFailure({ feedback: normalized.feedback }, { operation, invocationId })
+  }
   return normalized
 }
 
@@ -299,16 +325,17 @@ function invocationIsTerminal(result) {
   return result !== undefined && !invocationNeedsResume(result)
 }
 
-function timedOutInvocationResult(result, invocationId, attempts) {
+function timedOutInvocationResult(result, invocationId, attempts, managed = false) {
   return {
     ...cloneJson(result),
     agent_client_wait: {
       state: 'timed_out',
       invocation_id: invocationId,
-      resume_required: true,
+      resume_required: !managed,
+      ...(managed ? { inspect_tool: 'inspect_governed_tool_invocation', continuation_requires_explicit_intent: true } : {}),
       resume_tool: 'resume_governed_tool_invocation',
       resume_attempts: attempts,
-      next_action: 'Resume this exact invocation_id; never call the original business tool again.',
+      next_action: managed ? 'Inspect this exact invocation_id to observe its result. Continue it only with explicit intent through resume_governed_tool_invocation; never create a replacement.' : 'Resume this exact invocation_id; never call the original business tool again.',
     },
   }
 }
@@ -520,7 +547,7 @@ export function normalizeStartTurnResponse(value) {
   }
   const schema = value.schema ?? value.schema_version
   if (schema !== 'bailing.agent-turn-context.v1') {
-    throw new TypeError('startTurn response has an unsupported schema')
+    throw Object.assign(new TypeError('startTurn response has an unsupported schema'), { publicCode: 'agent_schema_unsupported' })
   }
   if (typeof value.run_id !== 'string' || !UUID.test(value.run_id.trim())) {
     throw new TypeError('startTurn response is missing run_id')
@@ -555,7 +582,7 @@ export function normalizeCapabilitySearchResponse(value) {
   }
   const schema = value.schema ?? value.schema_version
   if (schema !== 'bailing.agent-capability-search.v1') {
-    throw new TypeError('searchCapabilities response has an unsupported schema')
+    throw Object.assign(new TypeError('searchCapabilities response has an unsupported schema'), { publicCode: 'agent_schema_unsupported' })
   }
   if (!Array.isArray(value.tools) || value.tools.length > MAX_ACTIVE_TOOLS) {
     throw new TypeError('searchCapabilities response has an invalid tools list')
@@ -568,6 +595,7 @@ export function normalizeCapabilitySearchResponse(value) {
     schema,
     capabilityRevision: normalizeRevision(value.capability_revision, 'capability_revision'),
     tools,
+    discovery: normalizeDiscovery(value.discovery, tools.length),
   }
 }
 
@@ -593,6 +621,7 @@ function profileSection(state, run) {
       `Capability revision: ${run.capabilityRevision}`,
       SYSTEM_DESCRIPTION_GUIDANCE,
       SUBJECT_DISPLAY_GUIDANCE,
+      DISCOVERY_GUIDANCE,
       `Authorization directory: ${safeJson([targetDirectoryEntry(state, run)])}`,
       'BailingHub Core is the authority for identity, authorization, capability-candidate trimming, approval, invocation, and audit. The local Agent chooses among the active candidates and performs the local reasoning and orchestration. Use only the active BailingHub tools exposed in this turn.',
       `Workspace instructions:\n${instructions}`,
@@ -754,7 +783,12 @@ function createState(agent, workspace, connectionName) {
     systemInfoLoads: new Map(),
     activeDefinitions: new Map(),
     activeDisposers: new Map(),
+    definitionSlots: new Map(),
+    visibleToolNames: [],
+    toolUsage: new Map(),
+    toolUseSequence: 0,
     knownToolNames: new Set(),
+    toolsetGeneration: 0,
     status: { state: 'ready' },
     disposed: false,
   }
@@ -769,13 +803,24 @@ function conversationStarted(session) {
 }
 
 export class BailingHubAgentClientRuntime {
-  constructor(ctx, config, getTransport, recoveryOptions = {}, { scopeStore, archiveStore } = {}) {
+  constructor(ctx, config, getTransport, recoveryOptions = {}, { scopeStore, archiveStore, artifactSource, artifactStore, invocationStore, taskStore, toolLifecycle = 'active_turn' } = {}) {
+    if (!['active_turn', 'session'].includes(toolLifecycle)) throw new TypeError('Unsupported toolLifecycle')
+    this.sessionToolReuse = toolLifecycle === 'session'
+    // Custom hosts own their persistence namespace; never silently put their
+    // recovery records in an unrelated default directory.
+    this.invocationJournal = new InvocationJournal(invocationStore === undefined
+      ? scopeStore === undefined ? createFileInvocationStore() : null : invocationStore)
+    this.artifactSource = artifactSource
+    this.artifactStore = artifactStore
     this.ctx = ctx
     this.config = normalizeConfig(config)
     this.getTransport = getTransport
     this.sessionScopes = new SessionScopeCoordinator({
       store: scopeStore, getTransport, normalizeConfig, sanitize: sanitizePublicValue,
     })
+    this.sessionTasks = new SessionTaskCoordinator({ store: taskStore === undefined
+      ? scopeStore === undefined ? createFileSessionTaskStore() : null : taskStore,
+      scopes: this.sessionScopes, getTransport, conversationId: id => messageAlias('conversation', id) })
     this.conversationOutbox = new ConversationOutbox({ store: archiveStore })
     this.archiveAvailability = new Map()
     this.recovery = normalizeRecoveryOptions(recoveryOptions)
@@ -792,9 +837,15 @@ export class BailingHubAgentClientRuntime {
     this.statesBySessionId = new Map()
     this.observedSessions = new Map()
     this.observedConversationStarts = new Map()
+    this.toolFailures = new WeakMap()
+    this.invocationOperations = new Map()
+    this.hostActionControllers = new Map()
+    this.hostReceiptBindings = new Set()
+    this.disposed = false
   }
 
   install() {
+    this.ctx.on('tools/execute', (exec, next) => this.onToolExecute(exec, next))
     this.ctx.on('session/created', (session) => this.observeSession(session))
     this.ctx.on('agent/inbox/claimed', (payload) => this.onInboxClaimed(payload))
     this.ctx.on('system-prompt/assemble', (assembly, context, next) =>
@@ -806,7 +857,7 @@ export class BailingHubAgentClientRuntime {
     const registerCommand = () => this.ctx.commands.register({
       name: 'bailinghub',
       description: 'authorize, select conversation scope, diagnose, or resync BailingHub Agent Client connections',
-      input: { hint: 'scope [set <connection-key>...|none]|archive [status|sync]|doctor|connections list|add|use|remove|login|status|logout|workspaces|use <workspace>|sync' },
+      input: { hint: 'scope [set <connection-key>...|none]|archive [status|sync]|invocations [status|restore]|doctor|connections list|add|use|remove|login|status|logout|workspaces|use <workspace>|sync' },
       handler: (invocation) => this.handleCommand(invocation),
     })
     if (typeof this.ctx.effect === 'function') this.ctx.effect(registerCommand)
@@ -828,6 +879,15 @@ export class BailingHubAgentClientRuntime {
         const result = operation === 'sync' ? await this.syncSessionArchive(String(sessionId)) : await this.getSessionArchiveStatus(String(sessionId))
         return { kind: result.state === 'synced' || result.state === 'inactive' ? 'success' : 'error', text: commandText(result) }
       }
+      if (action === 'invocations') {
+        const sessionId = invocation.agent?.session?.id
+        if (!sessionId) throw scopeError('INVALID_SESSION_ID')
+        this.observeSession(invocation.agent.session)
+        const [operation = 'status', ...extra] = rest
+        if (extra.length || !['status', 'restore'].includes(operation)) return { kind: 'error', text: 'Usage: /bailinghub invocations [status|restore]' }
+        const result = operation === 'restore' ? await this.restoreSessionInvocations(String(sessionId)) : await this.getSessionInvocationStatus(String(sessionId))
+        return { kind: ['ready', 'inactive'].includes(result.state) ? 'success' : 'error', text: commandText(result) }
+      }
       if (action === 'scope') {
         const sessionId = invocation.agent?.session?.id
         if (!sessionId) throw scopeError('INVALID_SESSION_ID')
@@ -903,7 +963,7 @@ export class BailingHubAgentClientRuntime {
         default:
           return {
             kind: 'error',
-            text: 'Usage: /bailinghub scope [set <connection-key>...|none]|archive [status|sync]|doctor|connections list|add|use|remove|login|status|logout|workspaces|use <workspace>|sync',
+            text: 'Usage: /bailinghub scope [set <connection-key>...|none]|archive [status|sync]|invocations [status|restore]|doctor|connections list|add|use|remove|login|status|logout|workspaces|use <workspace>|sync',
           }
       }
     } catch (error) {
@@ -946,6 +1006,93 @@ export class BailingHubAgentClientRuntime {
     return this.sessionScopes.set(sessionId, request)
   }
 
+  async setSessionTaskBinding(session, request) {
+    const id = typeof session === 'string' ? session : String(session.id)
+    if (typeof session !== 'string') this.observeSession(session)
+    const state = this.statesBySessionId.get(id)
+    if (!this.sessionTasks.entry(id).record && state && [...state.runs.values()].some(run => run.runId || run.targets?.some(target => target.run?.runId))) throw taskError('TASK_BINDING_CONFLICT')
+    return this.sessionTasks.set(id, request)
+  }
+
+  /** Synchronous snapshot; queued local writes can still be pending. */
+  getSessionLocalPrimaryStatus(session) {
+    if (!session || typeof session.id !== 'string' || !session.id.trim() || session.id.length > 512
+      || /[\u0000-\u001f\u007f]/.test(session.id) || !Array.isArray(session.events)) {
+      throw new TypeError('A real Session with its current events is required')
+    }
+    const view = this.sessionTaskView(session.id, session)
+    return { schema: 'bailing.agent-session-local-primary.v1',
+      state: ['storage_error', 'recovery_gap'].includes(view.state) ? view.state : 'ready',
+      local: { ...view.local }, snapshot_is_dispatch_permission: false }
+  }
+
+  /** Settle already queued local persistence before checking the primary error. */
+  async waitForSessionLocalPrimaryStatus(session) {
+    this.getSessionLocalPrimaryStatus(session) // Validate before touching queues.
+    await Promise.all([
+      this.conversationOutbox.drain(session.id),
+      this.invocationJournal.drain(session.id),
+    ])
+    // Task queues also contain remote validation; never wait for them here.
+    // Failed saves retain their original pending records and error status.
+    return this.getSessionLocalPrimaryStatus(session)
+  }
+
+  async getSessionTaskState(session) {
+    const id = typeof session === 'string' ? session : String(session.id)
+    await this.sessionTasks.refresh(id)
+    return this.sessionTaskView(id, typeof session === 'string' ? undefined : session)
+  }
+
+  async getSessionTaskCoordinates(session) {
+    const schema = 'bailing.agent-session-task-coordinates.v1'
+    const failure = error => {
+      const feedback = describeFailure(error, { operation: 'task_coordinates', origin: 'dsh' })
+      const state = feedback.code === 'SESSION_RECOVERY_GAP' ? 'recovery_gap'
+        : feedback.code === 'AUTHORIZATION_UNVERIFIED' ? 'unavailable'
+        : { storage_error: 'storage_error', unsupported: 'unsupported', transport_unavailable: 'unavailable' }[feedback.category] ?? 'blocked'
+      return { state, availability: state === 'unsupported' ? 'unsupported' : 'unavailable', reason: feedback.code, feedback }
+    }
+    let id, result
+    try {
+      id = typeof session === 'string' ? session : session?.id
+      this.sessionScopes.entry(id) // Validate before observing or probing anything.
+      if (typeof session !== 'string') this.observeSession(session)
+      const localFailure = () => {
+        const local = this.sessionTaskView(id, typeof session === 'string' ? undefined : session)
+        return local.state === 'storage_error' ? local.reason?.startsWith('TASK_STORE_') ? local.reason : 'SESSION_LOCAL_STORAGE_ERROR'
+          : local.state === 'recovery_gap' ? 'SESSION_RECOVERY_GAP' : undefined
+      }
+      const before = localFailure()
+      if (before) result = failure({ code: before })
+      else {
+        try { result = await this.sessionTasks.coordinates(id) } catch (error) { result = failure(error) }
+        const after = localFailure()
+        if (after && (after !== 'SESSION_RECOVERY_GAP' || result.state !== 'storage_error')) result = failure({ code: after })
+      }
+    } catch (error) { result = failure(error) }
+    return { schema, ...result, snapshot_is_dispatch_permission: false }
+  }
+
+  sessionTaskView(id, session) {
+    const task = this.sessionTasks.view(id)
+    const sessionObject = session ?? this.statesBySessionId.get(id)?.agent.session ?? this.observedSessions.get(id)
+    const journalFailure = this.invocationJournal.failures.get(id)
+    const unsavedInvocations = this.invocationJournal.pending.get(id)?.size ?? 0
+    const archive = this.archiveStatusWithCoverage(id, this.conversationOutbox.status(id))
+    const unsavedEvents = Math.max(archive.unsavedEvents ?? 0, sessionObject?.unsavedEvents?.length ?? 0)
+    const storage = task.state === 'storage_error' || unsavedEvents || unsavedInvocations || journalFailure?.startsWith('invocation_store_') || (archive.state === 'storage_error' || archive.syncState === 'storage_error')
+    return { ...task, ...(storage ? { state: 'storage_error' } : archive.state === 'recovery_gap' ? { state: 'recovery_gap' } : {}),
+      local: { task: task.state, invocation: journalFailure ?? (unsavedInvocations ? 'storage_error' : 'ready'),
+        archive: archive.state, unsavedEvents, unsavedInvocations } }
+  }
+
+  async restoreSessionTaskBinding(session) {
+    const id = typeof session === 'string' ? session : String(session.id)
+    await this.sessionTasks.refresh(id, true)
+    return this.sessionTaskView(id, typeof session === 'string' ? undefined : session)
+  }
+
   observeSession(session) {
     if (!session?.id) return
     const id = String(session.id)
@@ -979,6 +1126,208 @@ export class BailingHubAgentClientRuntime {
     return this.sessionScopes.restore(sessionId, this.inspectSessionLifecycle(sessionId))
   }
 
+  getSessionInvocationStatus(sessionId) {
+    return this.sessionInvocationStatus(sessionId, false)
+  }
+
+  restoreSessionInvocations(sessionId) {
+    return this.sessionInvocationStatus(sessionId, true)
+  }
+
+  inspectSessionInvocation(session, invocationId, options = {}) {
+    return this.sessionInvocationAction('inspect', session, invocationId, options)
+  }
+
+  resumeSessionInvocation(session, invocationId, options = {}) {
+    return this.sessionInvocationAction('resume', session, invocationId, options)
+  }
+
+  localInvocationActionFailure(id, session) {
+    const view = this.sessionTaskView(id, session)
+    // An unloaded outbox is not yet evidence of a gap. The action restores the
+    // original local metadata before testing coverage; no text is reconstructed.
+    const outbox = this.conversationOutbox.entries.get(id)
+    if (view.state === 'recovery_gap' && !outbox?.record && outbox?.coverageLoaded !== true) return undefined
+    const code = view.state === 'storage_error'
+      ? view.reason?.startsWith('TASK_STORE_') ? view.reason : 'SESSION_LOCAL_STORAGE_ERROR'
+      : view.state === 'recovery_gap' ? 'SESSION_RECOVERY_GAP' : undefined
+    return code ? { feedback: describeFailure({ code }, { operation: 'task_coordinates', origin: 'dsh' }) } : undefined
+  }
+
+  async sessionInvocationAction(operation, session, invocationId, options) {
+    const schema = 'bailing.agent-session-invocation-action.v1'
+    let id, signal, resumeDispatched = false
+    try {
+      if (!session || typeof session !== 'object' || !Array.isArray(session.events) ||
+        !INVOCATION_ID.test(invocationId ?? '') || !options || Object.keys(options).some(key => key !== 'signal') ||
+        options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+        throw Object.assign(new TypeError('A real Session and its original invocation id are required'), { publicCode: 'agent_invalid_request' })
+      }
+      id = session.id
+      this.sessionScopes.entry(id)
+      this.observeSession(session)
+      if (!this.hostActionControllers.has(id)) this.hostActionControllers.set(id, new AbortController())
+      signal = options.signal ? AbortSignal.any([options.signal, this.hostActionControllers.get(id).signal]) : this.hostActionControllers.get(id).signal
+      const active = () => { if (this.disposed || signal.aborted) throw abortError() }
+      const local = () => { const failure = this.localInvocationActionFailure(id, session); if (failure) throw failure }
+      return await this.serializeInvocation(id, invocationId, async () => {
+        local(); active()
+        const selection = await this.sessionScopes.verifiedSelection(id)
+        const scope = selection.record
+        if (!scope?.locked || !scope.authorizations?.length) throw recoveryError('invocation_binding_unavailable', invocationId)
+        await this.conversationOutbox.restoreExisting(id, { clientConversationId: messageAlias('conversation', id),
+          binding: scope.binding, members: archiveMembers(scope) })
+        local(); active(); await selection.check()
+        const fingerprint = scopeFingerprint(scope)
+        const status = await this.invocationJournal.status(id, fingerprint)
+        if (status.state !== 'ready') throw recoveryError(status.reason ?? 'invocation_store_unavailable', invocationId)
+        const original = await this.invocationJournal.find(id, invocationId, fingerprint)
+        const member = scope.authorizations.find(value => value.connectionKey === original.target.connectionKey)
+        const ref = this.sessionScopes.view(this.sessionScopes.entry(id)).authorizations.find(value => value.connectionKey === member?.connectionKey)?.authorizationRef
+        const expected = member && { ...memberBinding(scope, member), connectionKey: member.connectionKey, agentSessionId: member.sessionId, authorizationRef: ref }
+        if (!member || metadataHash(expected) !== metadataHash(original.target) || original.scopeRevision !== scope.revision) throw recoveryError('invocation_binding_conflict', invocationId)
+        const record = { invocationId, journalEntry: original, journalSessionId: id, resumeNotBefore: original.retryAt }
+        const transport = await this.getTransport()
+        if (typeof transport.inspectInvocation !== 'function') throw taskError('TASK_UNSUPPORTED')
+        const connection = { connectionKey: member.connectionKey, workspace: member.workspace, signal,
+          expectedBinding: { ...memberBinding(scope, member), sessionId: member.sessionId } }
+        // This action never borrows an active/ended turn or creates a run.
+        const guard = async (dispatch = false) => {
+          local(); active(); await selection.check()
+          const task = await this.sessionTasks.binding(id, { dispatch })
+          if (metadataHash(task ?? null) !== metadataHash(original.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
+          const current = await this.invocationJournal.find(id, invocationId, fingerprint)
+          if (metadataHash(current) !== metadataHash(record.journalEntry)) throw recoveryError('invocation_store_conflict', invocationId)
+          await selection.check(); local(); active()
+        }
+        const inspect = async () => {
+          await guard()
+          const receipt = this.checkedInvocationReceipt(await transport.inspectInvocation(invocationId, connection), original)
+          await guard()
+          if (receipt.result) await this.rememberInvocationResult(record, receipt.result)
+          await guard()
+          this.hostReceiptBindings.add(`${id}:${invocationId}`)
+          return receipt
+        }
+        let receipt = await inspect()
+        let result
+        if (operation === 'resume') {
+          await guard(true)
+          const mayContinue = () => receipt.dispatch_state === 'not_dispatched' && receipt.journal_state === 'absent' && invocationNeedsResume(receipt.result)
+          const delay = Math.max(0, record.resumeNotBefore - this.recovery.now())
+          if (mayContinue() && delay >= this.recovery.maxWaitMilliseconds) return { schema, operation, invocation_id: invocationId,
+            state: 'ready', resume_dispatched: false, receipt, retry_after_ms: delay, next_action: 'inspect_original' }
+          if (mayContinue() && delay) {
+            await this.recovery.sleep(delay, signal)
+            receipt = await inspect()
+            await guard(true)
+          }
+          if (mayContinue()) {
+            await guard(true)
+            selection.assertCurrent(); local(); active()
+            resumeDispatched = true
+            result = invocationResult(await transport.resume(invocationId, {}, connection), invocationId, 'resume')
+            if (!result || result.route !== original.target.workspace || result.tool !== original.tool) throw recoveryError('invocation_binding_conflict', invocationId, 'unknown')
+            // Even a late original response may update its original journal;
+            // cancellation never re-enables tools or returns an actionable success.
+            await this.rememberInvocationResult(record, result, { freshDispatch: true })
+            await guard()
+            receipt = await inspect()
+          }
+        }
+        await guard()
+        return { schema, operation, invocation_id: invocationId, state: 'ready', resume_dispatched: resumeDispatched, receipt,
+          ...(result ? { result } : {}), next_action: receipt.result && invocationIsTerminal(receipt.result) && receipt.result.state !== 'reconciliation_required' ? 'none' : 'inspect_original' }
+      })
+    } catch (error) {
+      const failure = (id && this.localInvocationActionFailure(id, session)) ?? (signal?.aborted || this.disposed
+        ? Object.assign(abortError(), { publicCode: 'agent_request_cancelled' }) : error)
+      const feedback = describeFailure(failure, { operation, origin: 'dsh', invocationId, dispatch: resumeDispatched ? 'unknown' : 'not_dispatched' })
+      if (resumeDispatched) {
+        feedback.dispatch = 'unknown'
+        feedback.original_outcome = 'unverified'
+      }
+      if (['transport_unavailable', 'unknown_failure', 'invocation_outcome_unknown'].includes(feedback.category)) {
+        feedback.next_action = 'inspect_original'; feedback.retryable = false; feedback.original_outcome = 'unverified'
+      }
+      const state = feedback.code === 'SESSION_RECOVERY_GAP' ? 'recovery_gap'
+        : feedback.code === 'AUTHORIZATION_UNVERIFIED' ? 'unavailable'
+        : feedback.category === 'invocation_outcome_unknown' && feedback.code !== 'invocation_not_found' ? 'unavailable'
+        : { storage_error: 'storage_error', unsupported: 'unsupported', transport_unavailable: 'unavailable', cancelled: 'cancelled' }[feedback.category] ?? 'blocked'
+      return { schema, operation, ...(INVOCATION_ID.test(invocationId ?? '') ? { invocation_id: invocationId } : {}),
+        state, resume_dispatched: resumeDispatched, reason: feedback.code, feedback }
+    }
+  }
+
+  async sessionInvocationStatus(sessionId, restore) {
+    const scope = await this.getSessionScope(sessionId)
+    if (scope.mode === 'blocked') {
+      const unsavedRecords = this.invocationJournal.pending.get(sessionId)?.size ?? 0
+      const failure = this.invocationJournal.failures.get(sessionId)
+      const storageFailed = unsavedRecords > 0 || ['invocation_store_unavailable', 'invocation_store_conflict'].includes(failure)
+      return { state: storageFailed ? 'storage_error' : 'blocked',
+        reason: storageFailed ? failure ?? 'invocation_store_unavailable' : scope.reason ?? 'SESSION_SCOPE_UNAVAILABLE',
+        scope_state: 'blocked', scope_reason: scope.reason ?? 'SESSION_SCOPE_UNAVAILABLE', entries: [], unsavedRecords }
+    }
+    if (scope.mode !== 'business' || !scope.locked) return { state: 'inactive', entries: [], unsavedRecords: 0 }
+    // No business resume, new run, tool registration or transcript inference.
+    return this.invocationJournal.status(sessionId, scopeFingerprint(this.sessionScopes.snapshot(sessionId)), restore)
+  }
+
+  invocationMetadata(state, run, tool, arguments_, exec, invocationId) {
+    const scope = this.sessionScopes.snapshot(state.sessionId)
+    const member = scope.authorizations.find(item => item.connectionKey === state.authorization?.connectionKey)
+    if (!member) throw recoveryError('invocation_binding_conflict', invocationId)
+    return { id: invocationId, scopeHash: scopeFingerprint(scope), scopeRevision: scope.revision,
+      target: { ...memberBinding(scope, member), connectionKey: member.connectionKey,
+        agentSessionId: member.sessionId, authorizationRef: state.authorization.ref },
+      runId: run.runId, turn: run.turn, callId: exec.callId, tool: tool.name,
+      capabilityRevision: run.capabilityRevision, parameterHash: metadataHash(arguments_),
+      lastKnownState: 'unknown', retryAt: 0, resultHash: null,
+      ...(run.taskBinding ? { taskBinding: structuredClone(run.taskBinding) } : {}) }
+  }
+
+  async verifyInvocationJournal(state, invocationId, record) {
+    if (!this.invocationJournal.store) return
+    const status = await this.invocationJournal.status(state.sessionId, scopeFingerprint(this.sessionScopes.snapshot(state.sessionId)))
+    if (status.state !== 'ready') throw recoveryError(status.reason ?? 'invocation_store_unavailable', invocationId)
+    if (record?.journalEntry) {
+      const entry = await this.invocationJournal.find(state.sessionId, invocationId, scopeFingerprint(this.sessionScopes.snapshot(state.sessionId)))
+      record.journalEntry = entry
+      record.resumeNotBefore = entry.retryAt
+      if (record.latest && entry.resultHash !== metadataHash(record.latest)) record.latest = undefined
+    }
+  }
+
+  async recoverInvocationBinding(state, invocationId) {
+    // Validate ALL original members before using a durable target, including
+    // same-system scopes. A surviving subset is never a recovery target.
+    await this.sessionScopes.get(state.sessionId)
+    await this.sessionScopes.assertUsable(state.sessionId)
+    await this.verifyInvocationJournal(state, invocationId)
+    const scope = this.sessionScopes.snapshot(state.sessionId)
+    const entry = await this.invocationJournal.find(state.sessionId, invocationId, scopeFingerprint(scope))
+    const target = (state.authorizations ?? [state]).find(value => value.authorization?.ref === entry.target.authorizationRef)
+    const member = scope.authorizations.find(value => value.connectionKey === entry.target.connectionKey)
+    const expected = member && { ...memberBinding(scope, member), connectionKey: member.connectionKey,
+      agentSessionId: member.sessionId, authorizationRef: target?.authorization?.ref }
+    if (!target || !member || metadataHash(expected) !== metadataHash(entry.target) ||
+      entry.scopeRevision !== scope.revision || target.authorizedSessionId !== member.sessionId) throw recoveryError('invocation_binding_conflict', invocationId)
+    const taskBinding = await this.sessionTasks.binding(state.sessionId)
+    if (metadataHash(taskBinding ?? null) !== metadataHash(entry.taskBinding ?? null)) throw recoveryError('invocation_binding_conflict', invocationId)
+    const run = { taskBinding, runId: entry.runId, turn: entry.turn, capabilityRevision: entry.capabilityRevision, invocations: new Map() }
+    const record = this.invocationRecord(run, invocationId, { invoked: true, tool: entry.tool })
+    record.journalEntry = entry
+    record.journalSessionId = state.sessionId
+    record.resumeNotBefore = entry.retryAt
+    // A persisted state is a hint, not a fresh business receipt. Query the
+    // original invocation only when the caller explicitly requests resume.
+    const binding = { state: target, run, invocationId }
+    if (state.authorizations) state.authorizedInvocations.set(invocationId, binding)
+    else state.invocationBindings.set(invocationId, binding)
+    return binding
+  }
+
   async prepareSessionArchive(sessionId) {
     const scope = await this.sessionScopes.get(sessionId)
     if (scope.mode !== 'business' || !scope.locked) {
@@ -1142,6 +1491,8 @@ export class BailingHubAgentClientRuntime {
         state.status = { state: state.scopeView.state }
         return this.decorateAssembly(base, state, removedNames)
       }
+      const taskState = await this.sessionTasks.refresh(state.sessionId)
+      state.taskManaged = Boolean(taskState.task_binding || taskState.unsavedRecords || this.sessionTasks.entry(state.sessionId).intendedId || taskState.reason === 'TASK_REQUIRED')
       this.initializeAuthorizations(state)
       const started = await this.startRun(state, turn, context.signal)
       removedNames = started.removedNames
@@ -1280,8 +1631,11 @@ export class BailingHubAgentClientRuntime {
     if (!state.authorization) throw scopeError()
     if (state.parentState?.disposed) throw abortError()
     // Cross-system dispatch must not continue with only the surviving subset.
-    if (state.parentState?.crossSystem) await this.sessionScopes.get(state.sessionId)
+    if (state.parentState?.crossSystem || state.parentState?.sessionToolCache) await this.sessionScopes.get(state.sessionId)
     await this.sessionScopes.assertUsable(state.sessionId)
+    // Managed whole-scope resolution has just checked this exact target too.
+    // Do not issue a second status request for a member of the same proof.
+    if (state.parentState?.taskManaged) return
     let status
     try {
       const transport = await this.getTransport()
@@ -1300,7 +1654,10 @@ export class BailingHubAgentClientRuntime {
   }
 
   initializeAuthorizations(state) {
-    if (state.authorizationInit) return
+    if (state.authorizationInit && (!state.taskManaged || state.sessionToolCache)) return
+    // A failed pre-run optional session may subsequently receive its explicit
+    // managed association. Its next turn must still use lazy target preparation.
+    if (state.authorizationInit) { delete state.authorization; delete state.authorizedSessionId }
     const snapshot = this.sessionScopes.snapshot(state.sessionId)
     const entries = state.scopeView.authorizations.map((item) => ({
       ...item, ref: item.authorizationRef,
@@ -1308,20 +1665,22 @@ export class BailingHubAgentClientRuntime {
     }))
     state.binding = snapshot.binding
     state.crossSystem = isCrossSystemScope(snapshot)
-    if (entries.length === 1) {
+    if (entries.length === 1 && !(this.sessionToolReuse || state.taskManaged)) {
       state.authorization = entries[0]
       state.authorizedSessionId = entries[0].sessionId
       state.workspace = entries[0].workspace
       state.connectionName = undefined
     } else {
+      if (this.sessionToolReuse || state.taskManaged) state.sessionToolCache = new SessionToolCache()
       state.authorizations = entries.map((authorization) => {
         const target = createState(state.agent, authorization.workspace, undefined)
         target.authorization = authorization
         target.authorizedSessionId = authorization.sessionId
-        if (state.crossSystem) {
+        if (state.crossSystem || (this.sessionToolReuse || state.taskManaged)) {
           const saved = snapshot.authorizations.find((item) => item.connectionKey === authorization.connectionKey)
           target.expectedBinding = { ...memberBinding(snapshot, saved), sessionId: saved.sessionId }
         }
+        if (this.sessionToolReuse || state.taskManaged) target.toolCacheKey = digestId(scopeFingerprint(snapshot), authorization.ref, authorization.connectionKey, authorization.sessionId)
         target.parentState = state
         target.pendingClaims = state.pendingClaims
         return target
@@ -1335,12 +1694,15 @@ export class BailingHubAgentClientRuntime {
     const removedNames = new Set(state.knownToolNames)
     await this.clearActiveTools(state)
     state.currentRun?.abortController?.abort()
-    const group = { turn, multi: true, crossSystem: state.crossSystem, status: 'active', targets: [], calls: new Map(),
+    const group = { turn, multi: true, crossSystem: state.crossSystem, sessionTools: (this.sessionToolReuse || state.taskManaged),
+      single: (this.sessionToolReuse || state.taskManaged) && state.authorizations.length === 1,
+      lazy: state.crossSystem || (this.sessionToolReuse || state.taskManaged), status: 'active', targets: [], calls: new Map(),
+      ...((this.sessionToolReuse || state.taskManaged) ? { preparedCalls: new Map() } : {}),
       userMessageId: state.pendingClaims.get(turn)?.[0]?.id,
-      ...(state.crossSystem ? { abortController: new AbortController() } : {}) }
+      ...(state.crossSystem || (this.sessionToolReuse || state.taskManaged) ? { abortController: new AbortController() } : {}) }
     state.runs.set(turn, group)
     state.currentRun = group
-    if (state.crossSystem) {
+    if (group.lazy) {
       // A selected directory grants a choice, not a broadcast of this turn.
       group.targets = state.authorizations.map((target) => ({ state: target, run: undefined }))
     } else {
@@ -1359,7 +1721,7 @@ export class BailingHubAgentClientRuntime {
     try {
       if (state.disposed) throw abortError()
       await this.replaceAuthorizedTools(state, group)
-      state.status = { state: 'active', authorizationCount: group.targets.length, activeToolCount: group.shared.tools.length }
+      state.status = { state: 'active', authorizationCount: group.targets.length, activeToolCount: this.getSessionToolState(state.sessionId).active_tools.length }
     } catch (error) {
       group.status = 'degraded'
       group.degradedReason = 'shared authorization tools are unavailable'
@@ -1371,32 +1733,35 @@ export class BailingHubAgentClientRuntime {
 
   async assertActiveGroup(state, group, exec) {
     await this.sessionScopes.assertUsable(state.sessionId)
-    if (state.disposed || exec.agent !== state.agent || state.currentRun !== group || group.status !== 'active') {
+    if (exec.signal?.aborted || state.disposed || state.endedTurns.has(group.turn) || group.status !== 'active') throw abortError()
+    if (exec.agent !== state.agent || state.currentRun !== group) {
       throw new Error('BailingHub authorization tools are not active for this session turn')
     }
     this.sessionScopes.assertCurrent(state.sessionId)
   }
 
   async replaceAuthorizedTools(state, group, preferredNames = [], preferredRefs = []) {
-    await this.clearActiveTools(state)
-    group.shared = sharedDeclarations(group.targets.filter(({ run }) => run?.status === 'active').map((target) => target.state), MAX_ACTIVE_TOOLS, preferredNames, group.crossSystem, preferredRefs)
-    try {
-      for (const shared of group.shared.tools) {
-        this.registerDefinition(state, this.authorizedDefinition(state, group, shared))
-      }
-      this.registerDefinition(state, this.authorizedSearchDefinition(state, group))
-      this.registerDefinition(state, this.authorizedResumeDefinition(state, group))
-    } catch (error) {
-      await this.clearActiveTools(state)
-      throw error
-    }
+    if (group.sessionTools) return replaceSessionTools(this, state, group, preferredNames, preferredRefs, normalizeCapabilitySearchResponse)
+    const candidates = sharedDeclarations(group.targets.filter(({ run }) => run?.status === 'active').map(target => target.state), Infinity, preferredNames, group.crossSystem, preferredRefs)
+    // Search hits and recently used tools get a place in the small schema window.
+    const hits = candidates.tools.filter(entry => preferredNames.includes(entry.tool.name) &&
+      (!preferredRefs.length || entry.targets.some(target => preferredRefs.includes(target.authorization.ref))))
+    for (const entry of [...hits].reverse()) this.touchTool(state, entry.name)
+    candidates.tools.sort((a, b) => (state.toolUsage.get(b.name) ?? 0) - (state.toolUsage.get(a.name) ?? 0))
+    group.shared = { ...candidates, tools: candidates.tools.slice(0, RETAINED_TOOL_LIMIT),
+      omitted: Math.max(0, candidates.tools.length - RETAINED_TOOL_LIMIT) }
+    state.visibleToolNames = group.shared.tools.slice(0, VISIBLE_TOOL_LIMIT).map(entry => entry.name)
+    const definitions = group.shared.tools.map(shared => this.authorizedDefinition(state, group, shared))
+    definitions.push(this.authorizedSearchDefinition(state, group), this.authorizedResumeDefinition(state, group), this.inspectDefinitionFor(state, group))
+    this.registerArtifactTools(state, group, definitions)
+    await this.reconcileDefinitions(state, group, definitions)
   }
 
   authorizedDefinition(state, group, shared) {
     const { tool } = shared
     return {
       name: shared.name,
-      description: `${tool.description}\n${group.crossSystem ? `System ${shared.targets[0].authorization.systemRef}; original capability ${tool.name}. ` : ''}Choose the authorized account for this call. scope=${tool.scope}, risk=${tool.risk}, approval_required=${tool.approvalRequired}, readonly=${tool.readonly}, idempotent=${tool.idempotent}.`,
+      description: `${tool.description}\n${group.crossSystem ? `System ${shared.targets[0].authorization.systemRef}; original capability ${tool.name}. ` : ''}Choose the authorized account for this call. scope=${tool.scope}, risk=${tool.risk}, approval_required=${tool.approvalRequired}, readonly=${tool.readonly}, idempotent=${tool.idempotent}. Use this loaded tool directly when the target is clear. If rate limited before dispatch, wait for retry_after_ms then resume the original invocation_id. On uncertain outcomes recover the original invocation_id; never create a replacement call.`,
       parameters: authorizationEnvelope(tool, shared.targets.map((target) => target.authorization.ref)),
       output: { schema: {}, render: (_arguments, value) => [{ type: 'text', text: safeJson(value) }] },
       execute: async (value, exec) => {
@@ -1406,24 +1771,27 @@ export class BailingHubAgentClientRuntime {
         const signature = invocationSignature(selected.ref, tool.name, selected.arguments)
         let binding = group.calls.get(exec.callId)
         if (binding && binding.signature !== signature) {
-          throw new Error('BailingHub invocation replay changed the original authorization, tool or arguments')
+          throw Object.assign(new Error('BailingHub invocation replay changed the original authorization, tool or arguments'), { publicCode: 'agent_invalid_request' })
         }
         if (!binding) {
           const target = shared.targets.find((entry) => entry.authorization.ref === selected.ref)
           if (!target) throw new Error('This tool is not available under the selected authorization')
           const current = target.currentRun.activeTools.find((entry) => entry.name === tool.name)
-          if (target.currentRun.status !== 'active' || !current || declarationKey(current) !== shared.key) {
-            throw new Error('This tool declaration is no longer active for the selected authorization')
+          if (!state.activeDefinitions.has(shared.name) || target.currentRun.status !== 'active' || !current || declarationKey(current) !== shared.key) {
+            throw Object.assign(new Error('This tool declaration is no longer active for the selected authorization'), { publicCode: 'tool_not_loaded', feedback: describeFailure({ publicCode: 'tool_not_loaded' }, { operation: 'invoke', dispatch: 'not_dispatched' }) })
           }
           // Freeze the revision as well as the key. A later search or default switch
           // must never reinterpret a replayed DSH call.
           const run = { ...target.currentRun, invocations: target.currentRun.invocations }
-          binding = { signature, state: target, run, tool, arguments: selected.arguments }
+          binding = { signature, state: target, run, tool, arguments: selected.arguments, registeredName: shared.name }
           group.calls.set(exec.callId, binding)
           const invocationId = digestId(target.sessionId, run.runId, exec.callId, tool.name)
+          binding.invocationId = invocationId
           state.authorizedInvocations.set(invocationId, binding)
           target.currentRun.toolCallIds.add(exec.callId)
         }
+        this.touchTool(state, shared.name)
+        touchCatalogTool(binding.state.currentRun, tool.name)
         const result = await this.executeTrackedInvocation(binding.state, binding.run, binding.tool, binding.arguments, exec)
         return authorizedResult(binding.state, result)
       },
@@ -1434,8 +1802,8 @@ export class BailingHubAgentClientRuntime {
     return {
       name: 'search_business_capabilities',
       description: group.crossSystem
-        ? 'Choose one authorized business target and find its capabilities. authorization_ref is required. query is the minimal task description sent to that target to open this turn; omit unrelated conversation and other systems\' data. This grants no new authority.'
-        : 'Find shared business tools within this session\'s authorizations. Optionally restrict the search to one authorization. This grants no new authority.',
+        ? 'Choose one authorized business target and find its capabilities. authorization_ref is required. query is the minimal task description sent to that target to open this turn; omit unrelated conversation and other systems\' data. This grants no new authority.' + ' ' + DISCOVERY_GUIDANCE
+        : 'Find shared business tools within this session\'s authorizations. Optionally restrict the search to one authorization. This grants no new authority.' + ' ' + DISCOVERY_GUIDANCE,
       parameters: {
         type: 'object', properties: {
           query: { type: 'string' }, limit: { type: 'integer', description: 'Maximum results from 1 to 12.' },
@@ -1454,7 +1822,7 @@ export class BailingHubAgentClientRuntime {
         const targets = group.targets.filter(({ state: target }) =>
           value.authorization_ref === undefined || target.authorization.ref === value.authorization_ref)
         if (!targets.length) throw new Error('Unknown authorization_ref')
-        // Serialize catalog replacement while allowing independent business calls.
+        // Serialize discovery updates while allowing independent business calls.
         const search = async () => {
           await this.assertActiveGroup(state, group, exec)
           const names = []
@@ -1474,19 +1842,21 @@ export class BailingHubAgentClientRuntime {
               const result = normalizeCapabilitySearchResponse(await transport.searchCapabilities(
                 { query, limit, runId: run.runId }, this.connectionOptions(target, exec.signal),
               ))
-              run.capabilityRevision = result.capabilityRevision
-              run.activeTools = result.tools
+              await this.assertActiveGroup(state, group, exec)
+              if (exec.signal?.aborted) throw abortError()
+              const update = mergeDiscoveredTools(run, result)
               names.push(...result.tools.map((tool) => tool.name))
-              results.push({ authorization_ref: target.authorization.ref, state: 'available' })
-            } catch {
-              if (entry.run) entry.run.activeTools = []
-              results.push({ authorization_ref: target.authorization.ref, state: 'unavailable' })
+              results.push({ authorization_ref: target.authorization.ref, state: 'available', discovery: result.discovery, ...update })
+            } catch (error) {
+              // A failed search does not prove that previously discovered tools vanished.
+              results.push({ authorization_ref: target.authorization.ref, state: 'unavailable', feedback: describeFailure(error, { operation: 'search' }) })
             }
           }
           await this.assertActiveGroup(state, group, exec)
           await this.replaceAuthorizedTools(state, group, names, targets.map(({ state: target }) => target.authorization.ref))
           return {
             authorizations: results,
+            ...this.getSessionToolState(state.sessionId),
             active_tools: group.shared.tools.map(({ tool, name, targets }) => ({
               name, authorization_refs: targets.map((target) => target.authorization.ref),
               ...(group.crossSystem ? { original_name: tool.name, system_ref: targets[0].authorization.systemRef } : {}),
@@ -1509,10 +1879,10 @@ export class BailingHubAgentClientRuntime {
       if (!value || Object.keys(value).some((key) => key !== 'invocation_id') || !INVOCATION_ID.test(value.invocation_id ?? '')) {
         throw new TypeError('Only the original invocation_id may be supplied for recovery')
       }
-      const binding = state.authorizedInvocations.get(value.invocation_id)
-      if (!binding) throw new Error('This invocation is not bound to an authorization in this session')
+      const binding = state.authorizedInvocations.get(value.invocation_id) ?? await this.recoverInvocationBinding(state, value.invocation_id)
+      await this.assertActiveGroup(state, group, exec)
         const entry = group.targets.find(({ state: target }) => target === binding.state)
-        if (group.crossSystem && !entry.run) {
+        if (group.lazy && !entry.run && !binding.run.taskBinding) {
           await this.ensureAuthorizedTarget(state, group, entry, `Check the original governed invocation ${value.invocation_id}; do not execute it again.`, exec)
         }
         const currentRun = entry.run
@@ -1521,21 +1891,29 @@ export class BailingHubAgentClientRuntime {
           currentRun.recoveries.set(value.invocation_id, binding.run.invocations.get(value.invocation_id))
         }
       const result = await this.resumeTrackedInvocation(binding.state, binding.run, value.invocation_id, exec.signal)
-      return authorizedResult(binding.state, result)
+      return group.single ? result : authorizedResult(binding.state, result)
     }
     return definition
   }
 
   async ensureAuthorizedTarget(state, group, entry, task, exec) {
     await this.assertActiveGroup(state, group, exec)
+    if (group.sessionTools && entry.run?.status === 'degraded' &&
+      entry.run.failure?.feedback?.category === 'transport_unavailable') {
+      entry.startPromise = undefined
+      entry.run = undefined
+    }
     if (!entry.startPromise && !entry.run) {
+      // startTurn is idempotent on the original client turn. A response loss
+      // must retry that exact projection, never silently replace its input.
+      entry.projectedClaim ??= { id: group.userMessageId, text: task }
       entry.startPromise = this.startRunOnce(entry.state, group.turn, exec.signal, false,
-        { id: group.userMessageId, text: task }).then(() => { entry.run = entry.state.runs.get(group.turn) })
+        entry.projectedClaim).then(() => { entry.run = entry.state.runs.get(group.turn) })
     }
     await entry.startPromise
     // A late original response only retains its link; it cannot reopen tools.
     await this.assertActiveGroup(state, group, exec)
-    if (entry.run?.status !== 'active') throw new Error('The selected target has no active run')
+    if (entry.run?.status !== 'active') throw entry.run?.failure ?? new Error('The selected target has no active run')
   }
 
   async startRunOnce(state, turn, signal, registerTools = true, projectedClaim) {
@@ -1554,15 +1932,19 @@ export class BailingHubAgentClientRuntime {
     const primary = claims[0]
     const userInput = claims.map((claim) => claim.text).filter(Boolean).join('\n\n')
     const staleTurn = () => (state.parentState ?? state).endedTurns.has(turn) ||
-      state.currentRun?.turn > turn || state.parentState?.currentRun?.turn > turn
+      state.currentRun?.turn > turn || state.parentState?.currentRun?.turn > turn ||
+      (state.parentState?.sessionToolCache && signal?.aborted)
 
     try {
       const transport = await this.getTransport()
-      await this.assertAuthorization(state)
+      if (!(state.parentState ?? state).taskManaged) await this.assertAuthorization(state)
       if (staleTurn()) {
         this.recordEndedRun(state, turn)
         return { removedNames }
       }
+      const taskBinding = await this.sessionTasks.binding(state.sessionId, { dispatch: true })
+      if (taskBinding && !this.invocationJournal.store) throw taskError('TASK_STORE_UNAVAILABLE')
+      if (staleTurn()) { this.recordEndedRun(state, turn); return { removedNames } }
       const response = await transport.startTurn(
         {
           clientConversationId: messageAlias('conversation', state.sessionId),
@@ -1572,8 +1954,10 @@ export class BailingHubAgentClientRuntime {
         },
         {
           ...this.connectionOptions(state, signal),
+          ...(taskBinding ? { taskBinding } : {}),
         },
       )
+      if (metadataHash(response.task_binding ?? null) !== metadataHash(taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
       const normalized = normalizeStartTurnResponse(response)
       // Record the original response linkage even if authorization is revoked
       // or the local turn is cancelled before its late response is processed.
@@ -1592,6 +1976,7 @@ export class BailingHubAgentClientRuntime {
       const run = {
         turn,
         status: 'active',
+        taskBinding,
         ...normalized,
         assistant: undefined,
         usages: [],
@@ -1600,6 +1985,7 @@ export class BailingHubAgentClientRuntime {
         completeSent: false,
         completion: undefined,
       }
+      if (state.parentState?.sessionToolCache) captureSessionTools(state.parentState, state, run)
       if (registerTools) await this.replaceActiveTools(state, run)
       state.runs.set(turn, run)
       state.currentRun = run
@@ -1641,29 +2027,149 @@ export class BailingHubAgentClientRuntime {
     }
   }
 
-  async replaceActiveTools(state, run) {
-    await this.clearActiveTools(state)
-    try {
-      for (const tool of run.activeTools) {
-        this.registerDefinition(state, this.definitionFor(state, run, tool))
-      }
-      this.registerDefinition(state, this.searchDefinitionFor(state, run))
-      this.registerDefinition(state, this.resumeDefinitionFor(state, run))
-    } catch (error) {
-      await this.clearActiveTools(state)
-      throw error
+  async replaceActiveTools(state, run, preferredNames = []) {
+    for (const name of [...preferredNames].reverse()) this.touchTool(state, name)
+    const sorted = [...run.activeTools].sort((a, b) => (state.toolUsage.get(b.name) ?? 0) - (state.toolUsage.get(a.name) ?? 0))
+    state.visibleToolNames = sorted.slice(0, VISIBLE_TOOL_LIMIT).map(tool => tool.name)
+    const definitions = sorted.map(tool => this.definitionFor(state, run, tool))
+    definitions.push(this.searchDefinitionFor(state, run), this.resumeDefinitionFor(state, run), this.inspectDefinitionFor(state, run))
+    this.registerArtifactTools(state, run, definitions)
+    await this.reconcileDefinitions(state, run, definitions)
+  }
+
+  touchTool(state, name) {
+    state.toolUsage.set(name, ++state.toolUseSequence)
+    if (state.activeDefinitions.has(name)) {
+      state.visibleToolNames = [name, ...state.visibleToolNames.filter(entry => entry !== name)].slice(0, VISIBLE_TOOL_LIMIT)
+    }
+  }
+
+  assertRegistryTurn(state, run) {
+    if (state.disposed || run.status !== 'active' || state.endedTurns.has(run.turn) ||
+      (state.currentRun && state.currentRun !== run && state.currentRun.turn >= run.turn)) throw abortError()
+  }
+
+  async reconcileDefinitions(state, run, definitions) {
+    this.assertRegistryTurn(state, run)
+    const desired = new Map(definitions.map(definition => [definition.name, definition]))
+    // Reuse unchanged registrations. Only retired or changed schemas are removed;
+    // unrelated tools and in-flight invocation bindings remain intact.
+    for (const [name, current] of state.activeDefinitions) {
+      const next = desired.get(name)
+      if (next && declarationKey(toolSchema(current)) === declarationKey(toolSchema(next))) continue
+      const dispose = state.activeDisposers.get(name)
+      state.activeDisposers.delete(name)
+      state.activeDefinitions.delete(name)
+      state.definitionSlots.delete(name)
+      state.toolsetGeneration += 1
+      await dispose?.()
+      this.assertRegistryTurn(state, run)
     }
+    for (const definition of definitions) {
+      this.assertRegistryTurn(state, run)
+      this.registerDefinition(state, definition, run)
+    }
+    state.toolsetGeneration += 1
   }
 
-  registerDefinition(state, definition) {
+  registerArtifactTools(state, run, definitions) {
+    const register = definition => definitions ? definitions.push(definition) : this.registerDefinition(state, definition)
+    if (!this.artifactSource) return
+    const assertActive = async (exec) => {
+      await this.sessionScopes.assertUsable(state.sessionId)
+      if (exec.agent !== state.agent || state.disposed || state.currentRun !== run || run.status !== 'active' || state.endedTurns.has(run.turn) || exec.signal?.aborted) throw abortError()
+    }
+    register({
+      name: 'list_generated_artifacts',
+      description: 'List images registered by this host and permitted for business use in this conversation, including generated images and user-provided images selected for that purpose. Returns opaque artifact references; never invent references or use local paths. Listing uploads no files. Chat attachments are not automatically registered or uploaded.',
+      parameters: { type: 'object', properties: {}, additionalProperties: false },
+      output: { schema: {}, render: (_args, value) => [{ type: 'text', text: safeJson(value) }] },
+      execute: async (args, exec) => {
+        await assertActive(exec)
+        if (Object.keys(args ?? {}).length) throw new TypeError('No parameters allowed')
+        const artifacts = await listArtifacts(this.artifactSource, state.sessionId)
+        await assertActive(exec)
+        return { artifacts }
+      },
+    })
+    const targets = state.authorizations ?? [state]
+    register({
+      name: 'upload_generated_artifacts',
+      description: 'Upload 1–8 registered images to ONE explicitly selected authorization when business use requires public URLs. Images may be generated or user-provided and explicitly selected for business use; they need not originate in this turn. Do not upload attachments merely because they appear in chat. Returns each image URL or error. Reuse ready URLs; retry pending items with the SAME artifact_ref and authorization, never rename or regenerate to bypass an error. The runtime handles recoverable upload run-link errors. Uploading does not update any product. Wait for every required image to be ready before submitting a complete gallery. Keep existing images unless the user asked to remove them. Business approvals still apply; uncertain business writes must resume their original invocation_id.',
+      parameters: { type: 'object', properties: {
+        authorization_ref: { type: 'string', enum: targets.map(x => x.authorization.ref) },
+        artifact_refs: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 8, uniqueItems: true },
+      }, required: ['authorization_ref', 'artifact_refs'], additionalProperties: false },
+      output: { schema: {}, render: (_args, value) => [{ type: 'text', text: safeJson(value) }] },
+      execute: async (args, exec) => {
+        await assertActive(exec)
+        const target = targets.find(x => x.authorization.ref === args?.authorization_ref)
+        const refs = args?.artifact_refs
+        if (!target || !Array.isArray(refs) || !refs.length || refs.length > 8 || new Set(refs).size !== refs.length || refs.some(x => typeof x !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(x)) || Object.keys(args).some(k => !['authorization_ref', 'artifact_refs'].includes(k))) throw new TypeError('Explicit selected authorization and registered artifact references are required')
+        const snapshot = this.sessionScopes.snapshot(state.sessionId)
+        const member = snapshot.authorizations.find(x => x.connectionKey === target.authorization.connectionKey)
+        const binding = { ...memberBinding(snapshot, member), sessionId: member.sessionId }
+        const transport = await this.getTransport()
+        const options = { ...this.connectionOptions(target, exec.signal), expectedBinding: binding }
+        // Cross-system targets are lazy: currentRun may still be from an older
+        // turn. Uploading alone neither starts a business run nor links that old run.
+        const targetRun = target.runs.get(run.turn)
+        const runId = targetRun?.status === 'active' && targetRun.turn === run.turn ? targetRun.runId : undefined
+        const results = []
+        for (const artifactRef of refs) {
+          try {
+            results.push(await deliverArtifact({ source: this.artifactSource, store: this.artifactStore, transport,
+              sessionId: state.sessionId, artifactRef, binding, options,
+              metadata: { clientConversationId: messageAlias('conversation', state.sessionId), clientTurnId: messageAlias('turn', state.sessionId, String(run.turn)),
+                ...(runId ? { runId } : {}) },
+              assertActive: async () => { await assertActive(exec); await this.assertAuthorization(target); await assertActive(exec) },
+            }))
+          } catch (error) { results.push(artifactFailure(error, artifactRef)) }
+        }
+        // A cancelled/ended turn cannot return an actionable URL or restore removed tools.
+        await assertActive(exec)
+        return { authorization_ref: target.authorization.ref, results, all_ready: results.every(x => x.state === 'ready'), business_operation_performed: false }
+      },
+    })
+  }
+
+  registerDefinition(state, definition, run = state.currentRun) {
     const existing = state.agent.ctx.tools.get?.(definition.name, state.agent)
-    if (existing !== undefined) {
-      throw new Error(`BailingHub tool conflicts with an existing DSH tool: ${definition.name}`)
+    const slot = state.definitionSlots.get(definition.name)
+    if (slot && existing === state.activeDefinitions.get(definition.name)) {
+      // The schema is identical. Capture the latest definition at call entry;
+      // never mutate the binding of a call that is already running.
+      slot.current = definition
+      return
     }
-    const disposer = state.agent.ctx.tools.register(definition)
-    state.activeDefinitions.set(definition.name, definition)
+    if (existing !== undefined) throw new Error(`BailingHub tool conflicts with an existing DSH tool: ${definition.name}`)
+    const nextSlot = { current: definition, run }
+    const registered = { ...definition, execute: async (args, exec) => {
+      const current = nextSlot.current
+      try {
+        if (exec.agent !== state.agent) throw Object.assign(new Error('The tool belongs to another session'),
+          { feedback: describeFailure({ code: 'agent_invalid_request' }, { operation: 'invoke', dispatch: 'not_dispatched' }) })
+        if (state.definitionSlots.get(definition.name) !== nextSlot) {
+          const feedback = this.originalCallFeedback(nextSlot.run, definition.name, exec.callId) ??
+            describeFailure({ code: 'tool_not_loaded' }, { operation: 'invoke', dispatch: 'not_dispatched' })
+          throw Object.assign(new Error('This tool registration was retired'), { feedback })
+        }
+        return await current.execute(args, exec)
+      } catch (error) {
+        const operation = definition.name === 'search_business_capabilities' ? 'search'
+          : definition.name === 'resume_governed_tool_invocation' ? 'resume' : definition.name === 'inspect_governed_tool_invocation' ? 'inspect' : 'invoke'
+        const failure = publicFailure(operation, error)
+        if (exec && typeof exec === 'object') this.toolFailures.set(exec, failure.feedback)
+        throw failure
+      }
+    } }
+    const disposer = state.agent.ctx.tools.register(registered)
+    state.definitionSlots.set(definition.name, nextSlot)
+    state.activeDefinitions.set(definition.name, registered)
     state.activeDisposers.set(definition.name, disposer)
     state.knownToolNames.add(definition.name)
+    state.toolsetGeneration += 1
+    state.status = { ...state.status, activeToolCount: [...state.activeDefinitions.keys()].filter(name => !RESERVED_TOOLS.has(name)).length }
   }
 
   invocationRecord(run, invocationId, details = {}) {
@@ -1692,9 +2198,19 @@ export class BailingHubAgentClientRuntime {
     return record
   }
 
-  runInvocationOperation(record, operation) {
+  serializeInvocation(sessionId, invocationId, operation) {
+    const key = `${sessionId}:${invocationId}`
+    const previous = this.invocationOperations.get(key) ?? Promise.resolve()
+    const result = previous.then(operation)
+    const tail = result.catch(() => {})
+    this.invocationOperations.set(key, tail)
+    void tail.finally(() => { if (this.invocationOperations.get(key) === tail) this.invocationOperations.delete(key) })
+    return result
+  }
+
+  runInvocationOperation(record, operation, sessionId) {
     if (record.operation) return record.operation
-    const promise = Promise.resolve().then(operation)
+    const promise = this.serializeInvocation(sessionId, record.invocationId, operation)
     record.operation = promise
     void promise.finally(() => {
       if (record.operation === promise) record.operation = undefined
@@ -1702,45 +2218,89 @@ export class BailingHubAgentClientRuntime {
     return promise
   }
 
+  async rememberInvocationResult(record, result, { freshDispatch = false } = {}) {
+    record.latest = result
+    const delay = result?.retry_after_ms
+    record.resumeNotBefore = result?.state === 'rejected_before_dispatch' && result.auto_retry_allowed === true
+      && Number.isSafeInteger(delay) && delay > 0 && delay <= 86_400_000
+      ? !freshDispatch && record.journalEntry?.resultHash === metadataHash(result) ? record.journalEntry.retryAt : this.recovery.now() + delay : 0
+    if (record.journalEntry) {
+      const next = { ...record.journalEntry, lastKnownState: result.state,
+        retryAt: record.resumeNotBefore, resultHash: metadataHash(result) }
+      await this.invocationJournal.update(record.journalSessionId, next, record.journalEntry)
+      record.journalEntry = next
+    }
+  }
+
   async waitForInvocation(state, record, options = {}) {
     const deadline = this.recovery.now() + this.recovery.maxWaitMilliseconds
     let attempts = 0
     let immediate = options.immediate === true || record.latest === undefined
 
     while (!invocationIsTerminal(record.latest)) {
+      if (options.signal?.aborted) throw abortError()
       this.assertLiveTargetTurn(state, options.activeTurn)
       const remaining = deadline - this.recovery.now()
       if (remaining <= 0 || attempts >= this.recovery.maxAttempts) {
         if (record.latest) {
-          return timedOutInvocationResult(record.latest, record.invocationId, attempts)
+          return timedOutInvocationResult(record.latest, record.invocationId, attempts, options.managed)
         }
-        throw acceptedUnknownFailure(options.operation ?? 'resume', record.invocationId)
+        const failure = acceptedUnknownFailure(options.operation ?? 'resume', record.invocationId)
+        if (options.managed) failure.feedback.next_action = 'inspect_original'
+        throw failure
       }
 
-      if (!immediate) {
-        await this.recovery.sleep(
-          Math.min(this.recovery.pollIntervalMilliseconds, remaining),
-          options.signal,
-        )
+      const rateWait = options.managed ? 0 : Math.max(0, (record.resumeNotBefore ?? 0) - this.recovery.now())
+      if (rateWait >= remaining && record.latest) {
+        const deferred = timedOutInvocationResult(record.latest, record.invocationId, attempts, options.managed)
+        deferred.agent_client_wait.state = 'rate_limited'
+        deferred.agent_client_wait.retry_after_ms = rateWait
+        deferred.agent_client_wait.next_action = 'Wait for retry_after_ms, then resume this exact invocation_id. Do not call the business tool again or switch authorization.'
+        return deferred
       }
+      const pause = Math.max(rateWait, immediate ? 0 : this.recovery.pollIntervalMilliseconds)
+      if (pause > 0) await this.recovery.sleep(Math.min(pause, remaining), options.signal)
+      if (options.signal?.aborted) throw abortError()
+      this.assertLiveTargetTurn(state, options.activeTurn)
+      if (this.recovery.now() >= deadline) continue
       immediate = false
       attempts += 1
 
       try {
         const transport = await this.getTransport()
-        await this.assertAuthorization(state)
+        if (!options.managed) {
+          await this.sessionScopes.get(state.sessionId)
+          await this.assertAuthorization(state)
+        }
         this.assertLiveTargetTurn(state, options.activeTurn)
-        const result = invocationResult(
-          await transport.resume(
-            record.invocationId,
-            {},
-            this.connectionOptions(state, options.signal),
-          ),
-          record.invocationId,
-        )
-        if (result) record.latest = result
+        const result = options.managed
+          ? (await this.inspectTrackedReceipt(state, record, options.signal)).result
+          : invocationResult(await transport.resume(record.invocationId, {}, this.connectionOptions(state, options.signal)), record.invocationId, 'resume')
+        if (result) await this.rememberInvocationResult(record, result, { freshDispatch: !options.managed })
+        if (options.managed) {
+          this.assertLiveTargetTurn(state, options.activeTurn)
+          if (options.signal?.aborted) throw abortError()
+        }
       } catch (error) {
-        if (!isAcceptedUnknown(error)) throw publicFailure('resume', error)
+        if (isInvocationNotFound(error)) {
+          // A late recovery response cannot replace cancellation or revive the
+          // ended turn. Preserve the same guard previously reached by polling.
+          try {
+            if (options.signal?.aborted) throw abortError()
+            this.assertLiveTargetTurn(state, options.activeTurn)
+          } catch (cancelled) {
+            throw publicFailure(options.managed ? 'inspect' : 'resume', cancelled, { invocationId: record.invocationId })
+          }
+        }
+        if (isInvocationNotFound(error) || !isAcceptedUnknown(error)) {
+          const failure = publicFailure(options.managed ? 'inspect' : 'resume', error, { invocationId: record.invocationId })
+          if (options.managed && ['transport_unavailable', 'unknown_failure', 'invocation_outcome_unknown'].includes(failure.feedback.category)) {
+            failure.feedback.next_action = 'inspect_original'
+            failure.feedback.retryable = false
+            failure.feedback.original_outcome = 'unverified'
+          }
+          throw failure
+        }
       }
     }
 
@@ -1756,16 +2316,39 @@ export class BailingHubAgentClientRuntime {
     })
 
     return this.runInvocationOperation(record, async () => {
-      await this.assertAuthorization(state)
+      if (!run.taskBinding) await this.assertAuthorization(state)
       this.assertLiveTargetTurn(state, run.turn)
+      if (exec.signal?.aborted) throw abortError()
+      await this.verifyInvocationJournal(state, invocationId, record)
+      if (!run.taskBinding || record.invoked || invocationIsTerminal(record.latest)) {
+        const taskBinding = await this.sessionTasks.binding(state.sessionId, { dispatch: true })
+        if (metadataHash(taskBinding ?? null) !== metadataHash(run.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
+      }
       if (invocationIsTerminal(record.latest)) return cloneJson(record.latest)
 
       if (!record.invoked) {
-        record.invoked = true
         try {
           const transport = await this.getTransport()
           this.assertLiveTargetTurn(state, run.turn)
-          const result = invocationResult(
+          if (exec.signal?.aborted) throw abortError()
+          const reservation = await this.invocationJournal.reserve(state.sessionId,
+            this.invocationMetadata(state, run, tool, clonedArguments, exec, invocationId))
+          if (reservation.supported) {
+            record.journalEntry = reservation.entry
+            record.journalSessionId = state.sessionId
+            record.resumeNotBefore = reservation.entry.retryAt
+          }
+          if (reservation.supported && !run.taskBinding) {
+            await this.sessionScopes.get(state.sessionId)
+            await this.sessionScopes.assertUsable(state.sessionId)
+          }
+          const currentTask = await this.sessionTasks.binding(state.sessionId, { dispatch: true })
+          if (metadataHash(currentTask ?? null) !== metadataHash(run.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
+          this.sessionScopes.assertCurrent(state.sessionId)
+          this.assertLiveTargetTurn(state, run.turn)
+          if (exec.signal?.aborted) throw abortError()
+          record.invoked = true
+          const result = reservation.created ? invocationResult(
             await transport.invoke(
               {
                 invocationId,
@@ -1777,12 +2360,13 @@ export class BailingHubAgentClientRuntime {
               this.connectionOptions(state, exec.signal),
             ),
             invocationId,
-          )
-          if (result) record.latest = result
+          ) : undefined
+          if (result) await this.rememberInvocationResult(record, result, { freshDispatch: true })
         } catch (error) {
           if (!isAcceptedUnknown(error)) {
-            record.invoked = false
-            throw publicFailure('invoke', error)
+            const failure = publicFailure('invoke', error, { invocationId, dispatch: record.invoked ? 'unknown' : 'not_dispatched' })
+            if (failure.feedback.dispatch === 'not_dispatched') record.invoked = false
+            throw failure
           }
         }
       }
@@ -1791,32 +2375,76 @@ export class BailingHubAgentClientRuntime {
       return this.waitForInvocation(state, record, {
         immediate: record.latest === undefined,
         operation: 'business-tool',
+        managed: Boolean(run.taskBinding),
         activeTurn: run.turn,
         signal: exec.signal,
       })
-    })
+    }, state.sessionId)
   }
 
   resumeTrackedInvocation(state, run, invocationId, signal) {
     const record = this.invocationRecord(run, invocationId, { invoked: true })
     const activeTurn = state.parentState?.currentRun?.turn
     return this.runInvocationOperation(record, async () => {
-      await this.assertAuthorization(state)
+      if (!run.taskBinding) {
+        await this.sessionScopes.get(state.sessionId)
+        await this.assertAuthorization(state)
+      }
       this.assertLiveTargetTurn(state, activeTurn)
+      if (signal?.aborted) throw abortError()
+      await this.verifyInvocationJournal(state, invocationId, record)
+      const taskBinding = await this.sessionTasks.binding(state.sessionId, { dispatch: true })
+      if (metadataHash(taskBinding ?? null) !== metadataHash(run.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
       if (invocationIsTerminal(record.latest)) return cloneJson(record.latest)
+      const receiptRecovery = Boolean(run.taskBinding) || this.hostReceiptBindings.has(`${state.sessionId}:${invocationId}`)
+      if (receiptRecovery) {
+        // A panel action may have completed this original invocation while this
+        // model action waited for the shared lock. Never issue a second POST.
+        const receipt = await this.inspectTrackedReceipt(state, record, signal)
+        if (receipt.result) await this.rememberInvocationResult(record, receipt.result)
+        this.assertLiveTargetTurn(state, activeTurn)
+        if (signal?.aborted) throw abortError()
+        if (invocationIsTerminal(record.latest)) return cloneJson(record.latest)
+        if (receipt.dispatch_state !== 'not_dispatched' || receipt.journal_state !== 'absent' || !invocationNeedsResume(receipt.result)) {
+          return this.waitForInvocation(state, record, { immediate: true, managed: true, operation: 'resume', activeTurn, signal })
+        }
+        const rateWait = Math.max(0, (record.resumeNotBefore ?? 0) - this.recovery.now())
+        if (rateWait >= this.recovery.maxWaitMilliseconds && record.latest) return timedOutInvocationResult(record.latest, invocationId, 0, true)
+        if (rateWait) {
+          await this.recovery.sleep(rateWait, signal)
+          // A wait separates dispatch from its proof; validate the whole group
+          // again after the delay, never reuse a prior operation's snapshot.
+          const afterWait = await this.sessionTasks.binding(state.sessionId, { dispatch: true })
+          if (metadataHash(afterWait ?? null) !== metadataHash(run.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
+          await this.verifyInvocationJournal(state, invocationId, record)
+        }
+        this.assertLiveTargetTurn(state, activeTurn)
+        if (signal?.aborted) throw abortError()
+        const transport = await this.getTransport()
+        this.sessionScopes.assertCurrent(state.sessionId)
+        this.assertLiveTargetTurn(state, activeTurn)
+        if (signal?.aborted) throw abortError()
+        const result = invocationResult(await transport.resume(invocationId, {}, this.connectionOptions(state, signal)), invocationId, 'resume')
+        if (result) await this.rememberInvocationResult(record, result, { freshDispatch: true })
+        this.assertLiveTargetTurn(state, activeTurn)
+        if (signal?.aborted) throw abortError()
+      }
       return this.waitForInvocation(state, record, {
         immediate: true,
+        managed: receiptRecovery,
         operation: 'resume',
         activeTurn,
         signal,
       })
-    })
+    }, state.sessionId)
   }
 
   assertLiveTargetTurn(state, turn) {
-    const parent = state.parentState
-    if (parent?.crossSystem && (parent.disposed || parent.currentRun?.turn !== turn ||
-      parent.currentRun?.status !== 'active' || parent.endedTurns.has(turn))) throw abortError()
+    const owner = state.parentState ?? state
+    // A frozen invocation may retain its original run, but cannot reactivate it.
+    // Cross-turn recovery explicitly supplies the current active turn instead.
+    if (owner.disposed || (turn !== undefined && owner.currentRun?.turn !== turn) ||
+      owner.currentRun?.status !== 'active' || owner.endedTurns.has(owner.currentRun?.turn)) throw abortError()
   }
 
   definitionFor(state, run, tool) {
@@ -1829,7 +2457,7 @@ export class BailingHubAgentClientRuntime {
     ].join(', ')
     return {
       name: tool.name,
-      description: `${tool.description}\nBailingHub governance metadata: ${governance}.`,
+      description: `${tool.description}\nBailingHub governance metadata: ${governance}. Use this loaded tool directly when the target is clear. If rate limited before dispatch, wait for retry_after_ms then resume the original invocation_id. On uncertain outcomes recover the original invocation_id; never create a replacement call.`,
       parameters: cloneJson(tool.parameters),
       output: {
         schema: {},
@@ -1844,13 +2472,19 @@ export class BailingHubAgentClientRuntime {
         run.calls ??= new Map()
         const signature = invocationSignature(state.authorization.connectionKey, tool.name, arguments_)
         let binding = run.calls.get(exec.callId)
-        if (binding && binding.signature !== signature) throw new Error('BailingHub invocation replay changed the original tool or arguments')
+        if (binding && binding.signature !== signature) throw Object.assign(new Error('BailingHub invocation replay changed the original tool or arguments'), { publicCode: 'agent_invalid_request' })
         if (!binding) {
-          binding = { run: { ...run, invocations: run.invocations }, tool, signature }
+          if (!state.activeDefinitions.has(tool.name) || !run.activeTools.some((current) => declarationKey(current) === declarationKey(tool))) {
+            throw Object.assign(new Error('This business tool is no longer loaded'), { feedback: describeFailure({ publicCode: 'tool_not_loaded' }, { operation: 'invoke', dispatch: 'not_dispatched' }) })
+          }
+          binding = { run: { ...run, invocations: run.invocations }, tool, signature, registeredName: tool.name }
           run.calls.set(exec.callId, binding)
           const id = digestId(state.sessionId, run.runId, exec.callId, tool.name)
+          binding.invocationId = id
           state.invocationBindings.set(id, binding)
         }
+        this.touchTool(state, tool.name)
+        touchCatalogTool(run, tool.name)
         return this.executeTrackedInvocation(state, binding.run, binding.tool, arguments_, exec)
       },
     }
@@ -1859,7 +2493,7 @@ export class BailingHubAgentClientRuntime {
   searchDefinitionFor(state, run) {
     return {
       name: 'search_business_capabilities',
-      description: 'Search within the authorized BailingHub workspace and replace this session run\'s active business-tool set with up to 12 relevant candidates. This grants no new authority.',
+      description: 'Search within the authorized BailingHub workspace and add up to 12 relevant candidates to this turn\'s retained tools. This grants no new authority. ' + DISCOVERY_GUIDANCE,
       parameters: {
         type: 'object',
         properties: {
@@ -1882,36 +2516,97 @@ export class BailingHubAgentClientRuntime {
         if (!query || !Number.isInteger(limit) || limit < 1 || limit > MAX_ACTIVE_TOOLS) {
           throw new TypeError('query is required and limit must be an integer from 1 to 12')
         }
-        try {
-          const transport = await this.getTransport()
-          await this.assertAuthorization(state)
-          const result = normalizeCapabilitySearchResponse(
-            await transport.searchCapabilities(
-              { query, limit, runId: run.runId },
-              this.connectionOptions(state, exec.signal),
-            ),
-          )
-          run.capabilityRevision = result.capabilityRevision
-          run.activeTools = result.tools
-          await this.replaceActiveTools(state, run)
-          state.status = {
-            ...state.status,
-            capabilityRevision: run.capabilityRevision,
-            activeToolCount: run.activeTools.length,
-          }
-          return {
-            schema: result.schema,
-            capability_revision: result.capabilityRevision,
-            active_tools: result.tools.map((tool) => ({
-              name: tool.name,
-              scope: tool.scope,
-              risk: tool.risk,
-              approval_required: tool.approvalRequired,
-            })),
+        const search = async () => {
+          this.assertRegistryTurn(state, run)
+          if (exec.signal?.aborted) throw abortError()
+          try {
+            const transport = await this.getTransport()
+            await this.assertAuthorization(state)
+            const result = normalizeCapabilitySearchResponse(
+              await transport.searchCapabilities(
+                { query, limit, runId: run.runId },
+                this.connectionOptions(state, exec.signal),
+              ),
+            )
+            this.assertRegistryTurn(state, run)
+            if (exec.signal?.aborted) throw abortError()
+            await this.assertAuthorization(state)
+            this.assertRegistryTurn(state, run)
+            if (exec.signal?.aborted) throw abortError()
+            const update = mergeDiscoveredTools(run, result)
+            await this.replaceActiveTools(state, run, result.tools.map(tool => tool.name))
+            state.status = {
+              ...state.status,
+              capabilityRevision: run.capabilityRevision,
+              activeToolCount: run.activeTools.length,
+            }
+            return {
+              schema: result.schema,
+              discovery: result.discovery,
+              ...this.getSessionToolState(state.sessionId),
+              ...update,
+              capability_revision: result.capabilityRevision,
+              active_tools: run.activeTools.map((tool) => ({
+                name: tool.name,
+                scope: tool.scope,
+                risk: tool.risk,
+                approval_required: tool.approvalRequired,
+              })),
+            }
+          } catch (error) {
+            throw publicFailure('searchCapabilities', error)
           }
-        } catch (error) {
-          throw publicFailure('searchCapabilities', error)
         }
+        const pending = (run.searchPromise ?? Promise.resolve()).then(search)
+        run.searchPromise = pending.catch(() => {})
+        return pending
+      },
+    }
+  }
+
+  async inspectTrackedReceipt(state, record, signal) {
+    if (!record.journalEntry) throw recoveryError('invocation_binding_unavailable', record.invocationId)
+    await this.verifyInvocationJournal(state, record.invocationId, record)
+    const taskBinding = await this.sessionTasks.binding(state.sessionId)
+    if (metadataHash(taskBinding ?? null) !== metadataHash(record.journalEntry.taskBinding ?? null)) throw taskError('TASK_BINDING_CONFLICT')
+    const transport = await this.getTransport()
+    if (typeof transport.inspectInvocation !== 'function') throw taskError('TASK_UNSUPPORTED')
+    return this.checkedInvocationReceipt(await transport.inspectInvocation(record.invocationId, this.connectionOptions(state, signal)), record.journalEntry)
+  }
+
+  checkedInvocationReceipt(receipt, original) {
+    if (receipt?.schema_version !== 'bailing.agent-invocation-receipt.v1' || receipt.read_only !== true || receipt.business_operation_performed !== false ||
+      receipt.invocation_id !== original.id || receipt.agent_run_id !== original.runId || receipt.route !== original.target.workspace || receipt.tool !== original.tool ||
+      !['not_dispatched', 'attempted', 'unknown'].includes(receipt.dispatch_state) ||
+      !['absent', 'dispatching', 'response_recorded', 'completed', 'uncertain', 'evidence_degraded', 'unknown'].includes(receipt.journal_state)) throw recoveryError('invocation_binding_conflict', original.id)
+    if (receipt.result !== null) {
+      receipt.result = invocationResult(receipt.result, original.id, 'inspect')
+      if (!receipt.result || receipt.result.route !== original.target.workspace || receipt.result.tool !== original.tool) throw recoveryError('invocation_binding_conflict', original.id)
+    }
+    return receipt
+  }
+
+  inspectDefinitionFor(state, run) {
+    return { name: 'inspect_governed_tool_invocation',
+      description: 'Read the original governed invocation receipt without continuing execution, consuming approval or creating a run. Use only its original invocation_id. A missing or unavailable receipt does not prove the operation never ran. Task cancellation remains in force even when a late original result succeeds.',
+      parameters: { type: 'object', properties: { invocation_id: { type: 'string' } }, required: ['invocation_id'], additionalProperties: false },
+      output: { schema: {}, render: (_args, value) => [{ type: 'text', text: safeJson(value) }] },
+      execute: async (value, exec) => {
+        if (exec.agent !== state.agent || state.currentRun !== run || run.status !== 'active' || exec.signal?.aborted) throw abortError()
+        if (!value || Object.keys(value).some(key => key !== 'invocation_id') || !INVOCATION_ID.test(value.invocation_id ?? '')) throw new TypeError('Only the original invocation_id is accepted')
+        if (!state.taskManaged) await this.sessionScopes.get(state.sessionId)
+        const binding = (state.authorizations ? state.authorizedInvocations : state.invocationBindings).get(value.invocation_id) ?? await this.recoverInvocationBinding(state, value.invocation_id)
+        const record = binding.run.invocations.get(value.invocation_id)
+        return this.serializeInvocation(state.sessionId, value.invocation_id, async () => {
+          this.assertLiveTargetTurn(binding.state, run.turn)
+          if (exec.signal?.aborted) throw abortError()
+          if (!binding.run.taskBinding) await this.assertAuthorization(binding.state)
+          const receipt = await this.inspectTrackedReceipt(binding.state, record, exec.signal)
+          if (receipt.result) await this.rememberInvocationResult(record, receipt.result)
+          this.assertLiveTargetTurn(binding.state, run.turn)
+          if (exec.signal?.aborted) throw abortError()
+          return receipt
+        })
       },
     }
   }
@@ -1919,7 +2614,7 @@ export class BailingHubAgentClientRuntime {
   resumeDefinitionFor(state, run) {
     return {
       name: 'resume_governed_tool_invocation',
-      description: 'Recover the exact governed BailingHub invocation after an uncertain outcome, pending approval, or in-progress response. This never creates a replacement invocation.',
+      description: 'Explicitly continue the exact governed BailingHub invocation after an uncertain outcome, pending approval, in-progress response, or pre-dispatch rate limit. Honor retry_after_ms before resuming; never switch authorization or create a replacement invocation. After reopening the same session, the host must retain its invocation store. Stored last-known states are not verified outcomes. Recovery can continue an approved original operation; it is not a read-only status check. If local recovery storage is unavailable, restore it before retrying. If invocation_not_found says inspect_original, stop automatic retries and verify the original execution evidence; it does not prove the business action never ran.',
       parameters: {
         type: 'object',
         properties: {
@@ -1944,8 +2639,9 @@ export class BailingHubAgentClientRuntime {
           throw new TypeError('invocation_id must be a 64-character lowercase digest')
         }
         if (Object.keys(arguments_).some((key) => key !== 'invocation_id')) throw new TypeError('Only the original invocation_id may be supplied for recovery')
-        const binding = state.invocationBindings.get(invocationId)
-        if (!binding) throw new Error('This invocation is not bound to an authorization in this session')
+        const binding = state.invocationBindings.get(invocationId) ?? await this.recoverInvocationBinding(state, invocationId)
+        run.recoveries ??= new Map()
+        run.recoveries.set(invocationId, binding.run.invocations.get(invocationId))
         return this.resumeTrackedInvocation(state, binding.run, invocationId, exec.signal)
       },
     }
@@ -1975,12 +2671,14 @@ export class BailingHubAgentClientRuntime {
       sections = replaceNamed(sections, {
         name: 'bailinghub:agent-client-profile', order: 20,
         text: [
-          run.crossSystem
+          run.sessionTools ? SESSION_TOOL_GUIDANCE : run.crossSystem
             ? 'BailingHub cross-system targets are selected. First choose the intended authorization_ref and call search_business_capabilities with a minimal target-specific task. Only that target receives the task and loads its context; no target is loaded automatically. Tool names are scoped aliases; use the tool only with one of its enumerated authorizations.'
             : 'BailingHub same-system authorizations are active. Shared tools require an authorization_ref on every call.',
           'Choose only the account(s) intended by the user. Never infer an account from list order or the default connection.',
           SYSTEM_DESCRIPTION_GUIDANCE,
           SUBJECT_DISPLAY_GUIDANCE,
+          ...(run.sessionTools ? [] : [DISCOVERY_GUIDANCE]),
+          `Current tool set: ${safeJson(this.getSessionToolState(state.sessionId))}`,
           'All declared account rules remain scoped to their authorization. Do not mix records, identifiers, memory or knowledge between accounts. Only transfer data when the user explicitly requests that permitted action.',
           ...(run.crossSystem ? [
             'Plan each step with its system, account and prerequisites. Check each result before running dependent steps; report completed, awaiting-approval, failed and not-started separately. A selected account is not permission to publish or bypass approval.',
@@ -1989,7 +2687,7 @@ export class BailingHubAgentClientRuntime {
           ] : []),
           `Authorization directory: ${safeJson(directory)}`,
           `Conflicting tool declarations (unavailable): ${safeJson(run.shared?.conflicts ?? [])}`,
-          `Additional tools omitted by the shared budget: ${run.shared?.omitted ?? 0}`,
+          `Known tools omitted by the retained registry budget: ${run.shared?.omitted ?? 0}`,
           'Recover a pending call only with its original invocation_id. Never repeat a write with another authorization or a new invocation id.',
           ...profiles,
         ].join('\n\n'),
@@ -2004,12 +2702,14 @@ export class BailingHubAgentClientRuntime {
         }
       }
     } else {
-      sections = replaceNamed(sections, profileSection(state, run))
+      const profile = profileSection(state, run)
+      sections = replaceNamed(sections, { ...profile, text: profile.text + `\nCurrent tool set: ${safeJson(this.getSessionToolState(state.sessionId))}` })
       for (const entry of contextEntries(run)) contexts = replaceNamed(contexts, entry)
     }
 
     const byName = new Map(tools.map((tool) => [tool.name, tool]))
     for (const definition of state.activeDefinitions.values()) {
+      if (!RESERVED_TOOLS.has(definition.name) && !state.visibleToolNames.includes(definition.name)) continue
       byName.set(definition.name, toolSchema(definition))
     }
     tools = [...byName.values()]
@@ -2486,8 +3186,11 @@ export class BailingHubAgentClientRuntime {
         ),
       )
     } catch (error) {
+      if (isInvocationNotFound(error)) {
+        throw publicFailure('resume', options.signal?.aborted ? abortError() : error, { invocationId: id })
+      }
       if (isAcceptedUnknown(error)) throw acceptedUnknownFailure('resume', id)
-      throw publicFailure('resume', error)
+      throw publicFailure('resume', error, { invocationId: id })
     }
   }
 
@@ -2513,6 +3216,95 @@ export class BailingHubAgentClientRuntime {
     }
   }
 
+  // Read-only host seam: it neither discovers tools nor validates over HTTP.
+  getSessionToolState(sessionId) {
+    const state = this.statesBySessionId.get(String(sessionId))
+    const run = state?.currentRun
+    let availability = !state ? 'unknown' : state.disposed || run?.status !== 'active' ? 'inactive' : 'active'
+    if (availability === 'active') {
+      try { this.sessionScopes.assertCurrent(state.sessionId) }
+      catch { availability = 'blocked' }
+    }
+    const names = availability === 'active'
+      ? [...state.activeDefinitions.keys()].filter((name) => !RESERVED_TOOLS.has(name)) : []
+    const sessionView = state?.sessionToolCache ? sessionToolView(state, run, availability === 'active') : undefined
+    const activeTools = sessionView ? sessionView.active_tools : run?.multi ? (run.shared?.tools ?? []).filter((entry) => names.includes(entry.name)).map((entry) => ({
+      name: entry.name, authorization_refs: entry.targets.map((target) => target.authorization.ref),
+      ...(run.crossSystem ? { original_name: entry.tool.name, system_ref: entry.targets[0].authorization.systemRef } : {}),
+    })) : names.map((name) => ({ name }))
+    const catalogConflictCount = run?.multi
+      ? run.targets.reduce((sum, entry) => sum + (entry.run?.catalogConflicts?.size ?? 0), 0)
+      : run?.catalogConflicts?.size ?? 0
+    return {
+      state: availability,
+      ...(this.sessionTasks.entry(String(sessionId)).record || this.sessionTasks.entry(String(sessionId)).failure ? { task: this.sessionTaskView(String(sessionId)) } : {}),
+      toolset: {
+        update: 'merge', scope: 'dsh_session', lifetime: 'active_turn',
+        ...(sessionView ? { reuse: 'session_runtime', cached_count: sessionView.cached_tools.length } : {}),
+        generation: state?.toolsetGeneration ?? 0, active_count: activeTools.length, limit: RETAINED_TOOL_LIMIT,
+        visible_count: activeTools.filter(tool => state?.visibleToolNames.includes(tool.name)).length, visible_limit: VISIBLE_TOOL_LIMIT,
+        retained_outside_window_count: activeTools.filter(tool => !state?.visibleToolNames.includes(tool.name)).length,
+        omitted_tool_count: run?.shared?.omitted ?? 0,
+        conflicting_tool_count: (run?.shared?.conflicts.length ?? 0) + catalogConflictCount,
+        catalog_conflict_count: catalogConflictCount,
+      },
+      active_tools: activeTools,
+      visible_tools: activeTools.filter(tool => state?.visibleToolNames.includes(tool.name)),
+      ...(sessionView ? { cached_tools: sessionView.cached_tools, targets: sessionView.targets,
+        cache: { lifetime: sessionView.cache.lifetime, target_count: sessionView.cache.targetCount,
+          tool_count: sessionView.cache.toolCount, bytes: sessionView.cache.bytes,
+          limit: sessionView.cache.maxTools, byte_limit: sessionView.cache.maxBytes } } : {}),
+    }
+  }
+
+  // A custom host may call this only after its registry reports UNKNOWN_TOOL.
+  // Ownership and retirement are checked locally; arbitrary names are untouched.
+  getToolDispatchFeedback(sessionId, { toolName, callId, errorCode } = {}) {
+    if (errorCode !== 'UNKNOWN_TOOL') return null
+    const state = this.statesBySessionId.get(String(sessionId))
+    if (!state || RESERVED_TOOLS.has(toolName) || !state.knownToolNames.has(toolName) || state.activeDefinitions.has(toolName)) return null
+    if (state.agent.ctx.tools.get?.(toolName, state.agent) !== undefined) return null
+    const view = this.getSessionToolState(sessionId)
+    if (view.state !== 'active') return describeFailure(
+      view.state === 'blocked' ? { code: 'SESSION_SCOPE_UNAVAILABLE' } : Object.assign(new Error(), { name: 'AbortError' }),
+      { operation: 'tool_dispatch', origin: 'host', dispatch: 'not_dispatched' },
+    )
+    return this.originalCallFeedback(state.currentRun, toolName, callId) ??
+      describeFailure({ code: 'tool_not_loaded' }, { operation: 'tool_dispatch', origin: 'host', dispatch: 'not_dispatched' })
+  }
+
+  originalCallFeedback(run, toolName, callId) {
+    const binding = typeof callId === 'string' ? run?.calls?.get(callId) : undefined
+    if (binding?.registeredName !== toolName || !binding.invocationId) return null
+    const record = binding.run.invocations.get(binding.invocationId)
+    const feedback = describeFailure({ code: 'tool_not_loaded' }, {
+      operation: 'tool_dispatch', origin: 'host', invocationId: binding.invocationId,
+      dispatch: record?.invoked === false ? 'not_dispatched' : record?.invoked === true ? 'attempted' : 'unknown',
+    })
+    feedback.next_action = record?.invoked === false && !record.latest ? 'rediscover'
+      : record?.invoked === true && (!record.latest || invocationNeedsResume(record.latest)) ? 'resume_original' : 'inspect_original'
+    feedback.retryable = ['resume_original', 'rediscover'].includes(feedback.next_action)
+    return feedback
+  }
+
+  async onToolExecute(exec, next) {
+    const state = exec.agent && this.statesByAgent.get(exec.agent)
+    const result = await next()
+    if (!state || !result?.isError) return result
+    const captured = this.toolFailures.get(exec)
+    this.toolFailures.delete(exec)
+    const feedback = captured ?? this.getToolDispatchFeedback(state.sessionId, {
+      toolName: exec.name, callId: exec.callId, errorCode: result.error?.info?.code,
+    })
+    if (!feedback) return result
+    return {
+      ...result,
+      error: { ...result.error, message: feedback.message },
+      meta: { ...result.meta, bailinghub: { feedback } },
+      content: [{ type: 'text', text: safeJson({ feedback }) }],
+    }
+  }
+
   inspectSession(sessionId) {
     const state = this.statesBySessionId.get(String(sessionId))
     return state ? sanitizePublicValue(state.status) : { state: 'unknown' }
@@ -2520,8 +3312,13 @@ export class BailingHubAgentClientRuntime {
 
   async clearActiveTools(state) {
     const disposers = [...state.activeDisposers.values()]
+    if (state.activeDefinitions.size) state.toolsetGeneration += 1
     state.activeDisposers.clear()
     state.activeDefinitions.clear()
+    state.definitionSlots.clear()
+    state.visibleToolNames = []
+    if (!state.sessionToolCache) state.toolUsage.clear()
+    state.status = { ...state.status, activeToolCount: 0 }
     const pending = []
     for (const dispose of disposers) {
       try {
@@ -2540,6 +3337,9 @@ export class BailingHubAgentClientRuntime {
   }
 
   async disposeSession(sessionId) {
+    this.hostActionControllers.get(String(sessionId))?.abort()
+    this.hostActionControllers.delete(String(sessionId))
+    for (const key of this.hostReceiptBindings) if (key.startsWith(`${sessionId}:`)) this.hostReceiptBindings.delete(key)
     this.observedSessions.delete(String(sessionId))
     this.observedConversationStarts.delete(String(sessionId))
     const state = this.statesBySessionId.get(String(sessionId))
@@ -2550,6 +3350,7 @@ export class BailingHubAgentClientRuntime {
   async disposeState(state) {
     if (state.disposed) return
     state.disposed = true
+    state.sessionToolCache?.clear()
     for (const controller of state.systemInfoLoads.values()) controller.abort()
     for (const run of state.runs.values()) run.abortController?.abort()
     await this.clearActiveTools(state)
@@ -2562,6 +3363,10 @@ export class BailingHubAgentClientRuntime {
   }
 
   async dispose() {
+    this.disposed = true
+    for (const controller of this.hostActionControllers.values()) controller.abort()
+    this.hostActionControllers.clear()
+    this.hostReceiptBindings.clear()
     this.observedSessions.clear()
     this.observedConversationStarts.clear()
     await Promise.allSettled([...this.states].map((state) => this.disposeState(state)))