aura-basetools-dsh 0.7.0 → 0.13.0

package/aura-read/index.js

@@ -29,7 +29,7 @@ import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 // 读取逻辑本身框架无关，住在 locator-lab；本文件是它的 DSH 适配器。
 import { readWith, readManyWith, MODES, BYTE_ORDER_MARK_BYTES, startsWithByteOrderMark } from 'aura-basetools/locator-lab/read-core.mjs'
-import { LINE_ADDRESS_HINT, asLinePair, assertKnownArgs, assertReadTargets, assertTargetShape, gaveLineAddress, inferReadMode, lineRangeOf } from 'aura-basetools/locator-lab/args.mjs'
+import { MT_READ_ELEMENT_KEYS, asLinePair, assertKnownArgs, assertReadTargets, assertTargetShape, inferReadMode, lineRangeOf, normalizeReadRequest } from 'aura-basetools/locator-lab/args.mjs'
 // 仓库级地图（T26）：引擎驱动遍历，本文件只把 ctx.fs 的两个原始能力接上去。
 import { collectRepoMap } from 'aura-basetools/locator-lab/repo-map.mjs'
 
@@ -80,6 +80,7 @@ export const Config = z.object({})
  */
 export const PASSTHROUGH_FIELDS = [
   'symbols',
+  'metrics',
   'version',
   'omitted',
   'next',
@@ -152,6 +153,10 @@ export const READ_ARG_KEYS = [
   'context',
   'since',
   'kind',
+  'max_chars',
+  'budget',
+  'offset',
+  'limit',
   // fs-contract-v2 §2.1：多目标形状。它与 `file_path` **互斥**（判据只有一份：`assertReadTargets`）。
   'targets',
 ]
@@ -407,7 +412,7 @@ function batchEntryOf(entry) {
  *     返回对象是**必须**的，不再是“可选美化”：句柄的身份标签按 `ledgerIdentityKey(filePath, identityKey)`
  *     算，而单目标那条路递的是 `ctx.fs.resolve()` 的 `targetKey`（C61）。多目标若只把路径串当身份，
  *     同一文件同一区间在两条路上会得到**两个不同的句柄**（实测 `h4745015d4840:…` vs `he6dd015d4840:…`），
- *     于是“一次读一批、再一次改一批”这条正路会在 `aura_edit` 上以 `PATCH_HANDLE_IDENTITY_MISMATCH` 断掉。
+ *     于是“一次读一批、再一次改一批”这条正路会在 `aura_basetools_edit` 上以 `PATCH_HANDLE_IDENTITY_MISMATCH` 断掉。
  *     `readManyTarget` 现在把 `displayPath` 当显示路径、`targetKey` 当身份键（**不新造第三份口径**：
  *     `ledgerIdentityKey` / `IDENTITY_KEYS` 就是既有那一份）。
  *   · 同一路径不得解析三次（resolve 在真实后端上是 realpath）⇒ 按路径**记忆化一个 Promise**，
@@ -476,7 +481,7 @@ async function readTargetsBatch(ctx, exec, targets) {
 }
 
 /**
- * 注册 `aura_read` 工具，以及配套的提示段。
+ * 注册 `aura_basetools_read` 工具，以及配套的提示段。
  *
  * ## 为什么必须同时注册提示段
  *
@@ -504,14 +509,14 @@ export function apply(ctx) {
     name: 'tool:aura-read',
     order: 1310,
     text: ({ scope }) =>
-      ctx.tools.get('aura_read', scope) === undefined
+      ctx.tools.get('aura_basetools_read', scope) === undefined
         ? ''
         : [
             // 措辞与内置指导**同形**（命令式）。理由见 aura-edit 里同一处的注释：
             // 建议式的措辞在实测中只在部分会话里生效——它是在跟先验拔河。
             // 兜底措辞分两处写：开头**不**给平级选项（给了就等于发许可证——实测中性任务下模型会顺着它选内置），
-            // 只在末尾给"aura_read 真做不到"的那两种情况。
-            'Use the aura_read tool — not read — for every text-file read: it is the default, and it shows structure instead of raw bytes.',
+            // 只在末尾给"aura_basetools_read 真做不到"的那两种情况。
+            'Use the aura_basetools_read tool — not read — for every text-file read: it is the default, and it shows structure instead of raw bytes.',
             'Start with `map` when you do not yet know the file (an importance-ranked symbol directory); use `around` or a line range (`start_line` + `end_line`) for the part you will edit; `digest` for a file\'s interface and dependencies; `changed` to see what moved since a previous read.',
             // 刻意**不再**写"未知扩展名请用内置 read"。实测这句话是错的：未知扩展名上
             // `auto` 会降级到 `full`，内容照给（见 locator-lab/disable-check.mjs）。
@@ -522,13 +527,13 @@ export function apply(ctx) {
             // 措辞仍是命令式，与上下文同形；放在兜底条件**之前**，让“何时该用内置 read”仍是最后一句。
             'When several files are needed — or several places in files you are about to change — pass `targets` instead of calling once per file: one call, one receipt per target, output in input order, and a missing file does not fail the rest.',
             // 兜底条件写明白：不写会让模型在确实需要内置工具时犹豫（超大窗口 / aura 直接拒读）。
-            'The built-in `read` remains only for what aura_read cannot do: a raw window larger than one reply, or a file aura_read refuses.',
+            'The built-in `read` remains only for what aura_basetools_read cannot do: a raw window larger than one reply, or a file aura_basetools_read refuses.',
           ].join(' '),
   })
 
   ctx.tools.register(
     defineTool({
-      name: 'aura_read',
+      name: 'aura_basetools_read',
       description:
         'Read a file the way you actually need it. Seven modes, and `auto` picks the smallest one for you: ' +
         '`map` (what is in this file — an importance-ranked symbol directory), ' +
@@ -628,13 +633,29 @@ export function apply(ctx) {
           type: 'string',
           description: 'mode=search: a substring to find across the file.',
         },
+        max_chars: {
+          type: 'integer',
+          description: 'Ask for a smaller content budget than the host ceiling (chars).',
+        },
+        budget: {
+          type: 'integer',
+          description: 'Pipeline ceiling in chars; overrides the host pruner threshold for this call.',
+        },
+        offset: {
+          type: 'integer',
+          description: 'Pagination: 0-based line offset; use with `limit` (mutually exclusive with lines/start_line+end_line).',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Pagination: number of lines (default 2000); use with `offset`.',
+        },
         context: {
           type: 'integer',
           description: 'mode=around: how many lines of context on each side. Default 8.',
         },
         since: {
           type: 'string',
-          description: 'mode=changed: the `version` value from a previous aura_read of this file.',
+          description: 'mode=changed: the `version` value from a previous aura_basetools_read of this file.',
         },
         kind: {
           type: 'string',
@@ -667,7 +688,7 @@ export function apply(ctx) {
             totalLines: { type: 'integer' },
             // `text` 必须声明。第一版漏了它——而渲染器返回的正是 `text`，
             // 于是**每一条成功路径**都被框架以 `additionalProperties: false` 拒绝：
-            //   tool "aura_read" returned invalid output: "value.text" is not a declared property
+            //   tool "aura_basetools_read" returned invalid output: "value.text" is not a declared property
             // 我的 load-test 当时 29/29 全绿，因为它从不校验输出是否合自己声明的 schema。
             // 现在那道校验补上了，这类错误不会再穿过测试。
             text: { type: 'string', required: true },
@@ -702,6 +723,21 @@ export function apply(ctx) {
               },
             },
             symbols: { type: 'integer' },
+            /**
+             * 0.9.8：确定性的回执 metrics（引擎统一附加）。只放可由内容复算的事实，
+             * 不放墙钟；`truncated` 表示 `omitted` 是否存在（有没有被预算裁过）。
+             */
+            metrics: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                mode: { type: 'string', required: true },
+                lines: { type: 'integer', required: true },
+                chars: { type: 'integer', required: true },
+                symbols: { type: 'integer' },
+                truncated: { type: 'boolean', required: true },
+              },
+            },
             // `version` 可选，而不是必填。历史：它曾是必填，而当时 `changed` 在 `since` 缺省下不给令牌，
             // 于是 around／lines／search 与所有未索引扩展名上它是 undefined，真实会话里 .json／.yml／.md
             // 的读取被框架整条拒掉，才改成可选。
