dsh-ptc-plus 0.5.2 → 0.5.3

package/internal/binding-adoption.js

@@ -0,0 +1,136 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { isPtcMessageSource, PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+
+/**
+ * Session binding adoption: which Global User Binding catalog entries this
+ * session uses.
+ *
+ * The question is answered per session and per entry, and the answer is a
+ * decision of exactly two states: this session uses the entry, or it does not.
+ * An entry the session never named is used, because the global catalog already
+ * answered the supply question. That default is the absence of a decision, not
+ * a third state: "use" and "never mentioned" lead to the same environment, so
+ * they are one state rather than two.
+ *
+ * Adoption can only take an entry away from this session. It cannot supply one,
+ * enable one, or name a source: an entry the global configuration disabled is
+ * absent from the catalog, so "adoption revives a deleted entry" has no
+ * encoding here and needs no rule forbidding it. Naming an entry the catalog
+ * does not offer is rejected at the surface that states the decision, because
+ * the record would otherwise claim authority over supply.
+ *
+ * The neighbour this must not be confused with is the capability pane's
+ * `automatic`, which means "the host derives this value". A binding has no host
+ * derivation to defer to, so borrowing that word would misdescribe both.
+ *
+ * The decision is recorded as one PTC message in the session log, so it is
+ * reconstructed by replaying that log after a restart instead of being kept in
+ * process memory.
+ */
+export const BINDING_ADOPTION_FORM = 'binding-adoption'
+export const BINDING_ADOPTION_SCHEMA = 'ptc-binding-adoption/v1'
+
+const MAX_DECLINED = 64
+const ENTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+const PREFIX = 'PTC Plus session binding adoption. This session uses every entry the global catalog supplies except the declined ones. Adoption can only withdraw an entry from this session: it cannot supply, enable or revive one, and the global configuration decides which entries exist at all. Declined entry IDs:'
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function sortIds(ids) {
+  return [...ids].sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+}
+
+export function normalizeBindingAdoption(value) {
+  if (!isRecord(value) || Reflect.ownKeys(value).length !== 2
+    || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'declined')) {
+    throw new TypeError('invalid binding adoption')
+  }
+  if (value.schema !== BINDING_ADOPTION_SCHEMA) throw new TypeError('invalid binding adoption schema')
+  if (!Array.isArray(value.declined) || value.declined.length > MAX_DECLINED) {
+    throw new TypeError('invalid binding adoption declined entries')
+  }
+  const declined = []
+  for (const id of value.declined) {
+    if (typeof id !== 'string' || !ENTRY_ID.test(id)) throw new TypeError('invalid binding adoption entry id')
+    if (declined.includes(id)) throw new TypeError('duplicate binding adoption entry id')
+    declined.push(id)
+  }
+  return Object.freeze({ schema: BINDING_ADOPTION_SCHEMA, declined: Object.freeze(sortIds(declined)) })
+}
+
+/** The exact model-visible wording one adoption record carries. */
+export function bindingAdoptionText(adoption) {
+  return `${PREFIX}\n${JSON.stringify(normalizeBindingAdoption(adoption).declined)}`
+}
+
+export function bindingAdoptionMessage(adoption) {
+  const text = bindingAdoptionText(adoption)
+  const message = createUserMessage({
+    source: { kind: PTC_MESSAGE_SOURCE_KIND, form: BINDING_ADOPTION_FORM },
+    content: [{ type: 'text', text }],
+  })
+  if (readBindingAdoption(message) === undefined) throw new TypeError('invalid binding adoption message')
+  return message
+}
+
+/** Read one adoption record back from a message, message projection or message fact. */
+export function readBindingAdoption(value) {
+  const source = value?.source
+  if (!isPtcMessageSource(source) || source.form !== BINDING_ADOPTION_FORM) return undefined
+  if (!Array.isArray(value.content) || value.content.length !== 1 || value.content[0]?.type !== 'text') return undefined
+  const text = value.content[0].text
+  if (typeof text !== 'string' || !text.startsWith(`${PREFIX}\n`)) return undefined
+  try {
+    const declined = JSON.parse(text.slice(PREFIX.length + 1))
+    const adoption = normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined })
+    return bindingAdoptionText(adoption) === text ? adoption : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The newest adoption this session recorded, or `undefined` while it recorded
+ * none. The newest record replaces earlier ones, because stating a decision
+ * again is how a session changes its mind.
+ */
+export function latestBindingAdoption(records) {
+  if (!Array.isArray(records)) return undefined
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    const record = records[index]
+    if (record?.form !== BINDING_ADOPTION_FORM) continue
+    try {
+      return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: record.declined })
+    } catch {
+      // A record that cannot be read is not evidence for an earlier record
+      // either: the newest statement is the current one, and it is unreadable.
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * The declined entry IDs of one adoption, as a set the environment uses.
+ * An adoption that was never stated declines nothing.
+ */
+export function declinedBindingEntries(adoption) {
+  return new Set(adoption === undefined ? [] : normalizeBindingAdoption(adoption).declined)
+}
+
+/** State one entry as used (`adopt` true) or not used, leaving the rest alone. */
+export function withBindingAdoption(adoption, entryId, adopt) {
+  if (typeof entryId !== 'string' || !ENTRY_ID.test(entryId)) throw new TypeError('invalid binding adoption entry id')
+  if (typeof adopt !== 'boolean') throw new TypeError('binding adoption decision must be a boolean')
+  const declined = declinedBindingEntries(adoption)
+  if (adopt) declined.delete(entryId)
+  else declined.add(entryId)
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [...declined] })
+}
+
+/** Drop every declined entry: this session again uses the whole catalog. */
+export function clearedBindingAdoption() {
+  return normalizeBindingAdoption({ schema: BINDING_ADOPTION_SCHEMA, declined: [] })
+}

