fix(docs): clarify that Claude permission aliases fail on the CLI flag #1029

Summary

The permissions reference lists Claude Code spellings as working mode aliases without distinguishing the CLI flag from settings. All four spellings listed there are rejected by --permission-mode. A user following that alias guidance to select a start mode gets a parser error before the requested task can run. The settings alias claim is supported by the published settings loader; this report concerns the undocumented difference at the CLI boundary.

Steps to reproduce

1. Install the published package stated under Runtime or environment.
2. Run each command below. These rejected inputs fail before login or a model request is needed.

cmd -p x --permission-mode manual --no-auto-update
cmd -p x --permission-mode acceptEdits --no-auto-update
cmd -p x --permission-mode dontAsk --no-auto-update
cmd -p x --permission-mode bypassPermissions --no-auto-update

Expected behavior

The documented alias guidance should accurately identify which input surfaces accept each spelling. Either these documented aliases should work on the CLI flag, or the permissions reference should state their narrower scope and give CLI users accepted equivalents. This report does not request a particular compatibility implementation.

Actual behavior

Each of the four commands exits 1. For example:

error: option '--permission-mode <mode>' argument 'acceptEdits' is invalid. Allowed choices are default, standard, plan, accept-edits, auto-accept, yolo, bypass, dont-ask.

The other three errors differ only in the rejected argument. This is separate from the short mode list displayed in --help.

Evidence

• Expected source: The hosted permissions reference, Permission modes → Aliases, lists manual, acceptEdits, dontAsk, and bypassPermissions as working Claude Code spellings. The package's dist/bundled/command-code-knowledge/reference/permissions.md:126 contains the same guidance; line 440 explicitly documents acceptEdits for settings defaultMode.
• Failure source: The four executed commands above return parser errors. In published dist/cli.mjs, the CLI option uses .choices(V$) and parsePermissionModeOption, whose eight-value allowlist is checked before normalizePermissionMode.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The published settings loader parses and merges settings.json without a permission enum restriction, and createConfigStore().getPermissionMode() calls normalizePermissionMode. Executing those extracted functions against disposable settings files gave manual → default, acceptEdits → internal auto-accept, dontAsk → dont-ask, and bypassPermissions → internal bypass. This helper test used an empty legacy configuration stub; it was not a full CLI/TUI launch. The setting aliases are therefore not alleged to be broken.

Restoration check

Re-run all four commands and compare their outcome with the alias scope stated in the hosted and bundled permissions references. Passing means each documented CLI alias works, or the references clearly distinguish settings aliases from accepted CLI values so those commands are no longer presented by implication as supported CLI inputs. Preserve the existing settings alias normalization. Changes to the abbreviated help list alone do not resolve this report.

Runtime or environment

• Command Code: npm command-code 1.82.4, confirmed as the latest published release and installed in an isolated prefix.
• Node.js: v26.10.0.
• Operating system: macOS, Darwin 27.0.0, arm64.
• Invocation: headless command from Bash, isolated HOME for parser checks.
• Current public default branch: main at c48f96fb959ceb0eae3f12dba4430be98b587031, inspected in a fresh clone. It contains tracker/configuration/registry content, not the CLI or permissions docs source; the behavioral checks therefore target the published package and current hosted page.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: Using the documented alternate spellings with the start-mode flag aborts the command before work begins; the affected inputs are bounded to these aliases.
• Workaround status: available
• Workaround basis: The parser lists accepted equivalents in its error, including default, accept-edits, dont-ask, and yolo; its published allowlist and normalization accept these spellings. Choosing the equivalent preserves the selected permission policy.