zai-org / zai-org/feedback

[Bug] ZCode CLI 0.16.5:--help 列出 --allowed-tools / --max-turns,parser 却报 Unknown option(exit 1),headless 无法配工具白名单

Open
#600 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

环境

  • CLI runtime: zcode 0.16.5(ZCode.app 内置 zcode.cjs,macOS Apple Silicon;全局命令为指向 App 内 runtime 的 wrapper)
  • 使用面:headless(zcode --prompt)驱动无人值守编码 agent

现象

zcode --help 列出了 headless 专用 flag:

  --max-turns <n>  Maximum model turns for headless prompts
  --allowed-tools <list>  Comma/space-separated tool allowlist for headless prompts
  --disallowed-tools <list>  Comma/space-separated tool denylist for headless prompts

但其中 --allowed-tools--max-turns 实际未在 parser 注册,传入即报错:

$ zcode --allowed-tools "Read" --prompt "reply with exactly OK"
Unknown option '--allowed-tools'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--allowed-tools"'
zcode 0.16.5
# exit 1

$ zcode --max-turns 3 --prompt "reply with exactly OK"
Unknown option '--max-turns'. ...
# exit 1

对照:同帮助块的 --disallowed-tools 实测可用(已在生产 headless 编码流水线稳定使用),--mode / --cwd / --prompt 亦正常。

影响

  1. headless/自动化场景只能配 denylist、无法配 allowlist——对无人值守 agent,allowlist 是更强的安全保证(默认拒绝未知工具),目前安全姿态被迫降级
  2. --max-turns 无法限制无人值守回合数
  3. help 已承诺这两个 flag,按 help 使用必然踩坑;且报错是误导性的 Unknown option + 「把 flag 放到 -- 后当位置参数」的建议,无任何「未实现」提示

推测根因

headless flag 的 help 文本已加入但 parser 注册遗漏。一个佐证:--disallowed-tools 在 help 里出现两次——--disallowedTools, --disallowed-tools <tools...>(旧注册,可用)与 headless 块的 --disallowed-tools <list>(新块),疑似新旧两处注册表不同步,新块只注册了 --disallowed-tools 一个。

修复意愿

runtime 未开源、无法直接提补丁,但我可以:

  • 第一时间配合验证修复版(我们有生产 headless 编码卡流水线,--allowed-tools 白名单 + --max-turns 是真实依赖,可做真实负载回归)
  • 如需更多诊断(受影响版本范围、parser 注册表 dump、不同调用形态的对照),随时提

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the mismatch in the zcode 0.16.5 runtime with --help, --allowed-tools, and --max-turns, comparing them with the working --disallowed-tools, --mode, --cwd, and --prompt flags. Done means the two reported flags are accepted by headless invocations, enforce their stated limits, and remain accurately represented in --help.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.