package/internal/capability-command-receipt.js

@@ -1,4 +1,6 @@
 /** Structured command outcome for locale-owned Client receipts; text remains a CLI fallback. */
+import { capabilityProofText, normalizeCapabilityProof } from './capability-delivery-proof.js'
+
 const PREFIX = '\n\nPTC Plus capability refresh receipt:\n'
 const FALLBACKS = Object.freeze({
   'saved-only': 'Global choice saved, but the session update failed; inspect and retry session',
@@ -11,13 +13,25 @@ const FALLBACKS = Object.freeze({
 })
 const STATES = new Set(['recorded', 'pending', 'unavailable', 'usage', 'saved-only', 'paused', 'off'])
 
-export function capabilityCommandReceipt(state, sessionId, error, proposal) {
+export function capabilityCommandReceipt(state, sessionId, error, proposal, proof) {
   if (!STATES.has(state) || typeof sessionId !== 'string' || !sessionId) throw new TypeError('invalid capability command receipt')
   if (error !== undefined && (state !== 'saved-only' || typeof error !== 'string' || !error)) throw new TypeError('invalid capability command error')
   if (proposal !== undefined && (state !== 'pending' || !proposal || typeof proposal.commandId !== 'string'
     || typeof proposal.rawInput !== 'string' || !proposal.message)) throw new TypeError('invalid capability proposal receipt')
-  return `${FALLBACKS[state]} ${sessionId}.${error ? ` ${error}` : ''}` + PREFIX
-    + JSON.stringify({ schema: 'ptc-capability-command/v1', state, sessionId, ...(error === undefined ? {} : { error }), ...(proposal === undefined ? {} : { proposal }) })
+  // A command that names one capability reports that capability's three layers
+  // beside the session outcome, so "saved" cannot be read as "delivered" or
+  // "usable". The schema stays v1 because the field is additive: receipts
+  // recorded before it existed still reproduce their own text.
+  const layers = proof === undefined ? undefined : normalizeCapabilityProof(proof)
+  return `${FALLBACKS[state]} ${sessionId}.${error ? ` ${error}` : ''}`
+    + (layers === undefined ? '' : ` ${capabilityProofText(layers)}`)
+    + PREFIX
+    + JSON.stringify({
+      schema: 'ptc-capability-command/v1', state, sessionId,
+      ...(error === undefined ? {} : { error }),
+      ...(proposal === undefined ? {} : { proposal }),
+      ...(layers === undefined ? {} : { proof: layers }),
+    })
 }
 
 export function readCapabilityCommandReceipt(text) {
@@ -26,6 +40,6 @@ export function readCapabilityCommandReceipt(text) {
     const receipt = JSON.parse(text.slice(text.indexOf(PREFIX) + PREFIX.length))
     return receipt?.schema === 'ptc-capability-command/v1' && STATES.has(receipt.state)
       && typeof receipt.sessionId === 'string' && receipt.sessionId
-      && capabilityCommandReceipt(receipt.state, receipt.sessionId, receipt.error, receipt.proposal) === text ? receipt : undefined
+      && capabilityCommandReceipt(receipt.state, receipt.sessionId, receipt.error, receipt.proposal, receipt.proof) === text ? receipt : undefined
   } catch { return undefined }
 }

package/internal/capability-delivery-proof.js

@@ -0,0 +1,70 @@
+/**
+ * One capability, three separate facts.
+ *
+ * Saving a global choice changes supply: the configuration now records a
+ * decision. It does not prove the model ever received that decision, and it does
+ * not prove a cell can reach the capability. Those are different questions with
+ * different owners:
+ *
+ * - **saved**: the global configuration records a choice for this capability.
+ * - **delivered**: the model-visible capability catalog published it at an
+ *   accepted step, rather than waiting for the next one or never listing it.
+ * - **usable**: a completed execution in this session actually reached it.
+ *
+ * Usability is only ever proved by an execution result. Nothing else in the
+ * product can claim it: a saved switch, a published catalog entry and an
+ * installed tool schema are all statements about intent, not about a value a
+ * cell obtained. Reporting "saved, delivered, usability unproven" is therefore
+ * the honest answer to "did that save take effect", and it is what a layer that
+ * cannot prove more must say instead of claiming effect.
+ */
+export const CAPABILITY_PROOF_SCHEMA = 'ptc-capability-proof/v1'
+export const CAPABILITY_DELIVERY_STATES = new Set(['delivered', 'pending', 'absent'])
+export const CAPABILITY_USABILITY_STATES = new Set(['proven', 'unproven'])
+
+const CAPABILITY_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function normalizeCapabilityProof(value) {
+  if (!isRecord(value) || Reflect.ownKeys(value).length !== 5
+    || !Object.hasOwn(value, 'schema') || !Object.hasOwn(value, 'id') || !Object.hasOwn(value, 'saved')
+    || !Object.hasOwn(value, 'delivery') || !Object.hasOwn(value, 'usability')) {
+    throw new TypeError('invalid capability proof')
+  }
+  if (value.schema !== CAPABILITY_PROOF_SCHEMA) throw new TypeError('invalid capability proof schema')
+  if (typeof value.id !== 'string' || !CAPABILITY_ID.test(value.id)) throw new TypeError('invalid capability proof id')
+  if (typeof value.saved !== 'boolean') throw new TypeError('invalid capability proof saved fact')
+  if (!CAPABILITY_DELIVERY_STATES.has(value.delivery)) throw new TypeError('invalid capability proof delivery state')
+  if (!CAPABILITY_USABILITY_STATES.has(value.usability)) throw new TypeError('invalid capability proof usability state')
+  return Object.freeze({
+    schema: CAPABILITY_PROOF_SCHEMA,
+    id: value.id,
+    saved: value.saved,
+    delivery: value.delivery,
+    usability: value.usability,
+  })
+}
+
+/**
+ * The model-visible sentence for one proof. Each layer states its own result, so
+ * a reader can tell which layer failed instead of reading one blanket "applied".
+ */
+export function capabilityProofText(proof) {
+  const normalized = normalizeCapabilityProof(proof)
+  const id = normalized.id
+  const saved = normalized.saved
+    ? `Saved: yes. The global configuration records a choice for ${id}.`
+    : `Saved: no. The global configuration records no choice for ${id}, so this save did not happen; the session choice below is the only change.`
+  const delivery = {
+    delivered: `Delivered: yes. The model-visible capability catalog published ${id} at an accepted step.`,
+    pending: `Delivered: not yet. The saved configuration reaches the model-visible catalog at the next accepted step, so ${id} is not in it now.`,
+    absent: `Delivered: no. The published capability catalog does not list ${id}, so the model never received it.`,
+  }[normalized.delivery]
+  const usability = normalized.usability === 'proven'
+    ? `Usable: proven. A completed execution in this session reached ${id}.`
+    : `Usable: unproven. No completed execution in this session reached ${id}; only such a result would prove it, and a saved or published entry does not.`
+  return `${saved} ${delivery} ${usability}`
+}

package/internal/capability-environment.js

@@ -1,7 +1,7 @@
 import { capabilityRule, capabilityPolicyForConfig, changeCapabilityRule, effectiveCapabilitySettings, CAPABILITY_DISCLOSURES, CAPABILITY_INVENTORY_CATEGORIES } from './capability-policy.js'
 /** One session-owned capability view for presentation, discovery and preparation. */
 import { createHash } from 'node:crypto'
-import { jsonSchemaToTs, renderToolsSdk, ToolNotFoundError } from '@deepseek-ai/dsh-tools'
+import { jsonSchemaToTs, renderToolsSdk, ToolNotFoundError } from './host-tool-sdk.js'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { isModelInvocable, isUserInvocable } from '@deepseek-ai/dsh-skill'
 import { createScope } from '@deepseek-ai/dsh-scope'
@@ -9,6 +9,7 @@ import { Context } from '@deepseek-ai/cordis'
 import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
 import { readSessionLog } from './session-events.js'
 import { readCapabilityCommandReceipt } from './capability-command-receipt.js'
+import { normalizeCapabilityProof } from './capability-delivery-proof.js'
 import { createCapabilityPlan } from './capability-plan.js'
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
 import { deepFreeze } from './record-utils.js'
@@ -1306,6 +1307,42 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
           member === agent ? status : member.status))
       }
     },
