docs/references/ai/agent-prompt-layers.md
Agent conversations combine several independently stored prompt sources. They are not synchronized because each source has a different scope and lifecycle.
| Priority | Source | Storage | Scope and lifecycle |
|---|---|---|---|
| 1 | Platform and runtime safety constraints | Application and runtime code | Non-overridable runtime policy; materialized with the connection |
| 2 | Agent System Prompt | agent.instructions in Agent configuration | Authoritative role, goals, capability scope, and behavioral constraints; applies from the next fresh model turn after save |
| 3 | Workspace Instructions | <workspace>/system.md plus runtime-native CLAUDE.md / scoped AGENTS.md context | Workspace-local guidance; an explicit system.md replaces the runtime's native base, including when the file is empty |
| 4 | Agent Persona | <agent-data>/SOUL.md | Persistent name, personality, tone, and communication style across workspaces |
Lower-priority guidance still applies when it does not conflict with a higher-priority source. USER.md, memory/FACT.md, journal entries, and retrieved knowledge are context rather than behavioral authority. This hierarchy is injected only when agent.instructions resolves to non-blank content. Agents without a configured System Prompt retain the legacy role-discovery and role-bearing SOUL.md fallback instead of receiving a hierarchy that points to a missing authority source.
The hierarchy is an explicit instruction contract provided to the model, not a deterministic enforcement or security boundary; application and runtime hooks independently enforce hard runtime and tool-safety constraints. Prompt composition still preserves existing workspace and SOUL.md content verbatim. This change does not structurally remove legacy role text, so resolving conflicts remains model-mediated rather than guaranteed.
Assistant and Agent editors both call the field System Prompt and expose variable insertion, resolved preview, generation, and polishing. Their storage and runtimes remain different: Assistant stores assistant.prompt; Agent stores agent.instructions. The editor's resolved preview is display-only: unresolved source text is persisted, and Main resolves it independently when materializing a connection.
For Agents, buildAgentRuntimePrompt resolves a non-blank configured System
Prompt and wraps it in <agent_instructions> for every registered runtime.
Workspace and persona content remain present, but they cannot redefine the
Agent role. When the configured value is blank, neither that wrapper nor the
precedence hierarchy is injected.
An explicit system.md selects a custom base across runtimes; an empty file
deliberately selects an empty custom base. Each driver maps the common
{ base, append } result into its SDK: Claude Code uses its preset/custom base,
Pi uses system/append overrides, and DSH maps it into its composition. Runtime-
native workspace context can still load according to that driver's trust
boundary. Cherry-owned persona, memory, workspace-path, security, citation,
artifact, and language guidance is appended independently of the base.
SOUL.md is not a replica of Agent configuration. With a configured System Prompt, bootstrap may create or edit it only to record the Agent's name, personality, tone, and communication style; it must not discover, restate, or replace the configured role. Without a configured System Prompt, bootstrap preserves the legacy flow and may discover and store the role in SOUL.md. Bootstrap records user context in USER.md in both modes.
Saving Agent configuration never writes SOUL.md, and editing SOUL.md never writes agent.instructions. Existing custom files are preserved.
Saving agent.instructions invalidates the connection rebuild signature. Changes to app.user.name and the Agent's resolved primary model name also invalidate it because they affect {{username}} and {{model_name}}. An idle stale connection closes eagerly; a live response finishes with its captured prompt; the next fresh model turn rebuilds and sees the saved value.
System Prompt variables are resolved by buildAgentRuntimePrompt when an Agent
runtime connection is created or rebuilt. {{model_name}} uses the Agent's
resolved primary model name. Volatile values such as {{date}}, {{time}},
and {{datetime}} remain connection snapshots until another rebuild; they do
not force a rebuild every turn.
src/main/ai/runtime/agentPrompt.ts owns shared precedence, variable materialization, and the { base, append } contract.src/main/ai/runtime/{claudeCode,pi,dsh}/ map that contract into their SDK/composition.src/main/ai/agents/prompt.ts owns workspace base selection and persona/memory context.src/main/ai/agents/bootstrap.ts owns first-run persona and user onboarding guidance.src/main/ai/agentSession/AgentSessionRuntimeService.ts owns next-turn connection reconciliation.