[DOCS] Security-critical `-p` flag behavior (trust verification disabled) missing from CLI and headless documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

Primary: https://code.claude.com/en/security (Additional safeguards section) Also affected: - https://code.claude.com/en/headless - https://code.claude.com/en/cli-reference

Section/Topic

1. Security page - "Additional safeguards" section, Trust verification bullet point 2. Headless/SDK page - Missing security implications section entirely 3. CLI Reference - -p / --print flag description

Current Documentation

In security.md (lines 57-58):

* **Trust verification**: First-time codebase runs and new MCP servers require trust verification
  * Note: Trust verification is disabled when running non-interactively with the `-p` flag

In headless.md:
No mention of security implications. The page documents -p usage but omits that trust verification is disabled.

In cli-reference.md (line 58):

| `--print`, `-p` | Print response without interactive mode (see SDK documentation for programmatic usage details) | `claude -p "query"` |

No security warning about trust verification bypass.

What's Wrong or Missing?

A security-critical behavior change is buried in a nested bullet point on the security page and completely absent from the two places users are most likely to learn about -p mode:

1. Visibility problem: The security implication is a sub-bullet under "Trust verification" - users scanning for -p flag behavior won't find it
2. Discoverability problem: Users reading the headless mode docs or CLI reference will not see any security warning
3. Risk: Users may unknowingly:

• Run Claude Code on untrusted repositories in CI/CD pipelines without trust verification
• Load MCP servers from untrusted sources without consent
• Expose automated systems to prompt injection attacks

Suggested Improvement

Option A: Add Warning boxes to affected pages

In headless.md, add after the "Basic usage" section:

<Warning>
  **Security note**: Trust verification is disabled in non-interactive mode (`-p`). First-time codebase runs and new MCP servers will NOT prompt for trust verification. Only use `-p` mode with trusted codebases and MCP configurations.
</Warning>

In cli-reference.md, update the -p flag row:

| `--print`, `-p` | Print response without interactive mode. **Note: Trust verification is disabled** (see [security implications](https://code.claude.com/en/security#additional-safeguards)) | `claude -p "query"` |

Option B: Elevate the security note

In security.md, convert the sub-bullet to a prominent Warning:

<Warning>
  **Non-interactive mode security**: When running with the `-p` flag, trust verification is disabled. First-time codebase runs and new MCP servers will execute without trust prompts. Use caution when running Claude Code programmatically on untrusted repositories.
</Warning>

Impact

High - Prevents users from using a feature

Additional Context

Affected files in documentation mirror

| File | Issue |
|------|-------|
| code-claude/docs/en/security.md | Info present but buried as sub-bullet |
| code-claude/docs/en/headless.md | Missing entirely |
| code-claude/docs/en/cli-reference.md | No warning in -p flag description |

Security implications

1. Prompt injection risk: Automated pipelines may process untrusted code without trust verification
2. MCP server loading: Untrusted MCP servers can be loaded without user consent in CI/CD
3. First-run bypass: Malicious codebases can skip the "do you trust this codebase?" prompt

Cross-references

• Current models reference: https://docs.anthropic.com/en/docs/about-claude/models
• Security page: https://code.claude.com/en/security
• Headless mode: https://code.claude.com/en/headless
• CLI reference: https://code.claude.com/en/cli-reference

---

Issue validated against documentation mirror on 2026-01-22