fix(docs): distinguish permission-mode yolo from the print bypass flag #1030

Summary

The permissions reference says --permission-mode yolo is equivalent to --yolo / --dangerously-skip-permissions. In print mode, the first form leaves the write/shell gate enabled: the requested file is not created, while replacing it with --yolo creates the file. This fails closed and is a documentation/CLI-contract mismatch, not a security bypass report.

Steps to reproduce

1. Use the published package stated under Runtime or environment, with an existing login and access to the free model shown below.
2. Create a disposable directory, initialize it with git init -b main, and run the following command inside it.

cmd -p 'Create a file named gpmyolo.txt in the current directory containing the text ok. Use your file-writing tool; do not ask questions.' \
  -m stealth/cat-jam:free \
  --output-format json --max-turns 4 --no-auto-update \
  --trust --skip-onboarding --no-session --permission-mode yolo

3. Check whether gpmyolo.txt exists and inspect tool_hook_blocked events inside the JSON event envelopes.
4. Run the identical command with --yolo replacing --permission-mode yolo, then check the file and its content again. Both runs were bounded externally to 240 seconds; neither reached that limit.

Expected behavior

The documented equivalence should hold for print mode, or the hosted and bundled permissions references should clearly explain that selecting baseline yolo mode does not enable print-mode writes/shell and identify the required flag. Any resolution should preserve explicit deny rules and the intended bypass kill switch; this report does not prescribe broadening permissions.

Actual behavior

In one executed comparison, both invocations exited 0 with a final result subtype of success, but their artifacts differed:

The first run's write_file event contained:

Error: Tool "write_file" requires permissions. Use --yolo (or --dangerously-skip-permissions) to enable file writes and shell commands in print mode.

Its final response said it could not write files in that mode and asked for a restart with the bypass flag. The control completed the requested file write. The successful exit code is reported only as context; the observed contract failure is the different tool/artifact behavior.

Evidence

• Expected source: The hosted permissions reference, Switching modes, states the three flags have the same permission-bypass behavior. The same statement appears in published dist/bundled/command-code-knowledge/reference/permissions.md:143.
• Failure source: The executed two-command comparison above, including the blocked tool events and direct filesystem checks. Published dist/cli.mjs also defines resolvePrintHarnessMods({dangerouslySkipPermissions:e}) as returning no gate only when that flag is true; otherwise it adds createPrintPermissionGateMod().
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The CLI's --yolo option implies dangerouslySkipPermissions: true; --permission-mode yolo sets the normalized permission mode without setting that boolean. runPrintMode passes the boolean to resolvePrintHarnessMods, so the baseline permission mode does not remove this additional print gate.

Restoration check

Re-run the two commands in the disposable repository and inspect tool events plus the actual file. Passing means either the documented equivalent invocations produce equivalent authorized write behavior, or the hosted and bundled permissions references accurately state the print-mode distinction and the required flag. A success result without the requested artifact does not establish equivalence.

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: Bash, print mode, disposable Git repository, existing login, model stealth/cat-jam:free.
• Current public default branch: main at c48f96fb959ceb0eae3f12dba4430be98b587031, inspected in a fresh clone. It does not contain the CLI or permissions docs source, so runtime checks target the published package and current hosted page.

Additional context

This report is limited to the executed print-mode comparison. No interactive TUI comparison was executed. Source tracing shows both forms select baseline bypass mode interactively, but that is not evidence that every flag side effect is identical: the standalone bypass flag also supplies automatic trust. The CLI parser's accepted-value list and its --help description are outside this report.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: Following the documented flag equivalence prevents the requested unattended file write even though the command completes; the demonstrated effect is bounded to print-mode write/shell gating.
• Workaround status: available
• Workaround basis: In the same disposable trusted repository, replacing the mode option with the explicitly documented --yolo flag created the requested file with the expected content. This is appropriate only when permission bypass was already intended, and is not a workaround for a workflow that requires restrictive permissions.