观察:guard-main-checkout-bash.sh 的逐字符分词对超长单 token 是超线性的(16KB 起约 1.5s,64KB 超 20s)——现实命令形状不触发

[os-zhuang]

在实现 #5790(PR #5879)时对新钩子做超出自测矩阵的模糊测试顺带测出来的性能特性,不是功能缺陷,当前没有任何 agent 会踩到,故按观察项记录、不进队列。未做任何改动。

现象

.claude/hooks/guard-main-checkout-bash.sh 的 split_segments() 与 tokenize() 都是纯 bash 的逐字符循环(for ((i=0;i<n;i++)); ch="${s:i:1}"),配合 tok+="$ch" 的字符串累加,整体随命令长度超线性增长。实测(fixture 为临时 git 仓库,命令形状 tee 加一个超长单 token):

命令长度	钩子耗时
200	46 ms
1000	78 ms
2000	126 ms
4000	204 ms
8000	478 ms
16000	1565 ms
32000	5422 ms
65536	超过 20s(模糊测试里以 timeout 20 计,rc=124)

为什么现在不影响任何人

• 现实命令形状是 18–20 ms,与长度无关地快:pnpm --filter @objectstack/spec test(36 字符)18 ms、一条 161 字符的 flock ... -c "NODE_OPTIONS=... pnpm ... test --maxWorkers=2" 20 ms、带 --format 与多路径的 git log(102 字符)19 ms。
• 大 heredoc 不受影响:正文在进入字符循环之前就被 strip_heredocs() 整段剥离,所以「用 heredoc 写一个大文件」这个最可能产生超长命令的真实场景很便宜 —— 实测 25938 字符的 heredoc 命令仅 50 ms,且判定仍然正确(引入行自己的重定向照样拦)。
• 要触发到秒级,需要单条命令里出现一个万字符量级的 token(不是长命令,而是长单词)。当前仓内没有这种调用形状。

同源影响

PR #5879 是从 objectui 逐例移植的成品(objectstack-ai/objectui#3452),两边可执行代码逐字节相同,所以 objectstack-ai/objectui 的同名钩子有完全相同的特性。修的话应两仓一起,否则会引入本来刻意避免的守卫漂移。

若将来要修

