Split DeveloperInstructions into individual fragments. (#18813)

Split DeveloperInstructions into individual fragments.
2026-07-01 00:31:56 +08:00 · 2026-04-21 10:22:36 -07:00
parent 5fe767e8e1
commit 2a226096f6
55 changed files with 1410 additions and 1058 deletions
@@ -0,0 +1,24 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct ApprovedCommandPrefixSaved {
+    prefixes: String,
+}
+
+impl ApprovedCommandPrefixSaved {
+    pub(crate) fn new(prefixes: impl Into<String>) -> Self {
+        Self {
+            prefixes: prefixes.into(),
+        }
+    }
+}
+
+impl ContextualUserFragment for ApprovedCommandPrefixSaved {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        format!("Approved command prefix saved:\n{}", self.prefixes)
+    }
+}
@@ -0,0 +1,30 @@
+use codex_app_server_protocol::AppInfo;
+use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
+use codex_protocol::protocol::APPS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::APPS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AppsInstructions;
+
+impl AppsInstructions {
+    pub(crate) fn from_connectors(connectors: &[AppInfo]) -> Option<Self> {
+        connectors
+            .iter()
+            .any(|connector| connector.is_accessible && connector.is_enabled)
+            .then_some(Self)
+    }
+}
+
+impl ContextualUserFragment for AppsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = APPS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = APPS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        format!(
+            "\n## Apps (Connectors)\nApps (Connectors) can be explicitly triggered in user messages in the format `[$app-name](app://{{connector_id}})`. Apps can also be implicitly triggered as long as the context suggests usage of available apps.\nAn app is equivalent to a set of MCP tools within the `{CODEX_APPS_MCP_SERVER_NAME}` MCP.\nAn installed app's MCP tools are either provided to you already, or can be lazy-loaded through the `tool_search` tool. If `tool_search` is available, the apps that are searchable by `tools_search` will be listed by it.\nDo not additionally call list_mcp_resources or list_mcp_resource_templates for apps.\n"
+        )
+    }
+}
@@ -0,0 +1,58 @@
+use codex_plugin::PluginCapabilitySummary;
+use codex_protocol::protocol::PLUGINS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::PLUGINS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct AvailablePluginsInstructions {
+    plugins: Vec<PluginCapabilitySummary>,
+}
+
+impl AvailablePluginsInstructions {
+    pub(crate) fn from_plugins(plugins: &[PluginCapabilitySummary]) -> Option<Self> {
+        if plugins.is_empty() {
+            return None;
+        }
+
+        Some(Self {
+            plugins: plugins.to_vec(),
+        })
+    }
+}
+
+impl ContextualUserFragment for AvailablePluginsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = PLUGINS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = PLUGINS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        let mut lines = vec![
+            "## Plugins".to_string(),
+            "A plugin is a local bundle of skills, MCP servers, and apps. Below is the list of plugins that are enabled and available in this session.".to_string(),
+            "### Available plugins".to_string(),
+        ];
+
+        lines.extend(
+            self.plugins
+                .iter()
+                .map(|plugin| match plugin.description.as_deref() {
+                    Some(description) => format!("- `{}`: {description}", plugin.display_name),
+                    None => format!("- `{}`", plugin.display_name),
+                }),
+        );
+
+        lines.push("### How to use plugins".to_string());
+        lines.push(
+            r###"- Discovery: The list above is the plugins available in this session.
+- Skill naming: If a plugin contributes skills, those skill entries are prefixed with `plugin_name:` in the Skills list.
+- Trigger rules: If the user explicitly names a plugin, prefer capabilities associated with that plugin for that turn.
+- Relationship to capabilities: Plugins are not invoked directly. Use their underlying skills, MCP tools, and app tools to help solve the task.
+- Preference: When a relevant plugin is available, prefer using capabilities associated with that plugin over standalone capabilities that provide similar functionality.
+- Missing/blocked: If the user requests a plugin that is not listed above, or the plugin does not have relevant callable capabilities for the task, say so briefly and continue with the best fallback."###
+                .to_string(),
+        );
+
+        format!("\n{}\n", lines.join("\n"))
+    }
+}
@@ -0,0 +1,56 @@
+use codex_core_skills::AvailableSkills;
+use codex_protocol::protocol::SKILLS_INSTRUCTIONS_CLOSE_TAG;
+use codex_protocol::protocol::SKILLS_INSTRUCTIONS_OPEN_TAG;
+
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AvailableSkillsInstructions {
+    skill_lines: Vec<String>,
+}
+
+impl From<AvailableSkills> for AvailableSkillsInstructions {
+    fn from(available_skills: AvailableSkills) -> Self {
+        Self {
+            skill_lines: available_skills.skill_lines,
+        }
+    }
+}
+
+impl ContextualUserFragment for AvailableSkillsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = SKILLS_INSTRUCTIONS_OPEN_TAG;
+    const END_MARKER: &'static str = SKILLS_INSTRUCTIONS_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        let mut lines: Vec<String> = Vec::new();
+        lines.push("## Skills".to_string());
+        lines.push("A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.".to_string());
+        lines.push("### Available skills".to_string());
+        lines.extend(self.skill_lines.iter().cloned());
+
+        lines.push("### How to use skills".to_string());
+        lines.push(
+            r###"- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
+- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
+- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
+- How to use a skill (progressive disclosure):
+  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
+  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.
+  3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
+  4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
+  5) If `assets/` or templates exist, reuse them instead of recreating from scratch.
+- Coordination and sequencing:
+  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
+  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
+- Context hygiene:
+  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
+  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
+  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
+- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue."###
+                .to_string(),
+        );
+
+        format!("\n{}\n", lines.join("\n"))
+    }
+}
@@ -0,0 +1,32 @@
+use super::ContextualUserFragment;
+use codex_protocol::config_types::CollaborationMode;
+use codex_protocol::protocol::COLLABORATION_MODE_CLOSE_TAG;
+use codex_protocol::protocol::COLLABORATION_MODE_OPEN_TAG;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct CollaborationModeInstructions {
+    instructions: String,
+}
+
+impl CollaborationModeInstructions {
+    pub(crate) fn from_collaboration_mode(collaboration_mode: &CollaborationMode) -> Option<Self> {
+        collaboration_mode
+            .settings
+            .developer_instructions
+            .as_ref()
+            .filter(|instructions| !instructions.is_empty())
+            .map(|instructions| Self {
+                instructions: instructions.clone(),
+            })
+    }
+}
+
+impl ContextualUserFragment for CollaborationModeInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = COLLABORATION_MODE_OPEN_TAG;
+    const END_MARKER: &'static str = COLLABORATION_MODE_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        self.instructions.clone()
+    }
+}
@@ -200,7 +200,7 @@ impl ContextualUserFragment for EnvironmentContext {
            lines.extend(subagents.lines().map(|line| format!("    {line}")));
            lines.push("  </subagents>".to_string());
        }