+    /**
+     * The saved, delivered and usable facts of one capability. A caller that
+     * only has "the save succeeded" must not report more than this returns.
+     */
+    describeCapabilityProof(agent, id) {
+      if (typeof id !== 'string' || id.length === 0) throw new TypeError('ptc-plus: capability proof requires a capability id')
+      const state = stateFor(agent)
+      const sourceSettings = state?.snapshot.sourceSettings ?? state?.snapshot.settings
+        ?? capabilityConfiguration(currentConfig)
+      // A global choice is recorded either as a legacy override or as a rule in the
+      // policy this owner writes for `/capabilities set global`, so both spellings
+      // prove the same save.
+      const capability = state?.snapshot.capabilities.find(item => item.id === id)
+      const recorded = capability === undefined || sourceSettings.policy === undefined
+        ? undefined : capabilityRule(sourceSettings.policy, capability)
+      const saved = Object.hasOwn(sourceSettings.manual?.overrides ?? {}, id)
+        || recorded?.availabilitySource === `item:${id}`
+        || recorded?.disclosureSource === `item:${id}`
+      // Delivery is a statement about the model-visible catalog. A plan that holds an
+      // entry whose choice is closed describes an entry the catalog does not list, so
+      // holding it proves nothing was delivered.
+      const entry = state?.snapshot.plan.entries.find(item => item.id === id)
+      const listed = entry !== undefined && entry.selection !== 'closed'
+      const delivery = !listed ? 'absent'
+        : state.message === undefined || planCommitted(agent, state.message) ? 'delivered' : 'pending'
+      return normalizeCapabilityProof({
+        schema: 'ptc-capability-proof/v1',
+        id,
+        saved,
+        delivery,
+        // Only a completed execution in this session proves usability; the
+        // worker's installed schemas and the published catalog prove nothing
+        // about what a cell actually obtained.
+        usability: state?.used?.has(id) === true ? 'proven' : 'unproven',
+      })
+    },
     describe(agent) {
       const state = stateFor(agent)
       return state === undefined ? { configured: capabilityConfiguration(currentConfig), effective: null }

package/internal/config-spec.js

@@ -130,10 +130,10 @@ export const CONFIG_FIELDS = Object.freeze([
     type: 'enum',
     options: Object.freeze(['stateful', 'protected']),
     default: 'stateful',
-    label: '允许重声明和覆盖',
-    labelEn: 'Allow redeclarations and overrides',
-    description: '同一作用域的声明和赋值可更新变量、函数、类及导入。关闭后检测跨 cell 重声明，并保护新建的 const 和 import；静态 import/export 始终可用。',
-    descriptionEn: 'Declarations and assignments update variables, functions, classes and imports in the same scope. Disabling detects cross-cell redeclarations and protects newly created const and import bindings; static import/export remains available.',
+    label: '跨 cell 声明策略',
+    labelEn: 'Cross-cell declaration policy',
+    description: '同一作用域的声明和赋值可更新变量、函数、类及导入。选“启用名称保护”时改为检测跨 cell 重声明，并保护新建的 const 和 import；静态 import/export 始终可用。',
+    descriptionEn: 'Declarations and assignments update variables, functions, classes and imports in the same scope. With “Protect names” selected, cross-cell redeclarations are detected instead and newly created const and import bindings are protected; static import/export remains available.',
   },
   {
     key: 'canonicalizeToolCalls',
@@ -287,6 +287,15 @@ export const CONFIG_FIELDS = Object.freeze([
     description: '检测到官方持久 REPL 模式时由官方运行时接管 PTC 会话执行；PTC Plus 让出 run_code 及其进程内会话状态语义，关闭时始终由 PTC Plus 接管。',
     descriptionEn: 'Lets the official runtime own PTC session execution when the official persistent REPL mode is active; PTC Plus then leaves run_code and its in-process session-state semantics to DSH. Disabled keeps PTC Plus in charge.',
   },
+  {
+    key: 'editRewritesHistory',
+    type: 'boolean',
+    default: false,
+    label: '编辑时替换原单元格',
+    labelEn: 'Replace the edited cell in place',
+    description: '默认关闭，一般也不需要打开：编辑只会追加一次执行，原单元格和它创建的绑定都还在。开启后，编辑会替换原单元格，之后的重建按新版本进行，新版本里不再声明的名字会被点名"已被替换"，而不是悄悄消失。只有当你希望环境表现得"这一格一直就是新版本"时才需要打开。',
+    descriptionEn: 'Off by default, and usually unnecessary: an edit appends one more execution, leaving the original cell and the bindings it created in place. When on, the edit replaces the original cell, later rebuilds follow the new version, and a name the new version no longer declares is reported as replaced rather than silently disappearing. Turn it on only when the environment should behave as if that cell had always been the new version.',
+  },
   {
     key: 'tipsEnabled',
     type: 'boolean',
@@ -483,7 +492,7 @@ export const CONFIG_GROUPS = Object.freeze([
     key: 'recovery',
     label: '状态与恢复',
     labelEn: 'State and recovery',
-    fields: Object.freeze(['durableReplay', 'unmeasuredCellLimit', 'officialReplPriority', 'tipsEnabled', 'tipCooldownMessages', 'tipEscalationFailures']),
+    fields: Object.freeze(['durableReplay', 'editRewritesHistory', 'unmeasuredCellLimit', 'officialReplPriority', 'tipsEnabled', 'tipCooldownMessages', 'tipEscalationFailures']),
   },
   {
     key: 'extensions',

package/internal/cordis-tools-owner.js

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module'
 import { dirname, isAbsolute, join } from 'node:path'
 import { isDeepStrictEqual } from 'node:util'
 import { RUN_CODE } from './runtime-bridge-owner.js'
+import { sessionExecutionAvailable } from './host-tool-sdk.js'
 
 const CORDIS_PRESET_ID = 'cordis'
 const CORDIS_SKILL_NAME = 'cordis-plugin-development'
@@ -111,7 +112,7 @@ function requireFiberServices(agent, fiber, owner) {
 function absentCompanionSurfaces(agent) {
   if (typeof agent?.ctx?.get !== 'function') return undefined
   const missing = []
-  if (agent.ctx.tools?.get?.(RUN_CODE, agent) === undefined) missing.push(`the ${RUN_CODE} tool`)
+  if (!sessionExecutionAvailable(agent.ctx.tools, agent, RUN_CODE)) missing.push(`the ${RUN_CODE} tool`)
   if (agent.ctx.tools?.get?.(COMPANION_SKILL_TOOL, agent) === undefined) {
     missing.push(`the ${COMPANION_SKILL_TOOL} tool`)
   }

package/internal/direct-surface-owner.js

@@ -27,7 +27,7 @@ const INVALID_TOOL_JSON_FAILURE = Object.freeze({
 const MALFORMED_TOOL_REJECTION_ID = 'dsh-ptc-plus-malformed-tool-json'
 const MALFORMED_TOOL_REJECTION_ARGUMENTS = '{"dsh_ptc_plus_malformed_tool_json":'
 
-function adaptRunCodeSchema(tool, promptText) {
+export function adaptRunCodeSchema(tool, promptText) {
   const parameters = tool.parameters
   const properties = isRecord(parameters) ? parameters.properties : undefined
   const code = isRecord(properties) ? properties.code : undefined
@@ -109,9 +109,14 @@ export function createCordisRecoveryPolicy(initiallyEnabled) {
   })
 }
 
-function presentationState(assembly) {
-  const tools = Array.isArray(assembly?.tools) ? assembly.tools : []
-  if (!tools.some(tool => tool?.name === RUN_CODE)) {
+function presentationState(assembly, declaresRunCode, agent) {
+  const tools = Array.isArray(assembly?.tools) ? assembly.tools : undefined
+  // A host that declares tools after the presentation waterfall carries no
+  // array here; the transport it publishes is then the same fact.
+  const present = tools === undefined
+    ? declaresRunCode?.(agent) === true
+    : tools.some(tool => tool?.name === RUN_CODE)
+  if (!present) {
     return { presentation: 'native', ownerProven: false, collapseSectionName: undefined }
   }
   const collapse = PTC_COLLAPSE_SECTION_NAMES
@@ -453,6 +458,7 @@ export function createDirectSurfaceOwner({
   canonicalizeToolCalls,
   sessionId,
   toolSchemasForAgent,
+  declaresRunCode,
   userBindingsForAgent = async () => undefined,
   setAgentPresentation = async () => {},
   sessionLogView,
@@ -578,7 +584,7 @@ export function createDirectSurfaceOwner({
       const requestOwner = id === undefined ? undefined : sessionOwner(id)
       const isCurrent = () => !disposed && (requestOwner === undefined
         || (requestOwner.active && sessions.get(id) === requestOwner))
-      const initialState = presentationState(initialAssembly)
+      const initialState = presentationState(initialAssembly, declaresRunCode, agent)
       let composition = compositions.get(agent)
       if (composition === undefined && id !== undefined
         && (initialState.ownerProven || initialState.presentation === 'ptc')) {
@@ -590,11 +596,17 @@ export function createDirectSurfaceOwner({
 
       const assembly = await next()
       if (!isCurrent()) return assembly
+      // A host may declare the model-facing tool array after this waterfall, in
+      // which case the assembly carries none. The declaration surface is then
+      // host-owned: the plugin still owns presentation, sections, contexts and
+      // request policy, but it must not claim to have replaced declarations the
+      // host has not asked it for. A present but non-array declaration is still
+      // a malformed assembly.
       const tools = assembly.tools
-      if (!Array.isArray(tools)) {
+      if (tools !== undefined && !Array.isArray(tools)) {
         throw new Error('ptc-plus: incompatible prompt assembly; expected a tools array')
       }
-      const completedState = presentationState(assembly)
+      const completedState = presentationState(assembly, declaresRunCode, agent)
       if (composition === undefined && id !== undefined) {
         const state = initialState.ownerProven ? initialState : completedState
         composition = captureComposition(agent, id, state.presentation)
@@ -607,7 +619,7 @@ export function createDirectSurfaceOwner({
       const requestSignal = context?.signal !== null && typeof context?.signal === 'object'
         ? context.signal
         : undefined
-      if (!tools.some(tool => tool?.name === RUN_CODE)) {
+      if (completedState.presentation === 'native') {
         if (presentation !== 'native') {
           throw new Error(`ptc-plus: ${presentation} agent composition assembled without run_code`)
         }
@@ -628,12 +640,14 @@ export function createDirectSurfaceOwner({
       if (sessionPtc) await capabilityEnvironment?.prepare(agent, assembly.sections)
       const userBindings = sessionPtc ? await userBindingsForAgent(agent) : undefined
       if (!isCurrent()) return assembly
-      const runCode = tools.find(tool => tool?.name === RUN_CODE)
+      const runCode = tools?.find(tool => tool?.name === RUN_CODE)
       const promptText = currentPromptText
-      let directTools = sessionPtc ? capabilityEnvironment?.visibleSchemas(agent, tools) ?? tools : tools
+      const hostDeclaresTools = tools !== undefined
+      let directTools = tools === undefined ? undefined
+        : sessionPtc ? capabilityEnvironment?.visibleSchemas(agent, tools) ?? tools : tools
       if (sessionPtcProjection) {
         editTransport.ensureInstalled(agent)
-        directTools = [adaptRunCodeSchema(runCode, promptText)]
+        if (hostDeclaresTools) directTools = [adaptRunCodeSchema(runCode, promptText)]
       }
       const runtimeContexts = sessionPtc
         ? sessionRuntimeContexts(agent, tipConfig, {
@@ -685,11 +699,11 @@ export function createDirectSurfaceOwner({
 
       return {
         ...assembly,
-        tools: sessionPtcProjection
+        ...(directTools === undefined ? {} : { tools: sessionPtcProjection
           ? directTools
           : directTools.map(tool => tool?.name === RUN_CODE
             ? adaptRunCodeSchema(tool, promptText)
-            : tool),
+            : tool) }),
         sections,
       }
     },

package/internal/edit-transport-owner.js

@@ -12,7 +12,7 @@ import {
   normalizeRecoveryBoundaries,
   normalizeRewrites,
   validatedRewrites,
-  withDiagnosticWording,
+  withSettlementProof,
 } from './session-journal.js'
 import {
   EXPECTED_TARGET_CALL_SEQ,
@@ -29,6 +29,7 @@ import { sessionEvents } from './session-events.js'
 import { deepEqualJson, snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import { RUN_CODE } from './runtime-bridge-owner.js'
+import { dispatchToolCall } from './host-tool-sdk.js'
 import { CAPABILITY_EVIDENCE_KEY } from './capability-environment.js'
 import { isRecord } from './record-utils.js'
 import {
@@ -199,9 +200,9 @@ export function createEditTransportOwner(ctx, {
           derived.draftCapability,
           presentationGeneration,
         )
-    // The derived settlement records its own diagnostic wording, so a replay reads
-    // the same pairing the root path publishes.
-    const withWording = withDiagnosticWording(withDraft, withDraft[JOURNAL_KEY])
+    // The derived settlement proves its own facts, so a replay reads the same
+    // settlement the root path publishes.
+    const withWording = withSettlementProof(withDraft, withDraft[JOURNAL_KEY])
     return derived.replMemory === undefined
       ? withWording
       : withReplMemorySnapshot(withWording, derived.replMemory, presentationGeneration)
@@ -310,7 +311,7 @@ export function createEditTransportOwner(ctx, {
         const executionStart = agent.session.append('tool/ptc-dispatch-start', data)
         const derivedExec = { callId: data.subCallId, rootCallId: data.rootCallId,
           parent: rootExec.token, name: RUN_CODE, arguments: argumentsValue, agent, signal: rootSignal }
-        const dispatch = () => ctx.tools.execute(derivedExec)
+        const dispatch = () => dispatchToolCall(ctx.tools, derivedExec)
         const tentative = await executeTentative(executionStart.seq, start.rootCallSeq,
           dispatch, executionLog, derivedExec)
         const inner = tentative.result

package/internal/execution-provider-owner.js

@@ -1,4 +1,5 @@
 import { createExecutionSeam, EXECUTION_SEAM_SERVICE, LEGACY_EXECUTION_SEAM_SERVICE } from './execution-seam-compat.js'
+import { providerRetainsState } from './official-repl-priority.js'
 
 export const name = 'ptc-plus-execution-provider'
 export const inject = ['loader']
@@ -70,6 +71,11 @@ export function apply(ctx, config = {}) {
       get language() { return readOriginal().language },
       get isolation() { return readOriginal().isolation },
       get programFormat() { return readOriginal().programFormat ?? 'function-body' },
+      // This composition isolates state owners and forwards every run to the
+      // original provider, so the original's retention declaration is the
+      // truthful answer. A host plugin that reads it must not see a stateful
+      // environment reported as stateless.
+      get retainsState() { return providerRetainsState(readOriginal()) },
       get executionInstructions() { return readOriginal().executionInstructions },
       get sandboxMode() { return readOriginal().sandboxMode },
       get timeout() { return readOriginal().timeout },

package/internal/execution-seam-compat.js

@@ -1,4 +1,6 @@
 /** Resolved-spec Cordis execution contract. */
+import { providerRetainsState } from './official-repl-priority.js'
+
 export const EXECUTION_SEAM_SERVICE = 'ptcRuntime'
 
 /** Request-only Cordis execution contract. */
@@ -63,7 +65,24 @@ export function createExecutionSeam(service, serviceName) {
     // Source evaluation form belongs to the provider that actually receives
     // the program. Program-format consumers delegate to the original provider,
     // so this descriptor always follows the original generation.
+    //
+    // Retention is different: while an installed adapter runs the program this
+    // provider keeps a per-session environment, so the answer describes what
+    // this provider does, not what the original would do. The ownership decision
+    // asks the original through `seam.originalRetainsState` instead.
     get programFormat() { requireCompatible(); return service.programFormat ?? 'function-body' },
+    // Retention belongs to the provider that actually receives the program, so
+    // this descriptor follows the original generation exactly like the source
+    // form. A host plugin that reads it must not see a stateful environment
+    // reported as stateless.
+    get retainsState() {
+      requireCompatible()
+      // While the installed adapter runs the program, this provider retains a
+      // per-session environment, whatever the original would do. Reporting the
+      // original's answer here would describe a stateful environment as
+      // stateless to every host plugin that asks.
+      return installed === undefined ? providerRetainsState(service) : true
+    },
     get executionInstructions() { requireCompatible(); return installed === undefined ? service.executionInstructions ?? '' : '' },
     get sandboxMode() { requireCompatible(); return installed === undefined ? service.sandboxMode : undefined },
     get timeout() { requireCompatible(); return installed === undefined ? service.timeout : undefined },
@@ -93,6 +112,12 @@ export function createExecutionSeam(service, serviceName) {
   })
   const seam = Object.freeze({
     serviceName,
+    /**
+     * Whether the original provider retains state per owner. Execution ownership
+     * is decided against the original — the provider that would receive the
+     * program if this attachment stood down — not against the composition.
+     */
+    get originalRetainsState() { requireAvailable(); return providerRetainsState(service) },
     get language() { requireAvailable(); return service.language },
     provider,
     get active() { return installed !== undefined && service.language === installed.language },