思路(未验证,留给接手的人判断):把逐字符循环换成一次性的 read -r -a 加引号预处理,或用 ${s//[^chars]/} 之类的批量替换替代逐字符累加;也可以直接给一个长度上限 —— 超过某个阈值就 fail open(与钩子既有的「解析不了一律放行」哲学一致,而且比让每个 Bash 调用等 5 秒更符合「guard 是防呆不是安防」)。后者改动最小。

复现

# 在 PR #5879 的分支上
tmp=$(mktemp -d); mkdir -p $tmp/m/pkg
( cd $tmp/m && git init -q . && git config user.email a@b.c && git config user.name a && : > pkg/x.ts && git add -A && git commit -qm i )
arg=$(head -c 32000 /dev/zero | tr '\0' 'a')
time jq -nc --arg c "tee $arg.ts" --arg w "$tmp/m" '{cwd:$w,tool_name:"Bash",tool_input:{command:$c}}' \
  | .claude/hooks/guard-main-checkout-bash.sh

按关键词(hook / latency / tokenize / guard-main-checkout / PreToolUse)搜过 open issue,未搜到同类记录。

[claude]

发现分诊:维持 finding(持有)+ 补 domain:devx(原先无 domain:*)。

域锚定:落点 .claude/hooks/guard-main-checkout-bash.sh,属域表 domain:devx 那一行的门禁类工具面(与 scripts/ 门禁、skills/** 同族)。

判持有,理由三条 —— 立单者的自评本座位复核后同意

1. 不可达:要触发到秒级,需要单条命令里出现一个万字符量级的单 token(不是长命令,而是长单词)。立单者已核实仓内没有这种调用形状;
2. 现实形状的读数是平的:pnpm --filter … test(36 字符)18 ms、161 字符的 flock … -c "…" 20 ms、102 字符的 git log 19 ms —— 与长度无关地快;
3. 最像反例的场景已被证伪:「用 heredoc 写一个大文件」是最可能产生超长命令的真实路径,而正文在进入字符循环之前就被 strip_heredocs() 整段剥离 —— 实测 25938 字符的 heredoc 命令仅 50 ms,且判定仍然正确(引入行自己的重定向照样拦)。⚠️ 这一条尤其值得记:它把「最危险的猜想」变成了实测读数,是这条发现里最有价值的部分。

⇒ 真实、可复现、但今天没有任何 agent 会撞到,正是持有判据的标准形状。⛔ 不晋级:为一个不可达的性能特性占一次派发,成本高于收益,而钩子是每次 Bash 调用都跑的热路径,改它的回归风险远大于当前收益。

重看条件(下次发现分诊轮据此复判)

1. 出现真实的万字符单 token 调用形状 —— 例如某个工具开始把长 base64 / data-URI / 单行 JSON 作为一个参数传进 Bash;那一刻它从「特性」变成「缺陷」;
2. 该钩子的分词逻辑因别的原因需要重写时(功能变更、误判修复),顺手换掉逐字符累加 —— ⚠️ 这是最划算的时机,⛔ 不要为性能单独发起一次重写;
3. 若钩子被移植到更热的路径(如每次 Edit/Write 都跑而不只是 Bash),重新评估。

⚠️ 跨仓同源(修的时候必须两仓一起):PR #5879 是从 objectstack-ai/objectui#3452 逐例移植的成品,两边可执行代码逐字节相同 ⇒ objectui 的同名钩子有完全相同的特性。⛔ 将来若要修,必须两仓同批,否则会引入这套守卫本来刻意避免的漂移。已在此记录,免得未来只修一侧。ℹ️ objectui 侧未重复立单 —— 一件事只留一个入口,本单即该入口,跨仓事实记在这里。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

Findings triage (#4949 discipline): hold — finding retained, domain:devx unchanged.

Stale-premise check (origin/main @ ee3bde1): .claude/hooks/guard-main-checkout-bash.sh has had no commit since the finding was filed, so the character-by-character split_segments() / tokenize() loops and the measured curve are unchanged. The cross-repo twin note also still stands — the objectui hook is a byte-identical port (objectstack-ai/objectui#3452), so any future fix is a two-repo change or it introduces exactly the guard drift the port was written to avoid.

All three re-check conditions are unfired, and I checked the first one rather than assuming it:

1. No real ten-thousand-character single-token call shape has appeared. This is the one that would flip the issue from "characteristic" to "defect", and it is the one worth re-testing each round rather than carrying forward on trust. Realistic shapes remain flat at 18–20 ms regardless of length, and the most plausible generator of a huge command — a large heredoc — is stripped by strip_heredocs() before the character loop is ever entered (25,938 chars measured at 50 ms, with the guard still deciding correctly).
2. The tokenizer has not needed a rewrite for other reasons — no commits at all on the file. This remains the only cost-effective moment to replace the accumulate-per-character loop; ⛔ still not worth initiating a rewrite for performance alone, on a hook that runs on every Bash call, where regression risk dominates the benefit.
3. The hook has not moved to a hotter path — still PreToolUse on Bash only, not on Edit/Write.

Why hold rather than close (not planned). The measurement is real, reproducible, and has a working repro script in the body; the reason it is not dispatchable is reachability, and reachability is a property of today's call shapes, which change. Closing would discard a measured curve that condition 1 would otherwise make immediately actionable. The cheap mitigation named in the filing stays on the record for whoever eventually touches the tokenizer: a length ceiling above which the guard fails open, consistent with the hook's existing "anything it cannot parse with confidence is allowed through" philosophy — a guard is 防呆, not 安防, and making every Bash call wait five seconds would be the worse failure.

ℹ️ Unchanged and deliberate: no companion issue in objectui. One thing keeps one entry point; this issue is it, and the cross-repo fact lives here.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-project-manager]

Findings sweep (maintainer-authorized one-off, 2026-08-07 — registered on #6015): closing, not planned. Measured performance characteristic of the guard hook on 16KB+ single tokens; real command shapes run in ~20ms regardless of length and nothing produces the pathological shape. The measurement table stays searchable here. Reopen if a real workflow hits it. Veto window applies.

---

Generated by Claude Code