dsh-plugin-prompt-tool 0.6.2 → 0.7.1

package/engine/compositions/library/tool-bootstrap.yml

@@ -1,5 +1,5 @@
 # module: tool-bootstrap
-# source: preset/engine/compositions/source/local/tool-bootstrap.yml (本地附加,非官方模块)
+# source: engine/compositions/source/local/tool-bootstrap.yml (本地附加,非官方模块)
 
 - id: tool-bootstrap
   name: ./engine/tool-bootstrap.mjs
@@ -7,8 +7,6 @@
     bootstrapTools: [bash, str_replace_editor]
     promoteOn: either
     includeSubagents: false
-    usePtcMode: __usePtcMode__
-    __bootstrapMaxTokens__
     # Post-compaction core work set: the model is mid-task and needs to keep
     # working, but faces a small catalog instead of the full Standard set.
     compactionTools: [read, write, edit, glob, grep, todo_write, ask_user_question]

package/engine/compositions/library/tool-config-engine.yml

@@ -0,0 +1,9 @@
+# module: tool-config-engine
+# source: 本地新增（自定义工具引擎：preset.yml customTools 段 → 渲染 custom-tools/ → 运行时注册）
+# 工具定义在预设目录 custom-tools/*.yml；执行器 shell/http/delegate/fs/ask-user。
+# requireApproval 数组可列出需 approval 门的执行器（默认空 = 不要求）。
+
+- id: tool-config-engine
+  name: ./engine/tool-config-engine.mjs
+  config:
+    configsDir: ../custom-tools

package/engine/compositions/library/tool-filter.yml

@@ -1,12 +1,8 @@
 # module: tool-filter
-# source: 本地附加（本项目主会话工具过滤；非官方模块）
+# source: engine/compositions/source/local/tool-filter.yml (本地附加,非官方模块)
 # 主会话常驻工具白名单/黑名单：作用于任意注册工具（含第三方插件工具）。
-# allow 非空 = 白名单（只保留列表内工具）；deny 非空 = 黑名单（移除列表内工具）；
-# 两者都空 = 不过滤（官方默认）。includeSubagents=true 时子代理同样过滤。
+# config 由参数桥按 params.toolFilterAllow/Deny/Subagents 合并；
+# 未声明 = 不过滤（官方默认），见 tool-filter.mjs。
 
 - id: tool-filter
   name: ./engine/tool-filter.mjs
-  config:
-    allow: __mainToolFilterAllow__
-    deny: __mainToolFilterDeny__
-    includeSubagents: __mainToolFilterSubagents__

package/engine/compositions/library/tool-fs-search.yml

@@ -1,5 +1,5 @@
 # module: tool-fs-search
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 - id: tool-fs-search

package/engine/compositions/library/tool-fs.yml

@@ -1,5 +1,5 @@
 # module: tool-fs
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 # ── filesystem ──────────────────────────────────────────────────────────────

package/engine/compositions/library/tool-goal.yml

@@ -1,15 +1,7 @@
 # module: tool-goal
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
-# ── goals ───────────────────────────────────────────────────────────────────
-
-# Only the model-facing tool. The goal SERVICE, its session driver, and the
-# `/goal` command stay on the host plane: the Gateway serves the goal domain as
-# Remote endpoints whose receiver comes from a generated descriptor, so it
-# resolves `goals` on the host and an entry-local realm here would hide it. The
-# registry is keyed by session anyway, so one host instance serves every
-# session. What a preset chooses is whether its agent can call the goal tool.
 - id: tool-goal
   name: '@deepseek-ai/dsh-tool-goal'
 

package/engine/compositions/library/tool-jobs.yml

@@ -1,5 +1,5 @@
 # module: tool-jobs
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 # ── background jobs ────────────────────────────────────────────────────────

package/engine/compositions/library/tool-pwsh.yml

@@ -1,5 +1,5 @@
 # module: tool-pwsh
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 - id: tool-pwsh

package/engine/compositions/library/tool-todo.yml

@@ -1,5 +1,5 @@
 # module: tool-todo
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 - id: tool-todo

package/engine/compositions/library/tool-web.yml

@@ -1,9 +1,9 @@
 # module: tool-web
-# source: E:\Documents\GitHub\deepseek-harness/apps/cli/config/agent-presets/standard/agent.cordis.yml
+# source: D:\AI\GitHub\deepseek-harness/packages/preset/agent-presets/presets/standard/agent.cordis.yml
 # local patches: 0
 
 - id: tool-web
   name: '@deepseek-ai/dsh-tool-web'
   config:
