Expose --prepend-system-prompt-file (or equivalent) to allow custom identity override

Summary

--append-system-prompt-file exists, but it injects content after the hardcoded identity preamble ("You are Claude Code, Anthropic's official CLI for Claude…"). There is no mechanism to inject content before or in place of that preamble. CLAUDE.md is also injected mid-prompt and cannot reliably override the core identity block.

This matters for anyone building a custom agent persona on top of Claude Code. The current prompt layout means the model always sees "You are Claude Code" first, and any custom identity (e.g., a SOUL.md defining a different agent name, personality, and behavioral rules) is structurally subordinate to it.

Use case

Building persistent AI agents (with their own names, identities, and behavioral constraints) that use Claude Code as a runtime. The agent's identity document (SOUL.md) needs to be the first thing the model sees in the system prompt, not appended after 3,000+ tokens of default Claude Code instructions.

Today's workarounds are all lossy:

• --append-system-prompt-file SOUL.md — identity lands at the bottom, after default persona is established
• CLAUDE.md — injected mid-prompt in # claudeMd section; can say "ignore previous identity" but that's brittle prompt engineering fighting the system prompt
• Custom system prompt via Agent SDK — requires leaving Claude Code's CLI entirely and losing its tooling (hooks, skills, plugins, memory, MCP, etc.)

Proposed solutions (any of these would work)

Option A: --prepend-system-prompt-file <path>
Mirror of --append-system-prompt-file but injects content before the default preamble. Simple, backwards-compatible, composable with --append.

Option B: --replace-system-prompt-identity <path>
Replace only the identity block ("You are Claude Code…" through the end of the "System" section) with the contents of the file. Leaves the rest of the system prompt (tools, environment, instructions) intact.

Option C: settings.json key (systemPromptIdentity or identityFile)
Point to a file that replaces the identity preamble. Persistent across sessions without needing CLI flags. Works for agents that always run with a custom identity.

Option D: CLAUDE.md priority escalation
Allow a CLAUDE.md directive (e.g., <!-- claude:identity -->) that causes its content to be injected before the default preamble rather than in the # claudeMd section.

Why this matters beyond the niche case

• Agent Teams: as multi-agent setups become common, each agent needs its own identity. The current architecture forces all agents to identify as "Claude Code" first.
• Enterprise white-labeling: orgs deploying Claude Code internally may want custom branding/identity without forking the system prompt.
• Behavioral reliability: identity instructions at the top of the system prompt are more reliably followed than those appended later, especially under context pressure.

Related issues

• #45935 / #38286 — --append-system-prompt-file not cumulative (separate bug, but same surface area)
• #39583 / #38938 — system prompt efficiency directives overriding CLAUDE.md preferences (symptom of the same structural problem: default prompt takes precedence over user customization)
• #43352 — system prompt granting permission to override user requests

Environment

• Claude Code v2.1.105+
• macOS / Darwin 24.3.0