-        format!("\n{}", lines.join("\n"))
+        format!("\n{}\n", lines.join("\n"))
    }
 }

@@ -28,13 +28,16 @@ impl<T: ContextualUserFragment> FragmentRegistration for FragmentRegistrationPro
    }
 }

-/// Context payload that is injected as a user-authored message fragment.
+/// Context payload that is injected as a message fragment.
 ///
-/// Implementations own the response role, start/end markers used to recognize
-/// the fragment, and provide the fragment body appended directly after the
-/// start marker. The default helpers wrap that body and convert it into the
-/// response item shape expected by model input assembly.
-pub(crate) trait ContextualUserFragment {
+/// Implementations own the response role and provide the exact fragment body.
+/// Marked fragments also provide start/end markers used to recognize injected
+/// context later. `render()` concatenates markers and body without adding
+/// separators, so implementations should include any whitespace they need
+/// between tags in `body()`. Unmarked fragments should leave both markers empty,
+/// in which case the default helpers render only the body and never match
+/// arbitrary text.
+pub trait ContextualUserFragment {
    const ROLE: &'static str;
    const START_MARKER: &'static str;
    const END_MARKER: &'static str;
@@ -45,6 +48,10 @@ pub(crate) trait ContextualUserFragment {
    where
        Self: Sized,
    {
+        if Self::START_MARKER.is_empty() || Self::END_MARKER.is_empty() {
+            return false;
+        }
+
        let trimmed = text.trim_start();
        let starts_with_marker = trimmed
            .get(..Self::START_MARKER.len())
@@ -57,12 +64,11 @@ pub(crate) trait ContextualUserFragment {
    }

    fn render(&self) -> String {
-        format!(
-            "{}{}\n{}",
-            Self::START_MARKER,
-            self.body(),
-            Self::END_MARKER
-        )
+        if Self::START_MARKER.is_empty() && Self::END_MARKER.is_empty() {
+            return self.body();
+        }
+
+        format!("{}{}{}", Self::START_MARKER, self.body(), Self::END_MARKER)
    }

    fn into(self) -> ResponseItem
@@ -0,0 +1,21 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct GuardianFollowupReviewReminder;
+
+impl ContextualUserFragment for GuardianFollowupReviewReminder {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        concat!(
+            "Use prior reviews as context, not binding precedent. ",
+            "Follow the Workspace Policy. ",
+            "If the user explicitly approves a previously rejected action after being informed of the ",
+            "concrete risks, set outcome to \"allow\" unless the policy explicitly disallows user ",
+            "overwrites in such cases."
+        )
+        .to_string()
+    }
+}
@@ -0,0 +1,22 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct HookAdditionalContext {
+    text: String,
+}
+
+impl HookAdditionalContext {
+    pub(crate) fn new(text: impl Into<String>) -> Self {
+        Self { text: text.into() }
+    }
+}
+
+impl ContextualUserFragment for HookAdditionalContext {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        self.text.clone()
+    }
+}
@@ -0,0 +1,30 @@
+use super::ContextualUserFragment;
+use std::fmt::Display;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct ImageGenerationInstructions {
+    image_output_dir: String,
+    image_output_path: String,
+}
+
+impl ImageGenerationInstructions {
+    pub(crate) fn new(image_output_dir: impl Display, image_output_path: impl Display) -> Self {
+        Self {
+            image_output_dir: image_output_dir.to_string(),
+            image_output_path: image_output_path.to_string(),
+        }
+    }
+}
+
+impl ContextualUserFragment for ImageGenerationInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        format!(
+            "Generated images are saved to {} as {} by default.\nIf you need to use a generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it.",
+            self.image_output_dir, self.image_output_path
+        )
+    }
+}
@@ -1,20 +1,56 @@
+//! Context fragments injected into model input.
+
+mod approved_command_prefix_saved;
+mod apps_instructions;
+mod available_plugins_instructions;
+mod available_skills_instructions;
+mod collaboration_mode_instructions;
 mod contextual_user_message;
 mod environment_context;
 mod fragment;
+mod guardian_followup_review_reminder;
+mod hook_additional_context;
+mod image_generation_instructions;
+mod model_switch_instructions;
+mod network_rule_saved;
+mod permissions_instructions;
+mod personality_spec_instructions;
+mod plugin_instructions;
+mod realtime_end_instructions;
+mod realtime_start_instructions;
+mod realtime_start_with_instructions;
 mod skill_instructions;
+mod spawn_agent_instructions;
 mod subagent_notification;
 mod turn_aborted;
 mod user_instructions;
 mod user_shell_command;