-    fetch: false
+    fetch: true
     searchTimeoutMs: 60000

package/engine/compositions/source/local/code-presentation.yml

@@ -0,0 +1,8 @@
+# module: code-presentation
+# source: engine/compositions/source/local/code-presentation.yml (本地附加,非官方模块)
+# 晋升后 Code Mode (PTC) wire 呈现（从 tool-bootstrap 拆出，与目录窄化解耦）：
+# "只要 PTC 不要 bootstrap" = modules 只挂本行；PTC+bootstrap = 同时挂两行。
+# usePtcMode 默认 false（opt-in）；params.usePtcMode 显式覆盖（参数桥）。
+
+- id: code-presentation
+  name: ./engine/code-presentation.mjs

package/engine/compositions/source/local/context-gate.yml

@@ -3,7 +3,6 @@
   config:
     promoteOn: either
     includeSubagents: false
-    allowKinds: __allowKinds__
 
 # ── bootstrap ───────────────────────────────────────────────────────────────
 

package/engine/compositions/source/local/str-replace-editor.yml

@@ -0,0 +1,10 @@
+# module: str-replace-editor
+# source: engine/compositions/source/local/str-replace-editor.yml (本地附加,非官方模块)
+# 官方 minimal 内置工具（filesystem group 内的 str-replace-editor 行）拆出为独立模块：
+# 复用宿主 sandbox 的 ctx.fs，不挂 fs-local 裸文件系统。
+# maxOutputChars 参数化：params.strReplaceEditorMaxOutputChars（默认官方值 16000）。
+
+- id: str-replace-editor
+  name: '@deepseek-ai/dsh-tool-str-replace-editor'
+  config:
+    maxOutputChars: 16000

package/engine/compositions/source/local/tool-bootstrap.yml

@@ -3,9 +3,7 @@
   config:
     bootstrapTools: [bash, str_replace_editor]
     promoteOn: either
-    includeSubagents: true
-    usePtcMode: __usePtcMode__
-    __bootstrapMaxTokens__
+    includeSubagents: false
     # Post-compaction core work set: the model is mid-task and needs to keep
     # working, but faces a small catalog instead of the full Standard set.
     compactionTools: [read, write, edit, glob, grep, todo_write, ask_user_question]

package/engine/compositions/source/local/tool-config-engine.yml

@@ -0,0 +1,9 @@
+# module: tool-config-engine
+# source: 本地新增（自定义工具引擎：preset.yml customTools 段 → 渲染 custom-tools/ → 运行时注册）
+# 工具定义在预设目录 custom-tools/*.yml；执行器 shell/http/delegate/fs/ask-user。
+# requireApproval 数组可列出需 approval 门的执行器（默认空 = 不要求）。
+
+- id: tool-config-engine
+  name: ./engine/tool-config-engine.mjs
+  config:
+    configsDir: ../custom-tools

package/engine/compositions/source/local/tool-filter.yml

@@ -0,0 +1,8 @@
+# module: tool-filter
+# source: engine/compositions/source/local/tool-filter.yml (本地附加,非官方模块)
+# 主会话常驻工具白名单/黑名单：作用于任意注册工具（含第三方插件工具）。
+# config 由参数桥按 params.toolFilterAllow/Deny/Subagents 合并；
+# 未声明 = 不过滤（官方默认），见 tool-filter.mjs。
+
+- id: tool-filter
+  name: ./engine/tool-filter.mjs

package/engine/cot-drip.mjs