@@ -873,31 +909,29 @@ export function apply(ctx) {
          * 它抛的是**参数面**错（`ARGS_TARGETS_SHAPE` / `ARGS_TARGETS_LIMIT` / `ARGS_SHAPE_EXCLUSIVE`），
          * 逐项失败则是结果通道（引擎已把每项封成结果，不抛）。
          */
-        const batch = assertReadTargets(args, { toolName: 'aura_read' })
+        const batch = assertReadTargets(args, { toolName: 'aura_basetools_read', elementKeys: MT_READ_ELEMENT_KEYS })
         if (batch !== undefined) {
           // 多目标形状同样要过未知参数守卫：拼错的键不因为换了形状就被放行。
-          assertKnownArgs(args, READ_ARG_KEYS, 'aura_read')
+          assertKnownArgs(args, READ_ARG_KEYS, 'aura_basetools_read')
           return await readTargetsBatch(ctx, exec, batch)
         }
         /**
          * “二选一”的**另一半**（两个都没给 ⇒ 也拒）只有一份判据，住在 `args.mjs` 的
          * `assertTargetShape`（`src/locator-lab/args.mjs:455`）——壳里原来那句
          * `file_path must be a non-empty string` 是特例写法，已删（它把“没有形状可用”
-         * 说成了“file_path 写错了”，而 aura_edit 壳里还长着同一句：两处必然会漂）。
+         * 说成了“file_path 写错了”，而 aura_basetools_edit 壳里还长着同一句：两处必然会漂）。
          * 抛的仍是参数面同族码 `ARGS_SHAPE_EXCLUSIVE`；单目标调用照旧带 `file_path`，故这条路一字未变。
          */
-        assertTargetShape(args, { toolName: 'aura_read' })
-        // 参数形状在这里收敛一次：后面只认 {start, end}，三个调用面（工具壳/CLI/MCP）判据一致。
-        const lineRange = lineRangeOf(args)
-        if (lineRange === undefined && gaveLineAddress(args)) {
-          throw new Error(LINE_ADDRESS_HINT)
+        assertTargetShape(args, { toolName: 'aura_basetools_read' })
+        // 参数形状在这里收敛一次：行区间 / 分页 / 模式推断与 CLI/MCP、targets 元素共用
+        // 同一个 `normalizeReadRequest`。旧版这里只看 `lines`，`offset/limit` 在本面被静默忽略。
+        assertKnownArgs(args, READ_ARG_KEYS, 'aura_basetools_read')
+        const shape = normalizeReadRequest(args)
+        if (shape.ok !== true) {
+          throw Object.assign(new Error(shape.error), { code: shape.code })
         }
-        // 给了行区间就用 lines 模式，省掉"顺手再写一个 mode"的机会（写了也尊重）。
-        // 未知参数不回默认行为：拼错的字段被静默忽略时，模型看到的是**成功**。
-        assertKnownArgs(args, READ_ARG_KEYS, 'aura_read')
-        // 未知参数不回默认行为：拼错的字段被静默忽略时，模型看到的是**成功**。
-        assertKnownArgs(args, READ_ARG_KEYS, 'aura_read')
-        const mode = inferReadMode(args, lineRange)
+        let mode = shape.mode
+        let lineRange = shape.lines
         const cwd = exec.agent?.session?.header?.cwd
         const target = await ctx.fs.resolve(args.file_path, {
           ...(cwd !== undefined ? { cwd } : {}),
@@ -907,12 +941,15 @@ export function apply(ctx) {
         const info = await ctx.fs.stat(target, exec.signal)
         if (info === undefined) {
           // **缺失也要记录成一次观测。** 这是 dsh-tool-fs 的契约：`fs/observed` 的
-          // `{kind:'absent'}` 让后续 `write` 能走"带防护的创建"而不是被策略拒绝。
-          // 我第一版直接抛错、不记录，于是"读一个还不存在的文件，然后创建它"这条
+          // `{kind:'absent'}` 让后续 `create` 能走"带防护的创建"而不是被策略拒绝。
+          // 我第一版直接抛错、不记录，于是"读一个还不存在的文件、然后创建它"这条
           // 完全正常的流程会在写入侧失败——而且失败原因看起来与读取毫无关系。
           ctx.emit('fs/observed', target, { kind: 'absent' }, exec)
           throw new Error(`cannot read "${target.displayPath}": not found`)
         }
+        if (info.type === 'directory' && shape.paginate) {
+          throw Object.assign(new Error('offset/limit applies to files; a directory is returned as a repo map — drop pagination'), { code: 'READ_BAD_ARGS' })
+        }
         /**
          * 目录：**不读文件，直接给一张仓库地图**（T26）。
          *
@@ -971,7 +1008,7 @@ export function apply(ctx) {
           source = await ctx.fs.readText(target, exec.signal)
         } catch (error) {
           if (!isNonUtf8TextFailure(error)) throw error
-          throw Object.assign(new Error(nonUtf8RefusalMessage('read', target.displayPath, 'aura_read')), {
+          throw Object.assign(new Error(nonUtf8RefusalMessage('read', target.displayPath, 'aura_basetools_read')), {
             code: typeof error.code === 'string' && error.code.length > 0 ? error.code : 'ERR_ENCODING_INVALID_ENCODED_DATA',
             cause: error,
           })
@@ -979,6 +1016,16 @@ export function apply(ctx) {
         // BOM 只存在于字节里（readText 会在解码时丢掉它）——版本令牌要能区分只差 BOM 的两个文件，
         // 就必须把这个事实从字节里取出来交给引擎。
         const byteOrderMark = await fileStartsWithByteOrderMark(ctx.fs, target, exec.signal)
+        /**
+         * 第二遍收敛：拿到总行数后才能做 offset 越界与尾行截断。
+         * 与单目标 `readEnvelope`、targets 元素**同一个**判定器。
+         */
+        const finalShape = normalizeReadRequest(args, source.split(/\r?\n/).length)
+        if (finalShape.ok !== true) {
+          throw Object.assign(new Error(finalShape.error), { code: finalShape.code })
+        }
+        mode = finalShape.mode
+        lineRange = finalShape.lines
         /**
          * 宿主给"单条工具结果"定的字符上限，**当场读**（不在引擎里抄）。
          *
@@ -992,6 +1039,8 @@ export function apply(ctx) {
          * 且因为披露机制在，偏保守不会丢信息。
          */
         const hostCeiling = (() => {
+          const explicit = Number.isInteger(args.budget) && args.budget > 0 ? args.budget : undefined
+          if (explicit !== undefined) return explicit
           const pruner = ctx.get('toolResultPruner')
           const threshold = pruner?.config?.thresholdChars
           return Number.isInteger(threshold) && threshold > 0 ? threshold : undefined
@@ -1065,6 +1114,8 @@ export function apply(ctx) {
           // changed 的 `since` 用文件版本而非内容指纹：调用方从 read 结果里拿到的是版本，
           // 而版本来自 fs 后端，因此跨进程、跨工具都一致。
           ...(args.since === undefined ? {} : { since: args.since }),
+          // `max_chars` 是调用方要求**更小**的预算；与 CLI/MCP/多目标同一字段。
+          ...(args.max_chars === undefined ? {} : { maxChars: args.max_chars }),
           // 流水线硬上限**现读现传**，不在引擎里抄一个常量。
           // `toolResultPruner.config.thresholdChars` 是可配置的（dsh-base 与三个 preset 都显式写着），
           // 所以"抄进引擎"会在宿主改配置时静默失准（调大→白白少给，调小→中段被剪）。

package/cordis.patch.yml

@@ -4,6 +4,7 @@
 # （dsh-app-boot/README.md:59），因此包装在 Windows / macOS / Linux、装在任意目录都成立。
 #
 # 内置 read / write / edit / read_image 一个都没停用：只加不减。
+# aura_basetools_write 与 aura_basetools_edit 由同一个插件模块注册（只多一个工具，不多一行 patch）。
 # read_image 没有 Aura 替代品，停用 tool-fs 会净损失读图能力。
 - insert:
     - id: tool-aura-read

package/dsh/argv-shell.mjs

@@ -0,0 +1,290 @@
+/**
+ * argv-shell —— 宿主钩子专用的「不经任何 shell」执行器（`ctx.shell` 的提供者）。
+ *
+ * 【这是什么】把钩子桥交来的命令【字符串】按最小词法切成 argv，直接交给
+ *   `ctx.subprocess.spawn({ argv })`；中间不启动任何 shell、不做命令替换、不做元字符解释。
+ *   语义等价于 `@deepseek-ai/dsh-native-command` 的 `runNativeCommand`（execFile，argv 原样给 OS），
+ *   只是搬到了 shell 接缝上 —— 因为 `dsh-hook-protocol` 的 `runHook()` 只认
+ *   `ctx.shell.run(ctx.shell.resolve({ command }))`，钩子配置里没有任何 argv 字段。
+ *
+ * 【为什么】宿主现行 `ctx.shell` 是 `@deepseek-ai/dsh-pwsh-local`：命令串被拼成
+ *   `pwsh -NoLogo -NoProfile -NonInteractive -Command "<前置编码指令><串>"` 再解析一遍。
+ *   PreToolUse 每个工具调用都要付这一层（p50 686ms，n=58,139），其中 76–84% 是这层壳，
+ *   真正的判定+落账只占 4.7%。换成本执行器 = 把壳层整个删掉。
+ *
+ * 【口径】只做最小、可预测的词法：空白分词；双/单引号成组并去掉引号；反斜杠只在成对引号内
+ *   转义（Windows 路径里的 `\` 必须原样保留）。`;` `|` `&` `$` `%` 反引号【都不是元字符】——
+ *   这正是它与 shell 的全部差别。引号不配对 = 抛错（不猜，宁可响亮失败）。
+ *
+ * 【边界】只实现 `run()`（钩子桥只用它）。`start()` 明确抛错：本执行器只挂在
+ *   `polaris-hooks-unconfined` 隔离组里，组内没有任何后台消费者 —— 不做半个实现。
+ *
+ * 【回滚】把 `<DSH_HOME>/profiles/<profile>/cordis.patch.yml` 里那一行的 name 改回
+ *   `@deepseek-ai/dsh-pwsh-local` 即可（本文件可以留着，没人指向它就永远不会被 import）。
+ *
+ * @module dsh/argv-shell
+ */
+import path from 'node:path'
+import { ShellExecutor } from '@deepseek-ai/dsh-shell'
+import z from '@deepseek-ai/schemastery'
+
+const DEFAULT_GRACE_MS = 3000
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
+/** 与 pwsh-local 同款的非交互环境覆盖：去掉颜色与分页器，免得混进被抓取的 stdout。 */
+const ENV_OVERRIDES = { NO_COLOR: '1', PAGER: 'cat', GIT_PAGER: 'cat' }
+
+/**
+ * 命令串 -> argv。纯函数、无副作用、不碰任何 shell 语义。
+ * @param command - 钩子配置里的命令串（跨 shell 同形写法：只用双引号、路径用正斜杠）。
+ * @returns argv；argv[0] 是程序，其余原样传给子进程。
+ * @throws 引号不配对时抛错（不猜一个"大概是这个意思"的 argv）。
+ */
+export function tokenizeArgv (command) {
+  if (typeof command !== 'string') throw new TypeError('argv-shell: command must be a string')
+  const out = []
+  let token = ''
+  let started = false
+  let quote = null
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== null) {
+      // 反斜杠只在【紧跟本段引号】时转义；其余一律字面（Windows 路径不能被吃掉反斜杠）。
+      if (ch === '\\' && command[i + 1] === quote) { token += quote; i++; continue }
+      if (ch === quote) { quote = null; continue }
+      token += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue }
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+      if (started) { out.push(token); token = ''; started = false }
+      continue
+    }
+    token += ch
+    started = true
+  }
+  if (quote !== null) throw new Error('argv-shell: unbalanced ' + quote + ' in command: ' + command)
+  if (started) out.push(token)
+  return out
+}
+
+// —— AuraPolaris PreToolUse 钩子的【进程内短路支路】———————————————
+// 【为什么】这条钩子是每个工具调用都要付一次的固定成本，而它要干的判定只有几毫秒：剩下全是
+//   "起两个 Node 进程"的税（宿主 → windows-job runner → 真身）。本执行器【就活在宿主进程里】
+//   （见文件头：它是 ctx.shell 的提供者），所以这一次调用完全可以不出进程。
+// 【代价面】2026-10-15 实测（串行、每路 n=24）：
+//   spawn 路径（含 windows-job runner 间接层）p50 ≈ 250–276ms，进程内路径 p50 ≈ 4ms；
+//   其中钩子自己的判定只占 ≈6ms（关掉：AURA_HOOK_INPROC=0）。
+// 【边界】①只认 PreToolUse（其它事件不归本支路）；②任何不确定都退回下面的 spawn 原路；
+//   ③非钩子命令在这段里只多一次 O(argv) 的字符串预筛，一个字节的行为变化都没有。
+// 关掉：环境变量 AURA_HOOK_INPROC=0（不必改宿主 profile）。
+const HOOK_SCRIPT_RE = /(?:^|[\\/])hook\.mjs$/i
+const NODE_BASENAMES = new Set(['node', 'node.exe', 'nodejs', 'nodejs.exe'])
+
+/**
+ * 便宜预筛：这串 argv 像不像「node <…>/hook.mjs … --event=PreToolUse」。
+ * 【这不是判定】—— 权威识别在 hook-inproc.recognizePreToolUseHook（那里解析脚本路径、校验同目录的
+ *   guard-core/adapters 布局）。这里只回答"值不值得去 import 那个模块"：漏判 = 白付一次 spawn，
+ *   误判 = 多一次 import + 一次失败返回，两种都不改变行为、都不会变成放行。
+ */
+function looksLikePreToolUseHook (argv) {
+  if (!Array.isArray(argv) || argv.length < 2) return false
+  if (typeof argv[0] !== 'string' || !NODE_BASENAMES.has(path.basename(argv[0]).toLowerCase())) return false
+  let script = false
+  let event = false
+  for (let i = 1; i < argv.length; i++) {
+    const token = argv[i]
+    if (typeof token !== 'string') continue
+    if (!script && !token.startsWith('-') && HOOK_SCRIPT_RE.test(token)) { script = true; continue }
+    if (token.startsWith('--event=')) event = token.slice('--event='.length).trim().toLowerCase() === 'pretooluse'
+    else if (token === '--event' && typeof argv[i + 1] === 'string') event = argv[i + 1].trim().toLowerCase() === 'pretooluse'
+  }
+  return script && event
+}
+
+/** 记一次分派（可观测标记）。写标记失败不许影响这次调用：吞掉。 */
+function noteDispatch (mod, kind, reason) {
+  try { if (typeof mod?.noteHookDispatch === 'function') mod.noteHookDispatch(kind, reason) } catch { /* 标记是读数，不是判据 */ }
+}
+
+/**
+ * 短路支路：把已知的 AuraPolaris PreToolUse 钩子在本进程内跑完。
+ * @returns 与 spawn 路径【同形】的结果对象；返回 null = 走原来的 spawn（一个字都没改的那条路）。
+ */
+async function inProcessShortCircuit (executor, argv, spec) {
+  if (!looksLikePreToolUseHook(argv)) return null
+  // 懒加载：非钩子命令不付这个模块的任何代价（构造执行器时也不 import）。
+  let mod
+  try { mod = await import('./hook-inproc.mjs') } catch { return null }
+  if (process.env.AURA_HOOK_INPROC === '0') { noteDispatch(mod, 'spawn', 'disabled'); return null }
+  let result = null
+  try {
+    result = await mod.runPreToolUseHookInProcess({
+      argv,
+      stdin: typeof spec.stdin === 'string' ? spec.stdin : '',
+      workdir: spec.workdir,
+      stdoutMaxBytes: spec.stdoutMaxBytes,
+      stderrMaxBytes: executor.config.maxOutputBytes,
+      signalAborted: spec.signal !== undefined && spec.signal.aborted === true,
+    })
+  } catch (error) {
+    // 抛 = 这条支路不可用。这里【只】退回 spawn：合成任何判定都等于把"护栏坏了"变成"放行"。
+    noteDispatch(mod, 'spawn', `threw:${String(error?.message ?? error).slice(0, 60)}`)
+    return null
+  }
+  // 形状不对（缺字段 / 类型不对 / ok 不是 true）= 与"抛"同等处理：退回 spawn。
+  if (result === null || typeof result !== 'object' || result.ok !== true ||
+    typeof result.exitCode !== 'number' || typeof result.stdout !== 'string' || typeof result.stderr !== 'string') {
+    noteDispatch(mod, 'spawn', String(result?.reason ?? 'unshaped'))
+    return null
+  }
+  noteDispatch(mod, 'inproc', 'ok')
+  return {
+    exitCode: result.exitCode,
+    signal: null,
+    timedOut: false,
+    aborted: spec.signal !== undefined && spec.signal.aborted === true,
+    timeoutMs: spec.timeoutMs,
+    stdout: { text: result.stdout, truncated: false },
+    stderr: { text: result.stderr, truncated: false },
+  }
+}
+
+/** 把已结算的 collect 读取器投影成 CollectedOutput。 */
+function finalOutput (reader) {
+  const read = reader.readFrom(0)
+  const out = { text: read.text, truncated: read.lossy }
+  if (read.spillPath !== undefined) out.spillPath = read.spillPath
+  return out
+}
+
+function assertPositiveFinite (name, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new Error('argv-shell: ' + name + ' must be a positive finite number')
+  }
+}
+
+function clampTimeout (value, base, max, label) {
+  if (value === undefined) return base
+  assertPositiveFinite(label, value)
+  return Math.min(value, max)
+}
+
+/**
+ * 本地 argv 执行器：`ctx.shell` 的无 shell 实现。
+ */
+export class ArgvShellExecutor extends ShellExecutor {
+  static inject = ['subprocess']
+  static Config = z.object({
+    cwd: z.string(),
+    timeoutMs: z.number().default(120000),
+    maxTimeoutMs: z.number().default(600000),
+    maxOutputBytes: z.number().default(64000),
+    maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
+    graceMs: z.number().default(DEFAULT_GRACE_MS),
+  })
+
+  constructor (ctx, config) {
+    super(ctx)
+    assertPositiveFinite('argv-shell: timeoutMs', config.timeoutMs)
+    assertPositiveFinite('argv-shell: maxTimeoutMs', config.maxTimeoutMs)
+    assertPositiveFinite('argv-shell: maxOutputBytes', config.maxOutputBytes)
+    assertPositiveFinite('argv-shell: maxSpillBytes', config.maxSpillBytes)
+    assertPositiveFinite('argv-shell: graceMs', config.graceMs)
+    this.entry = config
+  }
+
+  get config () { return this.entry }
+
+  /** 不沙箱化：本执行器是「宿主壳层的替身」，不引入任何新的执行语义。 */
+  get sandboxMode () { return undefined }
+
+  /** 与 pwsh-local 同款：填 workdir / timeoutMs / stdoutMaxBytes，其余原样透传。 */
+  resolve (request) {
+    const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, 'argv-shell: request.timeoutMs')
+    const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes
+    assertPositiveFinite('request.stdoutMaxBytes', stdoutMaxBytes)
+    const spec = {
+      command: request.command,
+      workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
+      timeoutMs,
+      stdoutMaxBytes,
+      sandboxPolicy: request.sandboxPolicy,
+    }
+    if (request.signal !== undefined) spec.signal = request.signal
+    if (request.stdin !== undefined) spec.stdin = request.stdin
+    if (request.env !== undefined) spec.env = request.env
+    if (request.dshEnv !== undefined) spec.dshEnv = request.dshEnv
+    return spec
+  }
+
+  /** 命令串 -> argv。本执行器与 pwsh-local 的【唯一】实质差别就在这一步。 */
+  argv (spec) {
+    const out = tokenizeArgv(spec.command)
+    if (out.length === 0) throw new Error('argv-shell: empty command')
+    return out
+  }
+
+  spawnSpec (spec, stdoutMaxBytes, signal, argv) {
+    const collect = (maxBytes) => ({ maxBytes, spill: { maxBytes: this.config.maxSpillBytes } })
+    const out = {
+      argv: [...argv],
+      cwd: spec.workdir,
+      stdio: {
+        stdin: spec.stdin !== undefined ? { data: spec.stdin } : 'ignore',
+        stdout: collect(stdoutMaxBytes),
+        stderr: collect(this.config.maxOutputBytes),
+      },
+      graceMs: this.config.graceMs,
+      env: { ...ENV_OVERRIDES, ...spec.env, ...spec.dshEnv },
+    }
+    if (signal !== undefined) out.signal = signal
+    return out
+  }
+
+  async run (spec) {
+    const argv = this.argv(spec)
+    // 短路支路：已知的 AuraPolaris PreToolUse 钩子在进程内跑完。null = 原路（下面的代码一个字没改）。
+    const shortcut = await inProcessShortCircuit(this, argv, spec)
+    if (shortcut !== null) return shortcut
+    const controller = new AbortController()
+    const onCallerAbort = () => controller.abort()
+    let timedOut = false
+    const timer = setTimeout(() => { timedOut = true; controller.abort() }, spec.timeoutMs)
+    if (spec.signal !== undefined) {
+      if (spec.signal.aborted) controller.abort()
+      else spec.signal.addEventListener('abort', onCallerAbort, { once: true })
+    }
+    let handle
+    let outcome = { exitCode: null, signal: null }
+    let failure = null
+    try {
+      handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, controller.signal, argv))
+      outcome = await handle.done
+    } catch (error) {
+      failure = error
+    } finally {
+      clearTimeout(timer)
+      if (spec.signal !== undefined) spec.signal.removeEventListener('abort', onCallerAbort)
+    }
+    const outputs = handle === undefined ? undefined : handle.collected
+    const stdout = outputs !== undefined && outputs.stdout !== undefined ? finalOutput(outputs.stdout) : { text: '', truncated: false }
+    const stderr = outputs !== undefined && outputs.stderr !== undefined
+      ? finalOutput(outputs.stderr)
+      : { text: failure === null ? '' : String(failure.message ?? failure), truncated: false }
+    return {
+      ...outcome,
+      timedOut,
+      aborted: spec.signal !== undefined && spec.signal.aborted === true && !timedOut,
+      timeoutMs: spec.timeoutMs,
+      stdout,
+      stderr,
+    }
+  }
+
+  /** 后台执行不属于本执行器的用例面（隔离组里只有钩子桥这一个消费者）。 */
+  start () {
+    throw new Error('argv-shell: background execution is not implemented — this executor only serves the hooks bridge')
+  }
+}
+
+export default ArgvShellExecutor