+pub(crate) use approved_command_prefix_saved::ApprovedCommandPrefixSaved;
+pub(crate) use apps_instructions::AppsInstructions;
+pub(crate) use available_plugins_instructions::AvailablePluginsInstructions;
+pub(crate) use available_skills_instructions::AvailableSkillsInstructions;
+pub(crate) use collaboration_mode_instructions::CollaborationModeInstructions;
 pub(crate) use contextual_user_message::is_contextual_user_fragment;
 pub(crate) use contextual_user_message::is_memory_excluded_contextual_user_fragment;
 pub(crate) use contextual_user_message::parse_visible_hook_prompt_message;
 pub(crate) use environment_context::EnvironmentContext;
-pub(crate) use fragment::ContextualUserFragment;
+pub use fragment::ContextualUserFragment;
 pub(crate) use fragment::FragmentRegistration;
 pub(crate) use fragment::FragmentRegistrationProxy;
+pub(crate) use guardian_followup_review_reminder::GuardianFollowupReviewReminder;
+pub(crate) use hook_additional_context::HookAdditionalContext;
+pub(crate) use image_generation_instructions::ImageGenerationInstructions;
+pub(crate) use model_switch_instructions::ModelSwitchInstructions;
+pub(crate) use network_rule_saved::NetworkRuleSaved;
+pub use permissions_instructions::PermissionsInstructions;
+pub(crate) use personality_spec_instructions::PersonalitySpecInstructions;
+pub(crate) use plugin_instructions::PluginInstructions;
+pub(crate) use realtime_end_instructions::RealtimeEndInstructions;
+pub(crate) use realtime_start_instructions::RealtimeStartInstructions;
+pub(crate) use realtime_start_with_instructions::RealtimeStartWithInstructions;
 pub(crate) use skill_instructions::SkillInstructions;
+pub(crate) use spawn_agent_instructions::SpawnAgentInstructions;
 pub(crate) use subagent_notification::SubagentNotification;
 pub(crate) use turn_aborted::TurnAborted;
 pub(crate) use user_instructions::UserInstructions;