@@ -0,0 +1,137 @@
+/**
+ * cot-drip — 执行期深思维持节拍（上游 dsh-anchored-standard 移植, MIT）。
+ *
+ * 锚定模式在每轮开场有深思考，但长工具循环中深思会衰减（后期步骤退化
+ * 回 "Let me…"）。本模块每 N 次工具结果向对话滴入一条短 user 提醒——
+ * 永不阻塞、永不报错、不碰工具目录：
+ *
+ *   `tools/post-execute` → { kind: 'accept', additionalContexts: [notice] }
+ *
+ * harness 把 additionalContexts 作为 durable user 消息追加在整批工具结果
+ * 之后，落在下一请求的规划节拍位（与 Code Mode 嵌套上下文同形状）。
+ * 模型读到后以一句 "We …" 重申剩余目标并继续。
+ *
+ * 节奏刻意温和：默认 every: 4 次结果、每轮最多 maxPerTurn: 1 条；
+ * every: 0 禁用。计数在 await 前同步自增（并行调用无法竞态越过节奏）；
+ * 轮边界由 durable turn/start + assistant/chunk 双路跟踪（无轮号时降级
+ * session 全局）；子代理默认不滴（brief 即计划）。
+ */
+
+import { booleanOption, validateConfig } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'cot-drip'
+
+/** 默认提醒文本——一条规划节拍，措辞维持 "We" 语态。 */
+export const DRIP_TEXT = [
+  'Progress check: before the next action, restate in one "We …" sentence what remains of the goal and why the next step is the right one.',
+].join(' ')
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['enabled', 'every', 'maxPerTurn', 'includeSubagents', 'text'])
+
+function parseCounter(value, field, fallback, minimum) {
+  if (value === undefined) return fallback
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new TypeError(`${name}: ${field} must be an integer >= ${minimum}; got ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/** 注册执行后深思滴入。 */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  if (source.enabled === false) return
+  const every = parseCounter(source.every, 'every', 4, 0)
+  const maxPerTurn = parseCounter(source.maxPerTurn, 'maxPerTurn', 1, 1)
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  const text = typeof source.text === 'string' && source.text.length > 0 ? source.text : DRIP_TEXT
+
+  /** sessionId -> { results, drips, lastTurn } — 每轮计数。 */
+  const state = new Map()
+
+  const countersOf = (sessionId) => {
+    let entry = state.get(sessionId)
+    if (entry === undefined) {
+      entry = { results: 0, drips: 0, lastTurn: undefined }
+      state.set(sessionId, entry)
+    }
+    return entry
+  }
+
+  let warned = false
+  const warnOnce = (message) => {
+    if (warned) return
+    warned = true
+    try {
+      ctx.logger.warn(message)
+    } catch {
+      // Logger unavailable — the guard exists only to avoid spamming.
+    }
+  }
+
+  // 轮跟踪：turn/start 重置计数；无可用轮号时用 assistant/chunk 的新轮。
+  ctx.on('session/event', (session, event) => {
+    if (session === undefined || session.id === undefined) return
+    if (event.type === 'turn/start') {
+      const turn = event.data?.turn
+      const entry = countersOf(session.id)
+      if (entry.lastTurn !== turn) {
+        entry.lastTurn = typeof turn === 'number' ? turn : entry.lastTurn
+        entry.results = 0
+        entry.drips = 0
+      }
+      return
+    }
+    if (event.type === 'assistant/chunk') {
+      const turn = event.data?.turn
+      if (typeof turn !== 'number') return
+      const entry = countersOf(session.id)
+      if (entry.lastTurn === undefined || turn > entry.lastTurn) {
+        entry.lastTurn = turn
+        entry.results = 0
+        entry.drips = 0
+      }
+    }
+  })
+
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    // await 前同步计数，并行调用不能竞态越过节奏。
+    const session = exec?.agent?.session
+    const eligible = session !== undefined
+      && session.id !== undefined
+      && (includeSubagents || (session.header?.delegationDepth ?? 0) === 0)
+    const entry = eligible ? countersOf(session.id) : undefined
+    if (entry !== undefined) entry.results += 1
+    const due = entry !== undefined
+      && every > 0
+      && entry.results % every === 0
+      && entry.drips < maxPerTurn
+
+    const decision = await next()
+    try {
+      if (!due || decision?.kind !== 'accept') return decision
+      entry.drips += 1
+      const notice = {
+        id: typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+          ? crypto.randomUUID()
+          : `cot-drip-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source: {
+          kind: 'plugin',
+          plugin: name,
+          form: 'notice',
+          summary: 'deliberation maintenance beat',
+        },
+      }
+      return {
+        ...decision,
+        additionalContexts: [...(decision.additionalContexts ?? []), notice],
+      }
+    } catch (error) {
+      warnOnce(`${name}: drip injection failed, keeping the plain result: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  })
+}

package/engine/custom-bash.mjs

@@ -43,6 +43,7 @@
 
 import { access } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
+import { validateConfig } from './shared.mjs'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'custom-bash'
@@ -53,6 +54,9 @@ export const inject = ['subprocess', 'tools']
 const DEFAULT_TIMEOUT_MS = 120000
 const DEFAULT_MAX_OUTPUT_BYTES = 64000
 
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['bashPath', 'timeoutMs', 'maxOutputBytes'])
+
 /**
  * Git Bash candidate paths, in probe order (see the header): the `git`
  * executable's install root first, then the well-known env-derived roots.
@@ -81,6 +85,24 @@ export function bashCandidates(env, gitExe) {
   return [...new Set(candidates)]
 }
 
+/**
+ * Git Bash / MSYS drive path (`/e/foo`) → Windows path (`E:\foo`).
+ * Unix paths like `/usr/bin` or `/tmp` are left unchanged. Exported for tests.
+ * (上游 anchored-standard 移植, issue #72)
+ */
+export function normalizeGitBashWorkdir(workdir, platform = process.platform) {
+  if (typeof workdir !== 'string' || workdir.length === 0) return workdir
+  if (platform !== 'win32') return workdir
+  const match = workdir.match(/^\/([a-zA-Z])(?:\/(.*))?$/)
+  if (!match) return workdir
+  const rest = match[2] ? match[2].replace(/\//g, '\\') : ''
+  return rest ? `${match[1].toUpperCase()}:\\${rest}` : `${match[1].toUpperCase()}:\\`
+}
+
+function isWorkdirEnoent(error) {
+  return /\bENOENT\b/.test(String((error && error.message) || error || ''))
+}
+
 /** Tool parameter schema for the model-facing command. */
 const commandSchema = {
   type: 'object',
@@ -91,7 +113,7 @@ const commandSchema = {
     },
     workdir: {
       type: 'string',
-      description: 'Optional working directory; defaults to the session cwd.',
+      description: 'Optional working directory; defaults to the session cwd. On Windows, Git Bash paths like /e/foo are accepted and converted to E:\\foo.',
     },
   },
   required: ['command'],
@@ -100,9 +122,10 @@ const commandSchema = {
 
 /** Register the model-facing `bash` tool. */
 export function apply(ctx, config) {
-  const explicitBashPath = typeof config?.bashPath === 'string' && config.bashPath.length > 0 ? config.bashPath : undefined
-  const timeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
-  const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  const explicitBashPath = typeof source.bashPath === 'string' && source.bashPath.length > 0 ? source.bashPath : undefined
+  const timeoutMs = Number.isSafeInteger(source.timeoutMs) && source.timeoutMs > 0 ? source.timeoutMs : DEFAULT_TIMEOUT_MS
+  const maxOutputBytes = Number.isSafeInteger(source.maxOutputBytes) && source.maxOutputBytes > 0 ? source.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
 
   // The inferred executable is memoized per plugin instance: candidate probing
   // walks the filesystem, and the answer cannot change within a mount. A
@@ -159,6 +182,7 @@ export function apply(ctx, config) {
       "* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.",
       '* Please avoid commands that may produce a very large amount of output.',
       '* NOTE: runs without OS sandbox confinement on Windows (no landlock); treat output as untrusted.',
+      '* workdir accepts a Windows path or a Git Bash drive path (/e/foo).',
     ].join('\n'),
     parameters: commandSchema,
     output: {
@@ -174,9 +198,24 @@ export function apply(ctx, config) {
     },
     async execute(args, exec) {
       const shell = await resolveShell(exec?.signal)
-      const workdir = typeof args.workdir === 'string' && args.workdir.length > 0
+      const sessionCwd = exec?.agent?.session?.header?.cwd
+      const requested = typeof args.workdir === 'string' && args.workdir.length > 0
         ? args.workdir
-        : exec?.agent?.session?.header?.cwd
+        : sessionCwd
+      const workdir = normalizeGitBashWorkdir(requested)
+
+      // spawnOnce：单次 spawn 封装（ENOENT 回退重试复用同一配置）。
+      const spawnOnce = (cwd) => ctx.subprocess.spawn({
+        argv: [shell, '-c', args.command],
+        ...cwd !== undefined ? { cwd } : {},
+        stdio: {
+          stdin: 'ignore',
+          stdout: { maxBytes: maxOutputBytes },
+          stderr: { maxBytes: maxOutputBytes },
+        },
+        signal: abort.signal,
+        graceMs: 3000,
+      })
 
       // timeoutMs is a foreground deadline. subprocess only reacts to an abort
       // signal, so we own the classification here: a timeout aborts the tree
@@ -191,25 +230,35 @@ export function apply(ctx, config) {
       if (exec?.signal?.aborted) onExecAbort()
       else exec?.signal?.addEventListener('abort', onExecAbort, { once: true })
 
+      let handle
       let outcome
+      let usedFallback = false
       try {
-        const handle = ctx.subprocess.spawn({
-          argv: [shell, '-c', args.command],
-          ...workdir !== undefined ? { cwd: workdir } : {},
-          stdio: {
-            stdin: 'ignore',
-            stdout: { maxBytes: maxOutputBytes },
-            stderr: { maxBytes: maxOutputBytes },
-          },
-          signal: abort.signal,
-          graceMs: 3000,
-        })
         try {
+          handle = spawnOnce(workdir)
           outcome = await handle.done
         } catch (error) {
-          // A spawn-level failure (bad executable, EPERM) surfaces as a throw,
-          // which the runtime turns into an isError result.
-          throw new Error(`bash spawn failed: ${String(error)}`)
+          // workdir 归一化后仍 ENOENT（如 /e/foo 目录不存在）→ 回退会话 cwd 重试
+          // （上游 anchored-standard issue #72）。
+          const fallback = sessionCwd !== undefined ? normalizeGitBashWorkdir(sessionCwd) : undefined
+          if (
+            requested !== undefined
+            && fallback !== undefined
+            && fallback !== workdir
+            && isWorkdirEnoent(error)
+          ) {
+            usedFallback = true
+            try {
+              handle = spawnOnce(fallback)
+              outcome = await handle.done
+            } catch (retryError) {
+              throw new Error(`bash spawn failed: ${String(retryError)}`)
+            }
+          } else {
+            // A spawn-level failure (bad executable, EPERM) surfaces as a throw,
+            // which the runtime turns into an isError result.
+            throw new Error(`bash spawn failed: ${String(error)}`)
+          }
         }
         let stdout = ''
         let stderr = ''
@@ -219,8 +268,11 @@ export function apply(ctx, config) {
         } catch {
           // Collected readers may be unavailable on some backends; tolerate.
         }
+        const note = usedFallback
+          ? `[custom-bash] workdir ${requested} was unusable (ENOENT); fell back to session cwd\n`
+          : ''
         const text = [stdout, stderr].filter((part) => part.length > 0).join('\n')
-        const tail = text.length > 0 ? text : `exit code: ${outcome.exitCode} (no output)`
+        const tail = note + (text.length > 0 ? text : `exit code: ${outcome.exitCode} (no output)`)
         if (timedOut) {
           throw new Error(`bash timed out after ${timeoutMs}ms${tail ? `\n${tail}` : ''}`)
         }

package/engine/deliberation-gate.mjs

@@ -0,0 +1,127 @@
+/**
+ * deliberation-gate — 轨迹深度门（上游 dsh-anchored-standard 移植, MIT）。
+ *
+ * 完整目录保持可见可调（会话观感正常），但首工具调用前深思不足就拒绝
+ * 一次。以 durable `assistant/chunk` 的 text/reasoning delta 累计长度作为
+ * "深思深度"代理（adapter 无 logprobs，观测层只有流式 chunk）。
+ *
+ * 行为：
+ *  - session/event 累计每轮流式长度；tools/pre-execute 时当前轮深度
+ *    < minChars（默认 400）→ { kind:'deny', reason: gateText }（规划式
+ *    提示，措辞明示"非工具失败"），每轮最多 maxGatesPerTurn 次（默认 1）。
+ *  - retry 把强制深思带进历史；无流式文本的轮 = 深度 0，恰好门一次
+ *    （fail-safe 向更多深思）。
+ *  - 冷启动从 durable log 扫描（重启保持深度）；turn map 修剪
+ *    （MAX_TRACKED_TURNS=8）；deny 前无 await（并行调用无法竞态越过预算）。
+ *  - 子代理默认不门控（brief 即计划）；includeSubagents: true 同门控。
+ */
+
+import { booleanOption, validateConfig } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'deliberation-gate'
+
+/** 默认深思下限（每轮首工具调用前，字符数）。 */
+export const DEFAULT_MIN_CHARS = 400
+
+/** 默认门控指令（拒绝回传的规划提示）。 */
+export const GATE_TEXT = [
+  'Deliberation gate: this turn has not shown its reasoning yet.',
+  'Before retrying this tool call, write out your full reasoning in your reply — start with "We", restate the goal, weigh the approaches, and lay out the concrete steps and risks — then issue the tool call again.',
+  'This message is a planning prompt, not a tool failure.',
+].join(' ')
+
+/** 每会话最多保留的轮次深度状态。 */
+const MAX_TRACKED_TURNS = 8
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['enabled', 'minChars', 'maxGatesPerTurn', 'includeSubagents', 'gateText'])
+
+function parseCounter(value, field, fallback, minimum) {
+  if (value === undefined) return fallback
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new TypeError(`${name}: ${field} must be an integer >= ${minimum}; got ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/** 注册轨迹深度门。 */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  if (source.enabled === false) return
+  const minChars = parseCounter(source.minChars, 'minChars', DEFAULT_MIN_CHARS, 0)
+  const maxGatesPerTurn = parseCounter(source.maxGatesPerTurn, 'maxGatesPerTurn', 1, 1)
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  const gateText = typeof source.gateText === 'string' && source.gateText.length > 0 ? source.gateText : GATE_TEXT
+
+  /** sessionId -> { turns: Map<turn, { chars, gates }>, lastTurn } */
+  const state = new Map()
+
+  /** 实时路径：每条流式 chunk 扩展轮条目。 */
+  const observeChunk = (sessionId, turn, textLength) => {
+    let entry = state.get(sessionId)
+    if (entry === undefined) {
+      entry = { turns: new Map(), lastTurn: turn }
+      state.set(sessionId, entry)
+    }
+    let turnEntry = entry.turns.get(turn)
+    if (turnEntry === undefined) {
+      // 修剪旧轮，长会话不累积状态。
+      if (entry.turns.size >= MAX_TRACKED_TURNS) {
+        const oldest = [...entry.turns.keys()].sort((a, b) => a - b).slice(0, entry.turns.size - MAX_TRACKED_TURNS + 1)
+        for (const key of oldest) entry.turns.delete(key)
+      }
+      turnEntry = { chars: 0, gates: 0 }
+      entry.turns.set(turn, turnEntry)
+    }
+    turnEntry.chars += textLength
+    if (turn > entry.lastTurn) entry.lastTurn = turn
+  }
+
+  /** 会话深度状态；首见冷扫 durable log（重启保持已流式深度）。 */
+  const depthOf = (session) => {
+    let entry = state.get(session.id)
+    if (entry === undefined) {
+      entry = { turns: new Map(), lastTurn: -1 }
+      if (Array.isArray(session.events)) {
+        for (const event of session.events) {
+          if (event.type !== 'assistant/chunk') continue
+          const turn = event.data?.turn
+          if (typeof turn !== 'number' || !Number.isFinite(turn)) continue
+          const text = event.data?.chunk?.text
+          observeChunk(session.id, turn, typeof text === 'string' ? text.length : 0)
+        }
+        entry = state.get(session.id) ?? entry
+      }
+      if (entry.turns.size === 0) {
+        // 无任何流式文本：深度视为 0 于哨兵轮，会话恰好门一次后放行。
+        entry.turns.set(entry.lastTurn, { chars: 0, gates: 0 })
+      }
+      state.set(session.id, entry)
+    }
+    return entry
+  }
+
+  // 深度代理：累计 durable assistant/chunk 的流式长度。
+  ctx.on('session/event', (session, event) => {
+    if (event.type !== 'assistant/chunk') return
+    const turn = event.data?.turn
+    if (typeof turn !== 'number' || !Number.isFinite(turn)) return
+    const text = event.data?.chunk?.text
+    observeChunk(session.id, turn, typeof text === 'string' ? text.length : 0)
+  })
+
+  // 门：同步决策，当前轮累计深度 < minChars 时最多 deny maxGatesPerTurn 次。
+  ctx.on('tools/pre-execute', (exec, next) => {
+    const session = exec?.agent?.session
+    if (session === undefined || session.id === undefined) return next()
+    if (!includeSubagents && (session.header?.delegationDepth ?? 0) > 0) return next()
+    const entry = depthOf(session)
+    const turnEntry = entry.turns.get(entry.lastTurn)
+    if (turnEntry === undefined) return next()
+    if (turnEntry.gates >= maxGatesPerTurn) return next()
+    if (turnEntry.chars >= minChars) return next()
+    turnEntry.gates += 1
+    return { kind: 'deny', reason: gateText }
+  })
+}