@@ -0,0 +1,27 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct ModelSwitchInstructions {
+    model_instructions: String,
+}
+
+impl ModelSwitchInstructions {
+    pub(crate) fn new(model_instructions: impl Into<String>) -> Self {
+        Self {
+            model_instructions: model_instructions.into(),
+        }
+    }
+}
+
+impl ContextualUserFragment for ModelSwitchInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "<model_switch>";
+    const END_MARKER: &'static str = "</model_switch>";
+
+    fn body(&self) -> String {
+        format!(
+            "\nThe user was previously using a different model. Please continue the conversation according to the following instructions:\n\n{}\n",
+            self.model_instructions
+        )
+    }
+}
@@ -0,0 +1,35 @@
+use super::ContextualUserFragment;
+use codex_protocol::approvals::NetworkPolicyAmendment;
+use codex_protocol::approvals::NetworkPolicyRuleAction;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct NetworkRuleSaved {
+    action: NetworkPolicyRuleAction,
+    host: String,
+}
+
+impl NetworkRuleSaved {
+    pub(crate) fn new(amendment: &NetworkPolicyAmendment) -> Self {
+        Self {
+            action: amendment.action,
+            host: amendment.host.clone(),
+        }
+    }
+}
+
+impl ContextualUserFragment for NetworkRuleSaved {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        let (action, list_name) = match self.action {
+            NetworkPolicyRuleAction::Allow => ("Allowed", "allowlist"),
+            NetworkPolicyRuleAction::Deny => ("Denied", "denylist"),
+        };
+        format!(
+            "{action} network rule saved in execpolicy ({list_name}): {}",
+            self.host
+        )
+    }
+}
@@ -0,0 +1,316 @@
+use super::ContextualUserFragment;
+use codex_execpolicy::Policy;
+use codex_protocol::config_types::ApprovalsReviewer;
+use codex_protocol::config_types::SandboxMode;
+use codex_protocol::models::format_allow_prefixes;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::GranularApprovalConfig;
+use codex_protocol::protocol::NetworkAccess;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::WritableRoot;
+use codex_utils_template::Template;
+use std::path::Path;
+use std::sync::LazyLock;
+
+const APPROVAL_POLICY_NEVER: &str = include_str!("prompts/permissions/approval_policy/never.md");
+const APPROVAL_POLICY_UNLESS_TRUSTED: &str =
+    include_str!("prompts/permissions/approval_policy/unless_trusted.md");
+const APPROVAL_POLICY_ON_FAILURE: &str =
+    include_str!("prompts/permissions/approval_policy/on_failure.md");
+const APPROVAL_POLICY_ON_REQUEST_RULE: &str =
+    include_str!("prompts/permissions/approval_policy/on_request.md");
+const APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION: &str =
+    include_str!("prompts/permissions/approval_policy/on_request_rule_request_permission.md");
+const AUTO_REVIEW_APPROVAL_SUFFIX: &str = "`approvals_reviewer` is `auto_review`: Sandbox escalations with require_escalated will be reviewed for compliance with the policy. If a rejection happens, you should proceed only with a materially safer alternative, or inform the user of the risk and send a final message to ask for approval.";
+
+const SANDBOX_MODE_DANGER_FULL_ACCESS: &str =
+    include_str!("prompts/permissions/sandbox_mode/danger_full_access.md");
+const SANDBOX_MODE_WORKSPACE_WRITE: &str =
+    include_str!("prompts/permissions/sandbox_mode/workspace_write.md");
+const SANDBOX_MODE_READ_ONLY: &str = include_str!("prompts/permissions/sandbox_mode/read_only.md");
+
+static SANDBOX_MODE_DANGER_FULL_ACCESS_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_DANGER_FULL_ACCESS.trim_end())
+        .unwrap_or_else(|err| panic!("danger-full-access sandbox template must parse: {err}"))
+});
+static SANDBOX_MODE_WORKSPACE_WRITE_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_WORKSPACE_WRITE.trim_end())
+        .unwrap_or_else(|err| panic!("workspace-write sandbox template must parse: {err}"))
+});
+static SANDBOX_MODE_READ_ONLY_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_READ_ONLY.trim_end())
+        .unwrap_or_else(|err| panic!("read-only sandbox template must parse: {err}"))
+});
+
+struct PermissionsPromptConfig<'a> {
+    approval_policy: AskForApproval,
+    approvals_reviewer: ApprovalsReviewer,
+    exec_policy: &'a Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+/// Developer instructions that describe the active sandbox and approval policy.
+pub struct PermissionsInstructions {
+    text: String,
+}
+
+impl PermissionsInstructions {
+    /// Builds permissions instructions from the effective sandbox and approval policy.
+    pub fn from_policy(
+        sandbox_policy: &SandboxPolicy,
+        approval_policy: AskForApproval,
+        approvals_reviewer: ApprovalsReviewer,
+        exec_policy: &Policy,
+        cwd: &Path,
+        exec_permission_approvals_enabled: bool,
+        request_permissions_tool_enabled: bool,
+    ) -> Self {
+        let network_access = if sandbox_policy.has_full_network_access() {
+            NetworkAccess::Enabled
+        } else {
+            NetworkAccess::Restricted
+        };
+
+        let (sandbox_mode, writable_roots) = match sandbox_policy {
+            SandboxPolicy::DangerFullAccess => (SandboxMode::DangerFullAccess, None),
+            SandboxPolicy::ReadOnly { .. } => (SandboxMode::ReadOnly, None),
+            SandboxPolicy::ExternalSandbox { .. } => (SandboxMode::DangerFullAccess, None),
+            SandboxPolicy::WorkspaceWrite { .. } => {
+                let roots = sandbox_policy.get_writable_roots_with_cwd(cwd);
+                (SandboxMode::WorkspaceWrite, Some(roots))
+            }
+        };
+
+        Self::from_permissions_with_network(
+            sandbox_mode,
+            network_access,
+            PermissionsPromptConfig {
+                approval_policy,
+                approvals_reviewer,
+                exec_policy,
+                exec_permission_approvals_enabled,
+                request_permissions_tool_enabled,
+            },
+            writable_roots,
+        )
+    }
+
+    fn from_permissions_with_network(
+        sandbox_mode: SandboxMode,
+        network_access: NetworkAccess,
+        config: PermissionsPromptConfig<'_>,
+        writable_roots: Option<Vec<WritableRoot>>,
+    ) -> Self {
+        let mut text = String::new();
+        append_section(&mut text, &sandbox_text(sandbox_mode, network_access));
+        append_section(
+            &mut text,
+            &approval_text(
+                config.approval_policy,
+                config.approvals_reviewer,
+                config.exec_policy,
+                config.exec_permission_approvals_enabled,
+                config.request_permissions_tool_enabled,
+            ),
+        );
+        if let Some(writable_roots) = writable_roots_text(writable_roots) {
+            append_section(&mut text, &writable_roots);
+        }
+        if !text.ends_with('\n') {
+            text.push('\n');
+        }
+        Self { text }
+    }
+}
+
+impl ContextualUserFragment for PermissionsInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "<permissions instructions>";
+    const END_MARKER: &'static str = "</permissions instructions>";
+
+    fn body(&self) -> String {
+        self.text.clone()
+    }
+}
+
+fn append_section(text: &mut String, section: &str) {
+    if !text.ends_with('\n') {
+        text.push('\n');
+    }
+    text.push_str(section);
+}
+
+fn approval_text(
+    approval_policy: AskForApproval,
+    approvals_reviewer: ApprovalsReviewer,
+    exec_policy: &Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+) -> String {
+    let with_request_permissions_tool = |text: &str| {
+        if request_permissions_tool_enabled {
+            format!("{text}\n\n{}", request_permissions_tool_prompt_section())
+        } else {
+            text.to_string()
+        }
+    };
+    let on_request_instructions = || {
+        let on_request_rule = if exec_permission_approvals_enabled {
+            APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string()
+        } else {
+            APPROVAL_POLICY_ON_REQUEST_RULE.to_string()
+        };
+        let mut sections = vec![on_request_rule];
+        if request_permissions_tool_enabled {
+            sections.push(request_permissions_tool_prompt_section().to_string());
+        }
+        if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
+            sections.push(format!(
+                "## Approved command prefixes\nThe following prefix rules have already been approved: {prefixes}"
+            ));
+        }
+        sections.join("\n\n")
+    };
+    let text = match approval_policy {
+        AskForApproval::Never => APPROVAL_POLICY_NEVER.to_string(),
+        AskForApproval::UnlessTrusted => {
+            with_request_permissions_tool(APPROVAL_POLICY_UNLESS_TRUSTED)
+        }
+        AskForApproval::OnFailure => with_request_permissions_tool(APPROVAL_POLICY_ON_FAILURE),
+        AskForApproval::OnRequest => on_request_instructions(),
+        AskForApproval::Granular(granular_config) => granular_instructions(
+            granular_config,
+            exec_policy,
+            exec_permission_approvals_enabled,
+            request_permissions_tool_enabled,
+        ),
+    };
+
+    if approvals_reviewer == ApprovalsReviewer::GuardianSubagent
+        && approval_policy != AskForApproval::Never
+    {
+        format!("{text}\n\n{AUTO_REVIEW_APPROVAL_SUFFIX}")
+    } else {
+        text
+    }
+}
+
+fn sandbox_text(mode: SandboxMode, network_access: NetworkAccess) -> String {
+    let template = match mode {
+        SandboxMode::DangerFullAccess => &*SANDBOX_MODE_DANGER_FULL_ACCESS_TEMPLATE,
+        SandboxMode::WorkspaceWrite => &*SANDBOX_MODE_WORKSPACE_WRITE_TEMPLATE,
+        SandboxMode::ReadOnly => &*SANDBOX_MODE_READ_ONLY_TEMPLATE,
+    };
+    let network_access = network_access.to_string();
+    template
+        .render([("network_access", network_access.as_str())])
+        .unwrap_or_else(|err| panic!("sandbox template must render: {err}"))
+}
+
+fn writable_roots_text(writable_roots: Option<Vec<WritableRoot>>) -> Option<String> {
+    let roots = writable_roots?;
+    if roots.is_empty() {
+        return None;
+    }
+
+    let roots_list: Vec<String> = roots
+        .iter()
+        .map(|r| format!("`{}`", r.root.to_string_lossy()))
+        .collect();
+    Some(if roots_list.len() == 1 {
+        format!(" The writable root is {}.", roots_list[0])
+    } else {
+        format!(" The writable roots are {}.", roots_list.join(", "))
+    })
+}
+
+fn approved_command_prefixes_text(exec_policy: &Policy) -> Option<String> {
+    format_allow_prefixes(exec_policy.get_allowed_prefixes())
+        .filter(|prefixes| !prefixes.is_empty())
+}
+
+fn granular_prompt_intro_text() -> &'static str {
+    "# Approval Requests\n\nApproval policy is `granular`. Categories set to `false` are automatically rejected instead of prompting the user."
+}
+
+fn request_permissions_tool_prompt_section() -> &'static str {
+    "# request_permissions Tool\n\nThe built-in `request_permissions` tool is available in this session. Invoke it when you need to request additional `network` or `file_system` permissions before later shell-like commands need them. Request only the specific permissions required for the task."
+}
+
+fn granular_instructions(
+    granular_config: GranularApprovalConfig,
+    exec_policy: &Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+) -> String {
+    let sandbox_approval_prompts_allowed = granular_config.allows_sandbox_approval();
+    let shell_permission_requests_available =
+        exec_permission_approvals_enabled && sandbox_approval_prompts_allowed;
+    let request_permissions_tool_prompts_allowed =
+        request_permissions_tool_enabled && granular_config.allows_request_permissions();
+    let categories = [
+        Some((
+            granular_config.allows_sandbox_approval(),
+            "`sandbox_approval`",
+        )),
+        Some((granular_config.allows_rules_approval(), "`rules`")),
+        Some((granular_config.allows_skill_approval(), "`skill_approval`")),
+        request_permissions_tool_enabled.then_some((
+            granular_config.allows_request_permissions(),
+            "`request_permissions`",
+        )),
+        Some((
+            granular_config.allows_mcp_elicitations(),
+            "`mcp_elicitations`",
+        )),
+    ];
+    let prompted_categories = categories
+        .iter()
+        .flatten()
+        .filter(|&&(is_allowed, _)| is_allowed)
+        .map(|&(_, category)| format!("- {category}"))
+        .collect::<Vec<_>>();
+    let rejected_categories = categories
+        .iter()
+        .flatten()
+        .filter(|&&(is_allowed, _)| !is_allowed)
+        .map(|&(_, category)| format!("- {category}"))
+        .collect::<Vec<_>>();
+
+    let mut sections = vec![granular_prompt_intro_text().to_string()];
+
+    if !prompted_categories.is_empty() {
+        sections.push(format!(
+            "These approval categories may still prompt the user when needed:\n{}",
+            prompted_categories.join("\n")
+        ));
+    }
+    if !rejected_categories.is_empty() {
+        sections.push(format!(
+            "These approval categories are automatically rejected instead of prompting the user:\n{}",
+            rejected_categories.join("\n")
+        ));
+    }
+
+    if shell_permission_requests_available {
+        sections.push(APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string());
+    }
+
+    if request_permissions_tool_prompts_allowed {
+        sections.push(request_permissions_tool_prompt_section().to_string());
+    }
+
+    if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
+        sections.push(format!(
+            "## Approved command prefixes\nThe following prefix rules have already been approved: {prefixes}"
+        ));
+    }
+
+    sections.join("\n\n")
+}
+
+#[cfg(test)]
+#[path = "permissions_instructions_tests.rs"]
+mod permissions_instructions_tests;
@@ -0,0 +1,412 @@
+use super::*;
+use codex_execpolicy::Decision;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+#[test]
+fn renders_sandbox_mode_text() {
+    assert_eq!(
+        sandbox_text(SandboxMode::WorkspaceWrite, NetworkAccess::Restricted),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `workspace-write`: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. Network access is restricted."
+    );
+
+    assert_eq!(
+        sandbox_text(SandboxMode::ReadOnly, NetworkAccess::Restricted),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `read-only`: The sandbox only permits reading files. Network access is restricted."
+    );
+
+    assert_eq!(
+        sandbox_text(SandboxMode::DangerFullAccess, NetworkAccess::Enabled),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is enabled."
+    );
+}
+
+#[test]
+fn builds_permissions_with_network_access_override() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(
+        text.contains("Network access is enabled."),
+        "expected network access to be enabled in message"
+    );
+    assert!(
+        text.contains("How to request escalation"),
+        "expected approval guidance to be included"
+    );
+}
+
+#[test]
+fn builds_permissions_from_policy() {
+    let policy = SandboxPolicy::WorkspaceWrite {
+        writable_roots: vec![],
+        read_only_access: Default::default(),
+        network_access: true,
+        exclude_tmpdir_env_var: false,
+        exclude_slash_tmp: false,
+    };
+
+    let instructions = PermissionsInstructions::from_policy(
+        &policy,
+        AskForApproval::UnlessTrusted,
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        &PathBuf::from("/tmp"),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+    let text = instructions.body();
+    assert!(text.contains("Network access is enabled."));
+    assert!(text.contains("`approval_policy` is `unless-trusted`"));
+}
+
+#[test]
+fn includes_request_rule_instructions_for_on_request() {
+    let mut exec_policy = Policy::empty();
+    exec_policy
+        .add_prefix_rule(&["git".to_string(), "pull".to_string()], Decision::Allow)
+        .expect("add rule");
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &exec_policy,
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("prefix_rule"));
+    assert!(text.contains("Approved command prefixes"));
+    assert!(text.contains(r#"["git", "pull"]"#));
+}
+
+#[test]
+fn includes_request_permissions_tool_instructions_for_unless_trusted_when_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::UnlessTrusted,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("`approval_policy` is `unless-trusted`"));
+    assert!(text.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn includes_request_permissions_tool_instructions_for_on_failure_when_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnFailure,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("`approval_policy` is `on-failure`"));
+    assert!(text.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn includes_request_permission_rule_instructions_for_on_request_when_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: true,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("with_additional_permissions"));
+    assert!(text.contains("additional_permissions"));
+}
+
+#[test]
+fn includes_request_permissions_tool_instructions_for_on_request_when_tool_is_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("# request_permissions Tool"));
+    assert!(text.contains("The built-in `request_permissions` tool is available in this session."));
+}
+
+#[test]
+fn on_request_includes_tool_guidance_alongside_inline_permission_guidance_when_both_exist() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: true,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("with_additional_permissions"));
+    assert!(text.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn guardian_subagent_approvals_append_guardian_specific_guidance() {
+    let text = approval_text(
+        AskForApproval::OnRequest,
+        ApprovalsReviewer::GuardianSubagent,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(text.contains("`approvals_reviewer` is `auto_review`"));
+    assert!(!text.contains("`approvals_reviewer` is `guardian_subagent`"));
+    assert!(text.contains("materially safer alternative"));
+}
+
+#[test]
+fn guardian_subagent_approvals_omit_guardian_specific_guidance_when_approval_is_never() {
+    let text = approval_text(
+        AskForApproval::Never,
+        ApprovalsReviewer::GuardianSubagent,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(!text.contains("`approvals_reviewer` is `auto_review`"));
+    assert!(!text.contains("`approvals_reviewer` is `guardian_subagent`"));
+}
+
+fn granular_categories_section(title: &str, categories: &[&str]) -> String {
+    format!("{title}\n{}", categories.join("\n"))
+}
+
+fn granular_prompt_expected(
+    prompted_categories: &[&str],
+    rejected_categories: &[&str],
+    include_shell_permission_request_instructions: bool,
+    include_request_permissions_tool_section: bool,
+) -> String {
+    let mut sections = vec![granular_prompt_intro_text().to_string()];
+    if !prompted_categories.is_empty() {
+        sections.push(granular_categories_section(
+            "These approval categories may still prompt the user when needed:",
+            prompted_categories,
+        ));
+    }
+    if !rejected_categories.is_empty() {
+        sections.push(granular_categories_section(
+            "These approval categories are automatically rejected instead of prompting the user:",
+            rejected_categories,
+        ));
+    }
+    if include_shell_permission_request_instructions {
+        sections.push(APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string());
+    }
+    if include_request_permissions_tool_section {
+        sections.push(request_permissions_tool_prompt_section().to_string());
+    }
+    sections.join("\n\n")
+}
+
+#[test]
+fn granular_policy_lists_prompted_and_rejected_categories_separately() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: false,
+            rules: true,
+            skill_approval: false,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        [
+            granular_prompt_intro_text().to_string(),
+            granular_categories_section(
+                "These approval categories may still prompt the user when needed:",
+                &["- `rules`"],
+            ),
+            granular_categories_section(
+                "These approval categories are automatically rejected instead of prompting the user:",
+                &[
+                    "- `sandbox_approval`",
+                    "- `skill_approval`",
+                    "- `mcp_elicitations`",
+                ],
+            ),
+        ]
+        .join("\n\n")
+    );
+}
+
+#[test]
+fn granular_policy_includes_command_permission_instructions_when_sandbox_approval_can_prompt() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        granular_prompt_expected(
+            &[
+                "- `sandbox_approval`",
+                "- `rules`",
+                "- `skill_approval`",
+                "- `mcp_elicitations`",
+            ],
+            &[],
+            /*include_shell_permission_request_instructions*/ true,
+            /*include_request_permissions_tool_section*/ false,
+        )
+    );
+}
+
+#[test]
+fn granular_policy_omits_shell_permission_instructions_when_inline_requests_are_disabled() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        granular_prompt_expected(
+            &[
+                "- `sandbox_approval`",
+                "- `rules`",
+                "- `skill_approval`",
+                "- `mcp_elicitations`",
+            ],
+            &[],
+            /*include_shell_permission_request_instructions*/ false,
+            /*include_request_permissions_tool_section*/ false,
+        )
+    );
+}
+
+#[test]
+fn granular_policy_includes_request_permissions_tool_only_when_that_prompt_can_still_fire() {
+    let allowed = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ true,
+    );
+    assert!(allowed.contains("# request_permissions Tool"));
+
+    let rejected = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: false,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ true,
+    );
+    assert!(!rejected.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn granular_policy_lists_request_permissions_category_without_tool_section_when_tool_unavailable() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: false,
+            rules: false,
+            skill_approval: false,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }),
+        ApprovalsReviewer::User,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(!text.contains("- `request_permissions`"));
+    assert!(!text.contains("# request_permissions Tool"));
+}
@@ -0,0 +1,25 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct PersonalitySpecInstructions {
+    spec: String,
+}
+
+impl PersonalitySpecInstructions {
+    pub(crate) fn new(spec: impl Into<String>) -> Self {
+        Self { spec: spec.into() }
+    }
+}
+
+impl ContextualUserFragment for PersonalitySpecInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "<personality_spec>";
+    const END_MARKER: &'static str = "</personality_spec>";
+
+    fn body(&self) -> String {
+        format!(
+            " The user has requested a new communication style. Future messages should adhere to the following personality: \n{} ",
+            self.spec
+        )
+    }
+}
@@ -0,0 +1,22 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, PartialEq)]
+pub(crate) struct PluginInstructions {
+    text: String,
+}
+
+impl PluginInstructions {
+    pub(crate) fn new(text: impl Into<String>) -> Self {
+        Self { text: text.into() }
+    }
+}
+
+impl ContextualUserFragment for PluginInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "";
+    const END_MARKER: &'static str = "";
+
+    fn body(&self) -> String {
+        self.text.clone()
+    }
+}
@@ -0,0 +1 @@
+Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
@@ -0,0 +1 @@
+Approvals are your mechanism to get user consent to run shell commands without the sandbox. `approval_policy` is `on-failure`: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
@@ -0,0 +1,57 @@
+# Escalation Requests
+
+Commands are run outside the sandbox if they are approved by the user, or match an existing rule that allows it to run unrestricted. The command string is split into independent command segments at shell control operators, including but not limited to:
+
+- Pipes: |
+- Logical operators: &&, ||
+- Command separators: ;
+- Subshell boundaries: (...), $(...)
+
+Each resulting segment is evaluated independently for sandbox restrictions and approval requirements.
+
+Example:
+
+git pull | tee output.txt
+
+This is treated as two command segments:
+
+["git", "pull"]
+
+["tee", "output.txt"]
+
+Commands that use more advanced shell features like redirection (>, >>, <), substitutions ($(...), ...), environment variables (FOO=bar), or wildcard patterns (*, ?) will not be evaluated against rules, to limit the scope of what an approved rule allows.
+
+## How to request escalation
+
+IMPORTANT: To request approval to execute a command that will require escalated privileges:
+
+- Provide the `sandbox_permissions` parameter with the value `"require_escalated"`
+- Include a short question asking the user if they want to allow the action in `justification` parameter. e.g. "Do you want to download and install dependencies for this project?"
+- Optionally suggest a `prefix_rule` - this will be shown to the user with an option to persist the rule approval for future sessions.
+
+If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with "require_escalated". ALWAYS proceed to use the `justification` parameter - do not message the user before requesting approval for the command.
+
+## When to request escalation
+
+While commands are running inside the sandbox, here are some scenarios that will require escalation outside the sandbox:
+
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with `require_escalated`. ALWAYS proceed to use the `sandbox_permissions` and `justification` parameters. do not message the user before requesting approval for the command.
+- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for.
+- Be judicious with escalating, but if completing the user's request requires it, you should do so - don't try and circumvent approvals by using other tools.
+
+## prefix_rule guidance
+
+When choosing a `prefix_rule`, request one that will allow you to fulfill similar requests from the user in the future without re-requesting escalation. It should be categorical and reasonably scoped to similar capabilities. You should rarely pass the entire command into `prefix_rule`.
+
+### Banned prefix_rules 
+Avoid requesting overly broad prefixes that the user would be ill-advised to approve. For example, do not request ["python3"], ["python", "-"], or other similar prefixes that would allow arbitrary scripting.
+NEVER provide a prefix_rule argument for destructive commands like rm.
+NEVER provide a prefix_rule if your command uses a heredoc or herestring. 
+
+### Examples
+Good examples of prefixes:
+- ["npm", "run", "dev"]
+- ["gh", "pr", "check"]
+- ["cargo", "test"]
@@ -0,0 +1,33 @@
+# Permission Requests
+
+Commands may require user approval before execution. Prefer requesting sandboxed additional permissions instead of asking to run fully outside the sandbox.
+
+## Preferred request mode
+
+When you need extra sandboxed permissions for one command, use:
+
+- `sandbox_permissions: "with_additional_permissions"`
+- `additional_permissions` with one or more of:
+  - `network.enabled`: set to `true` to enable network access
+  - `file_system.read`: list of paths that need read access
+  - `file_system.write`: list of paths that need write access
+
+When using the `request_permissions` tool directly, only request `network` and `file_system` permissions.
+
+This keeps execution inside the current sandbox policy, while adding only the requested permissions for that command, unless an exec-policy allow rule applies and authorizes running the command outside the sandbox.
+
+If the command already matches an exec-policy allow rule, the command can be auto-approved without an extra prompt. In that case, exec-policy allow behavior (including any sandbox bypass) takes precedence.
+
+## Escalation Requests
+
+Use full escalation only when sandboxed additional permissions cannot satisfy the task.
+
+- `sandbox_permissions: "require_escalated"`
+- Include `justification` as a short question asking for approval.
+- Optionally include `prefix_rule` to suggest a reusable allow rule.
+
+## Command segmentation reminder
+
+The command string is split into independent command segments at shell control operators, including pipes (`|`), logical operators (`&&`, `||`), command separators (`;`), and subshell boundaries (`(...)`, `$()`).
+
+Each segment is evaluated independently for sandbox restrictions and approval requirements.
@@ -0,0 +1 @@
+ Approvals are your mechanism to get user consent to run shell commands without the sandbox. `approval_policy` is `unless-trusted`: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is {{network_access}}.
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `read-only`: The sandbox only permits reading files. Network access is {{network_access}}.
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `workspace-write`: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. Network access is {{network_access}}.
@@ -0,0 +1,3 @@
+Realtime conversation ended.
+
+Subsequent user input will return to typed text rather than transcript-style text. Do not assume recognition errors or missing punctuation once realtime has ended. Resume normal chat behavior.
@@ -0,0 +1,9 @@
+Realtime conversation started.
+
+You are operating as a backend executor behind an intermediary. The user does not talk to you directly. Any response you produce will be consumed by the intermediary and may be summarized before the user sees it.
+
+When invoked, you receive the latest conversation transcript and any relevant mode or metadata. The intermediary may invoke you even when backend help is not actually needed. Use the transcript to decide whether you should do work. If backend help is unnecessary, avoid verbose responses that add user-visible latency.
+
+When user text is routed from realtime, treat it as a transcript. It may be unpunctuated or contain recognition errors.
+
+- Keep responses concise and action-oriented. Your updates should help the intermediary respond to the user.
@@ -0,0 +1,32 @@
+use super::ContextualUserFragment;
+use codex_protocol::protocol::REALTIME_CONVERSATION_CLOSE_TAG;
+use codex_protocol::protocol::REALTIME_CONVERSATION_OPEN_TAG;
+
+const REALTIME_END_INSTRUCTIONS: &str = include_str!("prompts/realtime/realtime_end.md");
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct RealtimeEndInstructions {
+    reason: String,
+}
+
+impl RealtimeEndInstructions {
+    pub(crate) fn new(reason: impl Into<String>) -> Self {
+        Self {
+            reason: reason.into(),
+        }
+    }
+}
+
+impl ContextualUserFragment for RealtimeEndInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = REALTIME_CONVERSATION_OPEN_TAG;
+    const END_MARKER: &'static str = REALTIME_CONVERSATION_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        format!(
+            "\n{}\n\nReason: {}\n",
+            REALTIME_END_INSTRUCTIONS.trim(),
+            self.reason
+        )
+    }
+}
@@ -0,0 +1,18 @@
+use super::ContextualUserFragment;
+use codex_protocol::protocol::REALTIME_CONVERSATION_CLOSE_TAG;
+use codex_protocol::protocol::REALTIME_CONVERSATION_OPEN_TAG;
+
+const REALTIME_START_INSTRUCTIONS: &str = include_str!("prompts/realtime/realtime_start.md");
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct RealtimeStartInstructions;
+
+impl ContextualUserFragment for RealtimeStartInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = REALTIME_CONVERSATION_OPEN_TAG;
+    const END_MARKER: &'static str = REALTIME_CONVERSATION_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        format!("\n{}\n", REALTIME_START_INSTRUCTIONS.trim())
+    }
+}
@@ -0,0 +1,26 @@
+use super::ContextualUserFragment;
+use codex_protocol::protocol::REALTIME_CONVERSATION_CLOSE_TAG;
+use codex_protocol::protocol::REALTIME_CONVERSATION_OPEN_TAG;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct RealtimeStartWithInstructions {
+    instructions: String,
+}
+
+impl RealtimeStartWithInstructions {
+    pub(crate) fn new(instructions: impl Into<String>) -> Self {
+        Self {
+            instructions: instructions.into(),
+        }
+    }
+}
+
+impl ContextualUserFragment for RealtimeStartWithInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = REALTIME_CONVERSATION_OPEN_TAG;
+    const END_MARKER: &'static str = REALTIME_CONVERSATION_CLOSE_TAG;
+
+    fn body(&self) -> String {
+        format!("\n{}\n", self.instructions)
+    }
+}
@@ -26,7 +26,7 @@ impl ContextualUserFragment for SkillInstructions {

    fn body(&self) -> String {
        format!(
-            "\n<name>{}</name>\n<path>{}</path>\n{}",
+            "\n<name>{}</name>\n<path>{}</path>\n{}\n",
            self.name, self.path, self.contents
        )
    }
@@ -0,0 +1,14 @@
+use super::ContextualUserFragment;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct SpawnAgentInstructions;
+
+impl ContextualUserFragment for SpawnAgentInstructions {
+    const ROLE: &'static str = "developer";
+    const START_MARKER: &'static str = "<spawned_agent_context>";
+    const END_MARKER: &'static str = "</spawned_agent_context>";
+
+    fn body(&self) -> String {
+        "\nYou are a newly spawned agent in a team of agents collaborating to complete a task. You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. You are responsible for returning the response to your assigned task in the final channel. When you give your response, the contents of your response in the final channel will be immediately delivered back to your parent agent. The prior conversation history was forked from your parent agent. Treat the next user message as your assigned task, and use the forked history only as background context.\n".to_string()
+    }
+}
@@ -24,7 +24,7 @@ impl ContextualUserFragment for SubagentNotification {

    fn body(&self) -> String {
        format!(
-            "\n{}",
+            "\n{}\n",
            serde_json::json!({
                "agent_path": &self.agent_reference,
                "status": &self.status,
@@ -21,6 +21,6 @@ impl ContextualUserFragment for TurnAborted {
    const END_MARKER: &'static str = "</turn_aborted>";

    fn body(&self) -> String {
-        format!("\n{}", self.guidance)
+        format!("\n{}\n", self.guidance)
    }
 }
@@ -12,6 +12,6 @@ impl ContextualUserFragment for UserInstructions {
    const END_MARKER: &'static str = "</INSTRUCTIONS>";

    fn body(&self) -> String {
-        format!("{}\n\n<INSTRUCTIONS>\n{}", self.directory, self.text)
+        format!("{}\n\n<INSTRUCTIONS>\n{}\n", self.directory, self.text)
    }
 }
@@ -33,7 +33,7 @@ impl ContextualUserFragment for UserShellCommand {

    fn body(&self) -> String {
        format!(
-            "\n<command>\n{}\n</command>\n<result>\nExit code: {}\nDuration: {:.4} seconds\nOutput:\n{}\n</result>",
+            "\n<command>\n{}\n</command>\n<result>\nExit code: {}\nDuration: {:.4} seconds\nOutput:\n{}\n</result>\n",
            self.command, self.exit_code, self.duration_seconds, self.output,
        )
    }
				`@@ -0,0 +1 @@`
				Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
				`@@ -0,0 +1 @@`
				Approvals are your mechanism to get user consent to run shell commands without the sandbox. `approval_policy` is `on-failure`: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
				`@@ -0,0 +1 @@`
				Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is {{network_access}}.