fix(codex): keep workspace persona session scoped

docs/concepts/system-prompt.md

@@ -141,8 +141,8 @@ layer stack for Telegram direct, Discord group, and heartbeat turns. That stack
 includes a pinned Codex `gpt-5.5` model prompt fixture generated from Codex's
 model catalog/cache shape, the Codex happy-path permission developer text,
 OpenClaw developer instructions, turn-scoped collaboration-mode instructions
-when OpenClaw provides them, user turn input, and references to the dynamic tool
-specs.
+for cron and heartbeat turns when OpenClaw provides them, user turn input, and
+references to the dynamic tool specs.
 
 Refresh the pinned Codex model prompt fixture with
 `pnpm prompt:snapshots:sync-codex-model`. By default, the script looks for
@@ -178,18 +178,19 @@ prompt surface that matches their lifetime:
 - `BOOTSTRAP.md` (only on brand-new workspaces)
 - `MEMORY.md` when present
 
-On the native Codex harness, OpenClaw avoids repeating stable workspace files
+On the native Codex harness, OpenClaw avoids repeating standing workspace files
 in every user turn. Codex loads `AGENTS.md` through its own project-doc
 discovery. `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` are forwarded as
-Codex developer instructions. `HEARTBEAT.md` content is not injected; heartbeat
-turns get a collaboration-mode note pointing to the file when it exists and is
-non-empty. `MEMORY.md` content from the configured agent workspace is not pasted
-into every native Codex turn; when memory tools are available for that workspace,
-Codex turns get a small workspace-memory note and should use `memory_search` or
-`memory_get` when durable memory is relevant. If tools are disabled, memory
-search is unavailable, or the active workspace differs from the agent memory
-workspace, `MEMORY.md` falls back to the normal bounded turn-context path. Active
-`BOOTSTRAP.md` content keeps the normal turn-context role for now.
+Codex thread developer instructions. `HEARTBEAT.md` content is not injected;
+heartbeat turns get a collaboration-mode note pointing to the file when it
+exists and is non-empty. `MEMORY.md` stays out of Codex thread developer
+instructions because it changes often: when memory tools are available for that
+workspace, Codex turns get a small workspace-memory note and should use
+`memory_search` or `memory_get` when durable memory is relevant. If tools are
+disabled, memory search is unavailable, or the active workspace differs from the
+agent memory workspace, `MEMORY.md` falls back to the normal bounded
+turn-context path. Active `BOOTSTRAP.md` content keeps the normal turn-context
+role for now.
 
 On non-Codex harnesses, bootstrap files continue to be composed into the
 OpenClaw prompt according to their existing gates. `HEARTBEAT.md` is omitted on

docs/tools/subagents.md

@@ -639,7 +639,7 @@ still need normal device approval for scope upgrades.
 - Sub-agent announce is **best-effort**. If the gateway restarts, pending "announce back" work is lost.
 - Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.
 - `sessions_spawn` is always non-blocking: it returns `{ status: "accepted", runId, childSessionKey }` immediately.
-- Sub-agent context only injects `AGENTS.md` and `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`). Codex-native subagents follow the same boundary: `TOOLS.md` stays in inherited Codex thread instructions, while parent-only persona, identity, and user files are injected as turn-scoped collaboration instructions so children do not clone them.
+- OpenClaw-managed sub-agent context only injects `AGENTS.md` and `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`). Codex-native subagents inherit the native Codex thread's developer instructions, including `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md`, so the main agent identity stays session-scoped instead of being replayed on every turn. `MEMORY.md` stays in the memory-tool or bounded turn-context path because it changes often.
 - Maximum nesting depth is 5 (`maxSpawnDepth` range: 1–5). Depth 2 is recommended for most use cases.
 - `maxChildrenPerAgent` caps active children per session (default `5`, range `1–20`).
 

extensions/codex/src/app-server/attempt-context.ts

@@ -23,12 +23,13 @@ import {
 } from "./thread-lifecycle.js";
 
 const CODEX_NATIVE_PROJECT_DOC_BASENAMES = new Set(["agents.md"]);
-const CODEX_INHERITED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set(["tools.md"]);
-const CODEX_TURN_SCOPED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set([
+const CODEX_INHERITED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set([
   "identity.md",
   "soul.md",
+  "tools.md",
   "user.md",
 ]);
+const CODEX_TURN_SCOPED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set<string>();
 const CODEX_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES = new Set([
   ...CODEX_INHERITED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES,
   ...CODEX_TURN_SCOPED_WORKSPACE_DEVELOPER_CONTEXT_BASENAMES,
@@ -634,7 +635,7 @@ function renderCodexWorkspaceBootstrapPromptContext(
     return undefined;
   }
   const lines = [
-    "OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. TOOLS.md is provided as inherited Codex developer instructions. SOUL.md, IDENTITY.md, and USER.md are provided as turn-scoped collaboration instructions so native Codex subagents do not inherit them. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.",
+    "OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided as Codex thread developer instructions so standing workspace guidance is not repeated in every turn. MEMORY.md stays in turn-scoped memory context, and HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.",
     "",
     "# Project Context",
     "",

extensions/codex/src/app-server/run-attempt.test.ts

@@ -272,22 +272,20 @@ async function buildCodexTurnContextForTest(
     cwd: workspaceDir,
     appServer: resolveCodexAppServerRuntimeOptions({}),
     promptText: codexTurnPromptText,
-    turnScopedDeveloperInstructions:
-      workspaceBootstrapContext.turnScopedDeveloperInstructions,
+    turnScopedDeveloperInstructions: workspaceBootstrapContext.turnScopedDeveloperInstructions,
     heartbeatCollaborationInstructions:
       workspaceBootstrapContext.heartbeatCollaborationInstructions,
   });
   const collaborationInstructions =
     turnStartParams.collaborationMode?.settings?.developer_instructions ?? "";
-  const inputText =
-    turnStartParams.input?.find((item) => item.type === "text")?.text ?? "";
+  const inputText = turnStartParams.input?.find((item) => item.type === "text")?.text ?? "";
   const systemPromptReport = buildCodexSystemPromptReport({
     attempt: params,
     sessionKey: params.sessionKey ?? params.sessionId,
     workspaceDir,
-    developerInstructions: [threadDeveloperInstructions, collaborationInstructions].join(
-      "\n\n",
-    ),
+    developerInstructions: [threadDeveloperInstructions, collaborationInstructions]
+      .filter((section) => section.trim())
+      .join("\n\n"),
     workspaceBootstrapContext,
     skillsPrompt: "",
     tools: dynamicTools,
@@ -1715,6 +1713,63 @@ describe("runCodexAppServerAttempt", () => {
     ]);
   });
 
+  it("preserves workspace instruction files when before_prompt_build replaces Codex developer instructions", async () => {
+    const beforePromptBuild = vi.fn(async () => ({
+      systemPrompt: "hook replacement codex system",
+    }));
+    initializeGlobalHookRunner(
+      createMockPluginRegistry([{ hookName: "before_prompt_build", handler: beforePromptBuild }]),
+    );
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const workspaceDir = path.join(tempDir, "workspace");
+    const soulGuidance = "Soul guidance that must stay session-scoped.";
+    const identityGuidance = "Identity guidance that must stay session-scoped.";
+    const toolGuidance = "Tool guidance that must stay session-scoped.";
+    const userProfile = "User profile that must stay session-scoped.";
+    const memorySummary = "Memory summary that must stay turn-scoped.";
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await fs.writeFile(path.join(workspaceDir, "SOUL.md"), soulGuidance);
+    await fs.writeFile(path.join(workspaceDir, "IDENTITY.md"), identityGuidance);
+    await fs.writeFile(path.join(workspaceDir, "TOOLS.md"), toolGuidance);
+    await fs.writeFile(path.join(workspaceDir, "USER.md"), userProfile);
+    await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), memorySummary);
+    const harness = createStartedThreadHarness();
+
+    const run = runCodexAppServerAttempt(createParams(sessionFile, workspaceDir));
+    await harness.waitForMethod("turn/start");
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    await harness.completeTurn({ threadId: "thread-1", turnId: "turn-1" });
+    const result = await run;
+
+    expect(beforePromptBuild).toHaveBeenCalledOnce();
+    const threadStart = harness.requests.find((request) => request.method === "thread/start");
+    const threadStartParams = threadStart?.params as { developerInstructions?: string };
+    expect(threadStartParams.developerInstructions).toContain("hook replacement codex system");
+    expect(threadStartParams.developerInstructions).toContain("OpenClaw Workspace Instructions");
+    expect(threadStartParams.developerInstructions).toContain(soulGuidance);
+    expect(threadStartParams.developerInstructions).toContain(identityGuidance);
+    expect(threadStartParams.developerInstructions).toContain(toolGuidance);
+    expect(threadStartParams.developerInstructions).toContain(userProfile);
+    expect(threadStartParams.developerInstructions).not.toContain(memorySummary);
+
+    const turnStart = harness.requests.find((request) => request.method === "turn/start");
+    const turnStartParams = turnStart?.params as {
+      input?: Array<{ text?: string }>;
+      collaborationMode?: { settings?: { developer_instructions?: string | null } };
+    };
+    const collaborationInstructions =
+      turnStartParams.collaborationMode?.settings?.developer_instructions ?? "";
+    expect(collaborationInstructions).not.toContain(soulGuidance);
+    expect(collaborationInstructions).not.toContain(identityGuidance);
+    expect(collaborationInstructions).not.toContain(toolGuidance);
+    expect(collaborationInstructions).not.toContain(userProfile);
+    expect(collaborationInstructions).not.toContain(memorySummary);
+    expect(turnStartParams.input?.[0]?.text ?? "").toContain(memorySummary);
+    expect(result.systemPromptReport?.systemPrompt.chars).toBe(
+      (threadStartParams.developerInstructions ?? "").length,
+    );
+  });
+
   it("projects mirrored history when starting Codex without a native thread binding", async () => {
     const sessionFile = path.join(tempDir, "session.jsonl");
     const workspaceDir = path.join(tempDir, "workspace");
@@ -1873,21 +1928,19 @@ describe("runCodexAppServerAttempt", () => {
     } = await buildCodexTurnContextForTest(params, workspaceDir);
 
     expect(threadDeveloperInstructions).toContain("OpenClaw Workspace Instructions");
-    expect(threadDeveloperInstructions).not.toContain(soulGuidance);
-    expect(threadDeveloperInstructions).not.toContain(identityGuidance);
+    expect(threadDeveloperInstructions).toContain(soulGuidance);
+    expect(threadDeveloperInstructions).toContain(identityGuidance);
     expect(threadDeveloperInstructions).toContain(toolGuidance);
-    expect(threadDeveloperInstructions).not.toContain(userProfile);
+    expect(threadDeveloperInstructions).toContain(userProfile);
     expect(threadDeveloperInstructions).not.toContain(memorySummary);
     expect(threadDeveloperInstructions).not.toContain("Codex loads AGENTS.md natively");
     expect(threadDeveloperInstructions).not.toContain(agentsGuidance);
 
-    expect(collaborationInstructions).toContain("# Collaboration Mode: Default");
-    expect(collaborationInstructions).toContain("request_user_input availability");
-    expect(collaborationInstructions).toContain("OpenClaw Agent Soul");
-    expect(collaborationInstructions).toContain(soulGuidance);
-    expect(collaborationInstructions).toContain(identityGuidance);
+    expect(collaborationInstructions).not.toContain("OpenClaw Agent Soul");
+    expect(collaborationInstructions).not.toContain(soulGuidance);
+    expect(collaborationInstructions).not.toContain(identityGuidance);
     expect(collaborationInstructions).not.toContain(toolGuidance);
-    expect(collaborationInstructions).toContain(userProfile);
+    expect(collaborationInstructions).not.toContain(userProfile);
     expect(collaborationInstructions).not.toContain(memorySummary);
     expect(inputText).toContain("OpenClaw runtime context for this turn:");
     expect(inputText).not.toContain("does not override Codex system/developer instructions");
@@ -1905,7 +1958,9 @@ describe("runCodexAppServerAttempt", () => {
     expect(inputText).not.toContain(agentsGuidance);
     expect(inputText).toContain("Current user request:\nhello");
     expect(systemPromptReport.systemPrompt.chars).toBe(
-      [threadDeveloperInstructions, collaborationInstructions].join("\n\n").length,
+      [threadDeveloperInstructions, collaborationInstructions]
+        .filter((section) => section.trim())
+        .join("\n\n").length,
     );
 
     const fileStats = new Map(
@@ -1973,14 +2028,12 @@ describe("runCodexAppServerAttempt", () => {
       developerInstructions?: string;
     };
     expect(threadStartParams.config?.instructions).toBeUndefined();
-    expect(threadStartParams.developerInstructions).toContain(
-      "OpenClaw Workspace Instructions",
-    );
+    expect(threadStartParams.developerInstructions).toContain("OpenClaw Workspace Instructions");
+    expect(threadStartParams.developerInstructions).toContain(soulGuidance);
+    expect(threadStartParams.developerInstructions).toContain(identityGuidance);
     expect(threadStartParams.developerInstructions).toContain(toolGuidance);
+    expect(threadStartParams.developerInstructions).toContain(userProfile);
     expect(threadStartParams.developerInstructions).not.toContain(agentsGuidance);
-    expect(threadStartParams.developerInstructions).not.toContain(soulGuidance);
-    expect(threadStartParams.developerInstructions).not.toContain(identityGuidance);
-    expect(threadStartParams.developerInstructions).not.toContain(userProfile);
 
     const turnStart = harness.requests.find((request) => request.method === "turn/start");
     const turnStartParams = turnStart?.params as {
@@ -1993,20 +2046,19 @@ describe("runCodexAppServerAttempt", () => {
     };
     const collaborationInstructions =
       turnStartParams.collaborationMode?.settings?.developer_instructions ?? "";
-    expect(collaborationInstructions).toContain("OpenClaw Agent Soul");
-    expect(collaborationInstructions).toContain(soulGuidance);
-    expect(collaborationInstructions).toContain(identityGuidance);
-    expect(collaborationInstructions).toContain(userProfile);
+    expect(collaborationInstructions).not.toContain("OpenClaw Agent Soul");
+    expect(collaborationInstructions).not.toContain(soulGuidance);
+    expect(collaborationInstructions).not.toContain(identityGuidance);
+    expect(collaborationInstructions).not.toContain(userProfile);
     expect(collaborationInstructions).not.toContain(toolGuidance);
 
     const inputText = turnStartParams.input?.[0]?.text ?? "";
     expect(inputText).toBe("hello");
     expect(inputText).not.toContain(agentsGuidance);
     expect(result.systemPromptReport?.systemPrompt.chars).toBe(
-      [
-        threadStartParams.developerInstructions ?? "",
-        collaborationInstructions,
-      ].join("\n\n").length,
+      [threadStartParams.developerInstructions ?? "", collaborationInstructions]
+        .filter((section) => section.trim())
+        .join("\n\n").length,
     );
   });
 

extensions/codex/src/app-server/run-attempt.ts

@@ -640,7 +640,6 @@ export async function runCodexAppServerAttempt(
     buildDeveloperInstructions(params, {
       dynamicTools: toolBridge.availableSpecs,
     }),
-    workspaceBootstrapContext.developerInstructions,
   );
   const openClawPromptContext = buildCodexOpenClawPromptContext({
     params,
@@ -771,9 +770,14 @@ export async function runCodexAppServerAttempt(
       heartbeatCollaborationInstructions:
         workspaceBootstrapContext.heartbeatCollaborationInstructions,
     }).settings.developer_instructions ?? undefined;
-  const buildRenderedCodexDeveloperInstructions = () =>
+  const buildCodexThreadDeveloperInstructions = () =>
     joinPresentSections(
       promptBuild.developerInstructions,
+      workspaceBootstrapContext.developerInstructions,
+    );
+  const buildRenderedCodexDeveloperInstructions = () =>
+    joinPresentSections(
+      buildCodexThreadDeveloperInstructions(),
       buildCodexTurnCollaborationDeveloperInstructions(),
     );
   const systemPromptReport = buildCodexSystemPromptReport({
@@ -871,7 +875,7 @@ export async function runCodexAppServerAttempt(
       effectiveWorkspace,
       effectiveCwd,
       dynamicTools: toolBridge.specs,
-      developerInstructions: promptBuild.developerInstructions,
+      developerInstructions: buildCodexThreadDeveloperInstructions(),
       buildFinalConfigPatch: buildNativeHookRelayFinalConfigPatch,
       bundleMcpThreadConfig,
       nativeToolSurfaceEnabled,
@@ -914,7 +918,7 @@ export async function runCodexAppServerAttempt(
   recordCodexTrajectoryContext(trajectoryRecorder, {
     attempt: params,
     cwd: effectiveCwd,
-    developerInstructions: promptBuild.developerInstructions,
+    developerInstructions: buildRenderedCodexDeveloperInstructions(),
     prompt: codexTurnPromptText,
     tools: toolBridge.availableSpecs,
   });

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/README.md

@@ -8,7 +8,7 @@ These fixtures capture the default OpenAI/Codex happy path for prompt review:
 - Codex harness default coverage for tool-only visible source replies.
 - Telegram direct chat, Discord group chat, and a heartbeat turn with `heartbeat_respond` available through searchable dynamic tools.
 
-The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, OpenClaw developer instructions, turn input with simulated OpenClaw workspace bootstrap runtime context, heartbeat collaboration-mode guidance when applicable, and references to the complete dynamic tool catalog.
+The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, OpenClaw developer instructions, turn input, heartbeat collaboration-mode guidance when applicable, and references to the complete dynamic tool catalog.
 
 The workspace bootstrap simulation includes dummy workspace contents so prompt reviewers can see how OpenClaw routes stable profile files into Codex developer instructions, keeps `MEMORY.md` in turn input, and points heartbeat turns at `HEARTBEAT.md` without inlining it. `AGENTS.md` is intentionally not repeated here because Codex loads it natively.
 

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/discord-group-codex-message-tool.md

@@ -7,7 +7,7 @@
 - Default happy path: the same Codex agent is mentioned in a Discord group/channel while Telegram can remain the user's primary direct interface.
 - Group-visible output must be explicit through the message tool; the model is also told to mostly lurk unless directly addressed or clearly useful.
 - This captures the OpenClaw-owned Codex app-server inputs and reconstructs the stable Codex model/permission layers from committed Codex prompt fixtures.
-- This also simulates Codex workspace bootstrap routing: `TOOLS.md` as inherited developer instructions, `SOUL.md`, `IDENTITY.md`, and `USER.md` as turn-scoped collaboration instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
+- This also simulates Codex workspace bootstrap routing: `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` as Codex developer instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
 
 ## Scenario Metadata
 
@@ -22,12 +22,13 @@
   "runtime": "codex_app_server",
   "simulatedHeartbeatWorkspaceFile": "/tmp/openclaw-happy-path/workspace/HEARTBEAT.md",
   "simulatedWorkspaceBootstrapFiles": ["/tmp/openclaw-happy-path/workspace/MEMORY.md"],
-  "simulatedWorkspaceDeveloperInstructionFiles": ["/tmp/openclaw-happy-path/workspace/TOOLS.md"],
-  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [
-    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+  "simulatedWorkspaceDeveloperInstructionFiles": [
     "/tmp/openclaw-happy-path/workspace/SOUL.md",
-    "/tmp/openclaw-happy-path/workspace/USER.md"
+    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+    "/tmp/openclaw-happy-path/workspace/USER.md",
+    "/tmp/openclaw-happy-path/workspace/TOOLS.md"
   ],
+  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [],
   "sourceReplyDeliveryMode": "message_tool_only",
   "toolSnapshot": "codex-dynamic-tools.discord-group.json",
   "trigger": "user"
@@ -137,7 +138,7 @@
   "collaborationMode": {
     "mode": "default",
     "settings": {
-      "developer_instructions": "# Collaboration Mode: Default\n\nYou are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.\n\nYour active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.\n\n## request_user_input availability\n\nUse the `request_user_input` tool only when it is listed in the available tools for this turn.\n\nIn Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.\n\n## OpenClaw Agent Soul\n\nOpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.\n\n### /tmp/openclaw-happy-path/workspace/IDENTITY.md\n\n<IDENTITY.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/SOUL.md\n\n<SOUL.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/USER.md\n\n<USER.md contents will be here>",
+      "developer_instructions": null,
       "model": "gpt-5.5",
       "reasoning_effort": "medium"
     }
@@ -162,7 +163,7 @@
 
 ## Reconstructed Model-Bound Prompt Layers
 
-This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input with OpenClaw runtime context, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
+This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
 
 ### Layer Metadata
 
@@ -205,8 +206,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
 ```json
 {
   "codexCollaborationModeDeveloperInstructions": {
-    "chars": 1433,
-    "roughTokens": 359
+    "chars": 0,
+    "roughTokens": 0
   },
   "codexModelInstructions": {
     "chars": 21335,
@@ -225,20 +226,20 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 10070
   },
   "openClawDeveloperInstructions": {
-    "chars": 2988,
-    "roughTokens": 747
+    "chars": 3239,
+    "roughTokens": 810
   },
   "totalTextOnly": {
-    "chars": 27700,
-    "roughTokens": 6925
+    "chars": 26525,
+    "roughTokens": 6632
   },
   "totalWithDynamicToolsJson": {
-    "chars": 67979,
-    "roughTokens": 16995
+    "chars": 66804,
+    "roughTokens": 16701
   },
   "userInputText": {
-    "chars": 1629,
-    "roughTokens": 408
+    "chars": 1638,
+    "roughTokens": 410
   }
 }
 ```
@@ -452,6 +453,18 @@ Activation: trigger-only (you are invoked only when explicitly mentioned; recent
 
 OpenClaw loaded these workspace instruction files from the active agent workspace. Internalize and follow them accordingly.
 
+### /tmp/openclaw-happy-path/workspace/SOUL.md
+
+<SOUL.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/IDENTITY.md
+
+<IDENTITY.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/USER.md
+
+<USER.md contents will be here>
+
 ### /tmp/openclaw-happy-path/workspace/TOOLS.md
 
 <TOOLS.md contents will be here>
@@ -459,35 +472,7 @@ OpenClaw loaded these workspace instruction files from the active agent workspac
 
 ### Developer: Codex Collaboration Mode Instructions
 
-```text
-# Collaboration Mode: Default
-
-You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
-
-Your active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.
-
-## request_user_input availability
-
-Use the `request_user_input` tool only when it is listed in the available tools for this turn.
-
-In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
-
-## OpenClaw Agent Soul
-
-OpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.
-
-### /tmp/openclaw-happy-path/workspace/IDENTITY.md
-
-<IDENTITY.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/SOUL.md
-
-<SOUL.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/USER.md
-
-<USER.md contents will be here>
-```
+This turn asks Codex app-server to resolve its built-in Default collaboration-mode instructions at runtime.
 
 ### User: Turn Input Text
 
@@ -497,7 +482,7 @@ Treat this OpenClaw-provided context as supporting project/user reference for th
 
 ## OpenClaw Workspace Context
 
-OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. TOOLS.md is provided as inherited Codex developer instructions. SOUL.md, IDENTITY.md, and USER.md are provided as turn-scoped collaboration instructions so native Codex subagents do not inherit them. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
+OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided as Codex thread developer instructions so standing workspace guidance is not repeated in every turn. MEMORY.md stays in turn-scoped memory context, and HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
 
 # Project Context
 

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md

@@ -7,7 +7,7 @@
 - Default happy path: OpenAI model through the Codex harness/runtime, Telegram direct conversation, and message-tool-only visible replies.
 - A quiet turn is represented by not calling `message(action=send)`; the normal final assistant text is private to OpenClaw/Codex.
 - This captures the OpenClaw-owned Codex app-server inputs and reconstructs the stable Codex model/permission layers from committed Codex prompt fixtures.
-- This also simulates Codex workspace bootstrap routing: `TOOLS.md` as inherited developer instructions, `SOUL.md`, `IDENTITY.md`, and `USER.md` as turn-scoped collaboration instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
+- This also simulates Codex workspace bootstrap routing: `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` as Codex developer instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
 
 ## Scenario Metadata
 
@@ -22,12 +22,13 @@
   "runtime": "codex_app_server",
   "simulatedHeartbeatWorkspaceFile": "/tmp/openclaw-happy-path/workspace/HEARTBEAT.md",
   "simulatedWorkspaceBootstrapFiles": ["/tmp/openclaw-happy-path/workspace/MEMORY.md"],
-  "simulatedWorkspaceDeveloperInstructionFiles": ["/tmp/openclaw-happy-path/workspace/TOOLS.md"],
-  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [
-    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+  "simulatedWorkspaceDeveloperInstructionFiles": [
     "/tmp/openclaw-happy-path/workspace/SOUL.md",
-    "/tmp/openclaw-happy-path/workspace/USER.md"
+    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+    "/tmp/openclaw-happy-path/workspace/USER.md",
+    "/tmp/openclaw-happy-path/workspace/TOOLS.md"
   ],
+  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [],
   "sourceReplyDeliveryMode": "message_tool_only",
   "toolSnapshot": "codex-dynamic-tools.telegram-direct.json",
   "trigger": "user"
@@ -137,7 +138,7 @@
   "collaborationMode": {
     "mode": "default",
     "settings": {
-      "developer_instructions": "# Collaboration Mode: Default\n\nYou are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.\n\nYour active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.\n\n## request_user_input availability\n\nUse the `request_user_input` tool only when it is listed in the available tools for this turn.\n\nIn Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.\n\n## OpenClaw Agent Soul\n\nOpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.\n\n### /tmp/openclaw-happy-path/workspace/IDENTITY.md\n\n<IDENTITY.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/SOUL.md\n\n<SOUL.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/USER.md\n\n<USER.md contents will be here>",
+      "developer_instructions": null,
       "model": "gpt-5.5",
       "reasoning_effort": "medium"
     }
@@ -162,7 +163,7 @@
 
 ## Reconstructed Model-Bound Prompt Layers
 
-This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input with OpenClaw runtime context, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
+This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
 
 ### Layer Metadata
 
@@ -205,8 +206,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
 ```json
 {
   "codexCollaborationModeDeveloperInstructions": {
-    "chars": 1433,
-    "roughTokens": 359
+    "chars": 0,
+    "roughTokens": 0
   },
   "codexModelInstructions": {
     "chars": 21335,
@@ -225,20 +226,20 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 10000
   },
   "openClawDeveloperInstructions": {
-    "chars": 1964,
-    "roughTokens": 491
+    "chars": 2215,
+    "roughTokens": 554
   },
   "totalTextOnly": {
-    "chars": 26176,
-    "roughTokens": 6544
+    "chars": 25001,
+    "roughTokens": 6251
   },
   "totalWithDynamicToolsJson": {
-    "chars": 66176,
-    "roughTokens": 16544
+    "chars": 65001,
+    "roughTokens": 16251
   },
   "userInputText": {
-    "chars": 1129,
-    "roughTokens": 283
+    "chars": 1138,
+    "roughTokens": 285
   }
 }
 ```
@@ -450,6 +451,18 @@ You are in a Telegram direct conversation. Normal final replies are private and
 
 OpenClaw loaded these workspace instruction files from the active agent workspace. Internalize and follow them accordingly.
 
+### /tmp/openclaw-happy-path/workspace/SOUL.md
+
+<SOUL.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/IDENTITY.md
+
+<IDENTITY.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/USER.md
+
+<USER.md contents will be here>
+
 ### /tmp/openclaw-happy-path/workspace/TOOLS.md
 
 <TOOLS.md contents will be here>
@@ -457,35 +470,7 @@ OpenClaw loaded these workspace instruction files from the active agent workspac
 
 ### Developer: Codex Collaboration Mode Instructions
 
-```text
-# Collaboration Mode: Default
-
-You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
-
-Your active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.
-
-## request_user_input availability
-
-Use the `request_user_input` tool only when it is listed in the available tools for this turn.
-
-In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
-
-## OpenClaw Agent Soul
-
-OpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.
-
-### /tmp/openclaw-happy-path/workspace/IDENTITY.md
-
-<IDENTITY.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/SOUL.md
-
-<SOUL.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/USER.md
-
-<USER.md contents will be here>
-```
+This turn asks Codex app-server to resolve its built-in Default collaboration-mode instructions at runtime.
 
 ### User: Turn Input Text
 
@@ -495,7 +480,7 @@ Treat this OpenClaw-provided context as supporting project/user reference for th
 
 ## OpenClaw Workspace Context
 
-OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. TOOLS.md is provided as inherited Codex developer instructions. SOUL.md, IDENTITY.md, and USER.md are provided as turn-scoped collaboration instructions so native Codex subagents do not inherit them. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
+OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided as Codex thread developer instructions so standing workspace guidance is not repeated in every turn. MEMORY.md stays in turn-scoped memory context, and HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
 
 # Project Context
 

test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-heartbeat-codex-tool.md

@@ -7,7 +7,7 @@
 - Heartbeat happy path: Codex receives the structured `heartbeat_respond` dynamic tool in the searchable catalog instead of the initial tool context.
 - The heartbeat tool still carries the notify/no-notify decision, outcome, summary, and optional notification text instead of relying only on final-text parsing.
 - This captures the OpenClaw-owned Codex app-server inputs and reconstructs the stable Codex model/permission layers from committed Codex prompt fixtures.
-- This also simulates Codex workspace bootstrap routing: `TOOLS.md` as inherited developer instructions, `SOUL.md`, `IDENTITY.md`, and `USER.md` as turn-scoped collaboration instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
+- This also simulates Codex workspace bootstrap routing: `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` as Codex developer instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.
 
 ## Scenario Metadata
 
@@ -22,12 +22,13 @@
   "runtime": "codex_app_server",
   "simulatedHeartbeatWorkspaceFile": "/tmp/openclaw-happy-path/workspace/HEARTBEAT.md",
   "simulatedWorkspaceBootstrapFiles": ["/tmp/openclaw-happy-path/workspace/MEMORY.md"],
-  "simulatedWorkspaceDeveloperInstructionFiles": ["/tmp/openclaw-happy-path/workspace/TOOLS.md"],
-  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [
-    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+  "simulatedWorkspaceDeveloperInstructionFiles": [
     "/tmp/openclaw-happy-path/workspace/SOUL.md",
-    "/tmp/openclaw-happy-path/workspace/USER.md"
+    "/tmp/openclaw-happy-path/workspace/IDENTITY.md",
+    "/tmp/openclaw-happy-path/workspace/USER.md",
+    "/tmp/openclaw-happy-path/workspace/TOOLS.md"
   ],
+  "simulatedWorkspaceTurnScopedDeveloperInstructionFiles": [],
   "sourceReplyDeliveryMode": "message_tool_only",
   "toolSnapshot": "codex-dynamic-tools.heartbeat-turn.json",
   "trigger": "heartbeat"
@@ -138,7 +139,7 @@
   "collaborationMode": {
     "mode": "default",
     "settings": {
-      "developer_instructions": "This is an OpenClaw heartbeat turn. Apply these instructions only to this heartbeat wake; ordinary chat turns should stay in Codex Default mode.\n\nWhen you are ready to end the heartbeat, prefer the structured `heartbeat_respond` tool so OpenClaw can record the wake outcome and notification decision. If `heartbeat_respond` is not already available and `tool_search` is available, search for `heartbeat_respond`, load it, then call it. Use `notify=false` when nothing should visibly interrupt the user.\n\n### Heartbeats\n\nUse heartbeats to create useful proactive progress, not chatter.\nTreat a heartbeat as a wake-up: orient, read HEARTBEAT.md when present, then do what is actually useful now.\nIf HEARTBEAT.md assigns concrete or ongoing work, execute its spirit with judgment. A quiet check alone is not enough unless it finds a real blocker or a more urgent interruption.\nAvoid rote loops. Do not confuse orientation with accomplishment.\nPrefer meaningful action over commentary. A good heartbeat often looks like silent progress.\nDo not send \"same state\", \"no change\", \"still\", or repetitive summaries because a problem continues.\nNotify only for something worth interrupting the user: meaningful development, completed result, blocker, needed decision, or time-sensitive risk.\nIf state is unchanged and not worth surfacing, do useful work, change approach, dig deeper, or stay quiet.\n\n## OpenClaw Agent Soul\n\nOpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.\n\n### /tmp/openclaw-happy-path/workspace/IDENTITY.md\n\n<IDENTITY.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/SOUL.md\n\n<SOUL.md contents will be here>\n\n### /tmp/openclaw-happy-path/workspace/USER.md\n\n<USER.md contents will be here>\n\n## OpenClaw Heartbeat Workspace\n\nHEARTBEAT.md exists in the active agent workspace. Read it before proceeding with this heartbeat, then decide what action is appropriate.\n\n- /tmp/openclaw-happy-path/workspace/HEARTBEAT.md",
+      "developer_instructions": "This is an OpenClaw heartbeat turn. Apply these instructions only to this heartbeat wake; ordinary chat turns should stay in Codex Default mode.\n\nWhen you are ready to end the heartbeat, prefer the structured `heartbeat_respond` tool so OpenClaw can record the wake outcome and notification decision. If `heartbeat_respond` is not already available and `tool_search` is available, search for `heartbeat_respond`, load it, then call it. Use `notify=false` when nothing should visibly interrupt the user.\n\n### Heartbeats\n\nUse heartbeats to create useful proactive progress, not chatter.\nTreat a heartbeat as a wake-up: orient, read HEARTBEAT.md when present, then do what is actually useful now.\nIf HEARTBEAT.md assigns concrete or ongoing work, execute its spirit with judgment. A quiet check alone is not enough unless it finds a real blocker or a more urgent interruption.\nAvoid rote loops. Do not confuse orientation with accomplishment.\nPrefer meaningful action over commentary. A good heartbeat often looks like silent progress.\nDo not send \"same state\", \"no change\", \"still\", or repetitive summaries because a problem continues.\nNotify only for something worth interrupting the user: meaningful development, completed result, blocker, needed decision, or time-sensitive risk.\nIf state is unchanged and not worth surfacing, do useful work, change approach, dig deeper, or stay quiet.\n\n## OpenClaw Heartbeat Workspace\n\nHEARTBEAT.md exists in the active agent workspace. Read it before proceeding with this heartbeat, then decide what action is appropriate.\n\n- /tmp/openclaw-happy-path/workspace/HEARTBEAT.md",
       "model": "gpt-5.5",
       "reasoning_effort": "medium"
     }
@@ -163,7 +164,7 @@
 
 ## Reconstructed Model-Bound Prompt Layers
 
-This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input with OpenClaw runtime context, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
+This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.
 
 ### Layer Metadata
 
@@ -206,8 +207,8 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
 ```json
 {
   "codexCollaborationModeDeveloperInstructions": {
-    "chars": 2119,
-    "roughTokens": 530
+    "chars": 1610,
+    "roughTokens": 403
   },
   "codexModelInstructions": {
     "chars": 21335,
@@ -226,20 +227,20 @@ This is the deterministic model-bound layer stack OpenClaw can snapshot for the
     "roughTokens": 10274
   },
   "openClawDeveloperInstructions": {
-    "chars": 1983,
-    "roughTokens": 496
+    "chars": 2234,
+    "roughTokens": 559
   },
   "totalTextOnly": {
-    "chars": 27119,
-    "roughTokens": 6780
+    "chars": 26870,
+    "roughTokens": 6718
   },
   "totalWithDynamicToolsJson": {
-    "chars": 68214,
-    "roughTokens": 17054
+    "chars": 67965,
+    "roughTokens": 16992
   },
   "userInputText": {
-    "chars": 1367,
-    "roughTokens": 342
+    "chars": 1376,
+    "roughTokens": 344
   }
 }
 ```
@@ -451,6 +452,18 @@ You are in a Telegram direct conversation. Normal final replies are private and
 
 OpenClaw loaded these workspace instruction files from the active agent workspace. Internalize and follow them accordingly.
 
+### /tmp/openclaw-happy-path/workspace/SOUL.md
+
+<SOUL.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/IDENTITY.md
+
+<IDENTITY.md contents will be here>
+
+### /tmp/openclaw-happy-path/workspace/USER.md
+
+<USER.md contents will be here>
+
 ### /tmp/openclaw-happy-path/workspace/TOOLS.md
 
 <TOOLS.md contents will be here>
@@ -474,22 +487,6 @@ Do not send "same state", "no change", "still", or repetitive summaries because
 Notify only for something worth interrupting the user: meaningful development, completed result, blocker, needed decision, or time-sensitive risk.
 If state is unchanged and not worth surfacing, do useful work, change approach, dig deeper, or stay quiet.
 
-## OpenClaw Agent Soul
-
-OpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.
-
-### /tmp/openclaw-happy-path/workspace/IDENTITY.md
-
-<IDENTITY.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/SOUL.md
-
-<SOUL.md contents will be here>
-
-### /tmp/openclaw-happy-path/workspace/USER.md
-
-<USER.md contents will be here>
-
 ## OpenClaw Heartbeat Workspace
 
 HEARTBEAT.md exists in the active agent workspace. Read it before proceeding with this heartbeat, then decide what action is appropriate.
@@ -505,7 +502,7 @@ Treat this OpenClaw-provided context as supporting project/user reference for th
 
 ## OpenClaw Workspace Context
 
-OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. TOOLS.md is provided as inherited Codex developer instructions. SOUL.md, IDENTITY.md, and USER.md are provided as turn-scoped collaboration instructions so native Codex subagents do not inherit them. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
+OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided as Codex thread developer instructions so standing workspace guidance is not repeated in every turn. MEMORY.md stays in turn-scoped memory context, and HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.
 
 # Project Context
 

test/helpers/agents/happy-path-prompt-snapshots.ts

@@ -131,47 +131,49 @@ const CODEX_WORKSPACE_BOOTSTRAP_CONTEXT_FILES = [
 
 const CODEX_WORKSPACE_THREAD_DEVELOPER_CONTEXT_FILES = [
   {
-    path: path.join(WORKSPACE_DIR, "TOOLS.md"),
-    content: "<TOOLS.md contents will be here>",
+    path: path.join(WORKSPACE_DIR, "SOUL.md"),
+    content: "<SOUL.md contents will be here>",
   },
-] as const;
-
-const CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_CONTEXT_FILES = [
   {
     path: path.join(WORKSPACE_DIR, "IDENTITY.md"),
     content: "<IDENTITY.md contents will be here>",
   },
-  {
-    path: path.join(WORKSPACE_DIR, "SOUL.md"),
-    content: "<SOUL.md contents will be here>",
-  },
   {
     path: path.join(WORKSPACE_DIR, "USER.md"),
     content: "<USER.md contents will be here>",
   },
+  {
+    path: path.join(WORKSPACE_DIR, "TOOLS.md"),
+    content: "<TOOLS.md contents will be here>",
+  },
 ] as const;
 
+const CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_CONTEXT_FILES = [] as const;
+
 const CODEX_HEARTBEAT_CONTEXT_FILE = {
   path: path.join(WORKSPACE_DIR, "HEARTBEAT.md"),
   content: "<HEARTBEAT.md contents will be here>",
 } as const;
 
-const CODEX_WORKSPACE_BOOTSTRAP_PROMPT_CONTEXT = [
-  "OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. TOOLS.md is provided as inherited Codex developer instructions. SOUL.md, IDENTITY.md, and USER.md are provided as turn-scoped collaboration instructions so native Codex subagents do not inherit them. HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.",
-  "",
-  "# Project Context",
-  "",
-  "The following project context files have been loaded:",
-  "",
-  ...CODEX_WORKSPACE_BOOTSTRAP_CONTEXT_FILES.flatMap((file) => [
-    `## ${file.path}`,
-    "",
-    file.content,
-    "",
-  ]),
-]
-  .join("\n")
-  .trim();
+const CODEX_WORKSPACE_BOOTSTRAP_PROMPT_CONTEXT =
+  CODEX_WORKSPACE_BOOTSTRAP_CONTEXT_FILES.length > 0
+    ? [
+        "OpenClaw loaded these user-editable workspace files for the current turn. Codex loads AGENTS.md natively. SOUL.md, IDENTITY.md, TOOLS.md, and USER.md are provided as Codex thread developer instructions so standing workspace guidance is not repeated in every turn. MEMORY.md stays in turn-scoped memory context, and HEARTBEAT.md is handled by heartbeat collaboration-mode guidance. Those files are not repeated here.",
+        "",
+        "# Project Context",
+        "",
+        "The following project context files have been loaded:",
+        "",
+        ...CODEX_WORKSPACE_BOOTSTRAP_CONTEXT_FILES.flatMap((file) => [
+          `## ${file.path}`,
+          "",
+          file.content,
+          "",
+        ]),
+      ]
+        .join("\n")
+        .trim()
+    : undefined;
 
 const CODEX_WORKSPACE_THREAD_DEVELOPER_INSTRUCTIONS = [
   "## OpenClaw Workspace Instructions",
@@ -188,20 +190,23 @@ const CODEX_WORKSPACE_THREAD_DEVELOPER_INSTRUCTIONS = [
   .join("\n")
   .trim();
 
-const CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_INSTRUCTIONS = [
-  "## OpenClaw Agent Soul",
-  "",
-  "OpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.",
-  "",
-  ...CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_CONTEXT_FILES.flatMap((file) => [
-    `### ${file.path}`,
-    "",
-    file.content,
-    "",
-  ]),
-]
-  .join("\n")
-  .trim();
+const CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_INSTRUCTIONS =
+  CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_CONTEXT_FILES.length > 0
+    ? [
+        "## OpenClaw Agent Soul",
+        "",
+        "OpenClaw loaded these workspace instruction files from the active agent workspace. They are the canonical definitions of who you are, how you think and work, and the human you work alongside. Internalize and follow them accordingly.",
+        "",
+        ...CODEX_WORKSPACE_TURN_SCOPED_DEVELOPER_CONTEXT_FILES.flatMap((file) => [
+          `### ${file.path}`,
+          "",
+          file.content,
+          "",
+        ]),
+      ]
+        .join("\n")
+        .trim()
+    : undefined;
 
 const CODEX_HEARTBEAT_COLLABORATION_INSTRUCTIONS = [
   "## OpenClaw Heartbeat Workspace",
@@ -647,7 +652,7 @@ function renderModelBoundPromptLayers(params: {
   return [
     "## Reconstructed Model-Bound Prompt Layers",
     "",
-    "This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input with OpenClaw runtime context, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.",
+    "This is the deterministic model-bound layer stack OpenClaw can snapshot for the Codex happy path. It uses a pinned Codex `gpt-5.5` prompt fixture generated from Codex's model catalog/cache shape, then adds the Codex permission developer text, Codex thread config instructions when present, OpenClaw developer instructions, turn-scoped collaboration-mode instructions when OpenClaw provides them, turn input, and the OpenClaw dynamic tool catalog. Codex can still add runtime-owned context such as native workspace `AGENTS.md`, environment context, memories, app/plugin instructions, and built-in collaboration-mode instructions inside the Codex runtime.",
     "",
     "### Layer Metadata",
     "",
@@ -745,7 +750,10 @@ function readCodexTurnInputText(turnStartParams: { input?: unknown }): string {
   return firstText?.text ?? "";
 }
 
-function buildCodexOpenClawRuntimeContext(): string {
+function buildCodexOpenClawRuntimeContext(): string | undefined {
+  if (!CODEX_WORKSPACE_BOOTSTRAP_PROMPT_CONTEXT) {
+    return undefined;
+  }
   return [
     "OpenClaw runtime context for this turn:",
     "Treat this OpenClaw-provided context as supporting project/user reference for the current request.",
@@ -757,7 +765,8 @@ function buildCodexOpenClawRuntimeContext(): string {
 }
 
 function prependCodexOpenClawRuntimeContext(prompt: string): string {
-  return [buildCodexOpenClawRuntimeContext(), "", "Current user request:", prompt].join("\n");
+  const runtimeContext = buildCodexOpenClawRuntimeContext();
+  return runtimeContext ? [runtimeContext, "", "Current user request:", prompt].join("\n") : prompt;
 }
 
 function renderScenarioSnapshot(scenario: PromptScenario): string {
@@ -793,7 +802,7 @@ function renderScenarioSnapshot(scenario: PromptScenario): string {
     "",
     ...scenario.notes.map((note) => `- ${note}`),
     "- This captures the OpenClaw-owned Codex app-server inputs and reconstructs the stable Codex model/permission layers from committed Codex prompt fixtures.",
-    "- This also simulates Codex workspace bootstrap routing: `TOOLS.md` as inherited developer instructions, `SOUL.md`, `IDENTITY.md`, and `USER.md` as turn-scoped collaboration instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.",
+    "- This also simulates Codex workspace bootstrap routing: `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and `USER.md` as Codex developer instructions, `MEMORY.md` in turn input, and `HEARTBEAT.md` as a heartbeat-only file pointer.",
     "",
     "## Scenario Metadata",
     "",
@@ -861,7 +870,7 @@ function renderReadme(scenarios: PromptScenario[]): string {
     "- Codex harness default coverage for tool-only visible source replies.",
     "- Telegram direct chat, Discord group chat, and a heartbeat turn with `heartbeat_respond` available through searchable dynamic tools.",
     "",
-    "The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, OpenClaw developer instructions, turn input with simulated OpenClaw workspace bootstrap runtime context, heartbeat collaboration-mode guidance when applicable, and references to the complete dynamic tool catalog.",
+    "The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, OpenClaw developer instructions, turn input, heartbeat collaboration-mode guidance when applicable, and references to the complete dynamic tool catalog.",
     "",
     "The workspace bootstrap simulation includes dummy workspace contents so prompt reviewers can see how OpenClaw routes stable profile files into Codex developer instructions, keeps `MEMORY.md` in turn input, and points heartbeat turns at `HEARTBEAT.md` without inlining it. `AGENTS.md` is intentionally not repeated here because Codex loads it natively.",
     "",

test/scripts/prompt-snapshots.test.ts

@@ -174,14 +174,14 @@ describe("happy path prompt snapshots", () => {
     const group = readCommittedSnapshot("discord-group-codex-message-tool.md");
     const heartbeat = readCommittedSnapshot("telegram-heartbeat-codex-tool.md");
     const heartbeatPhrase = "Use heartbeats to create useful proactive progress";
-    const agentSoulHeading = "## OpenClaw Agent Soul";
+    const workspaceInstructionsHeading = "## OpenClaw Workspace Instructions";
 
     expect(direct).toContain('"collaborationMode": {');
-    expect(direct).toContain('"developer_instructions": "# Collaboration Mode: Default');
-    expect(direct).toContain(agentSoulHeading);
+    expect(direct).toContain('"developer_instructions": null');
+    expect(direct).toContain(workspaceInstructionsHeading);
     expect(group).toContain('"collaborationMode": {');
-    expect(group).toContain('"developer_instructions": "# Collaboration Mode: Default');
-    expect(group).toContain(agentSoulHeading);
+    expect(group).toContain('"developer_instructions": null');
+    expect(group).toContain(workspaceInstructionsHeading);
     expect(direct).not.toContain(heartbeatPhrase);
     expect(group).not.toContain(heartbeatPhrase);
     expect(direct).not.toContain("This is an OpenClaw heartbeat turn.");
@@ -189,7 +189,7 @@ describe("happy path prompt snapshots", () => {
 
     expect(heartbeat).toContain('"collaborationMode": {');
     expect(heartbeat).toContain('"developer_instructions": "This is an OpenClaw heartbeat turn.');
-    expect(heartbeat).toContain(agentSoulHeading);
+    expect(heartbeat).toContain(workspaceInstructionsHeading);
     const openClawRuntimeInstructions = renderedPromptSection(
       heartbeat,
       "### Developer: OpenClaw Runtime Instructions",
@@ -202,6 +202,7 @@ describe("happy path prompt snapshots", () => {
     );
 
     expect(openClawRuntimeInstructions).not.toContain(heartbeatPhrase);
+    expect(collaborationModeInstructions).not.toContain(workspaceInstructionsHeading);
     expect(collaborationModeInstructions).toContain(heartbeatPhrase);
     expect(collaborationModeInstructions).toContain("HEARTBEAT.md exists");
     expect(collaborationModeInstructions).toContain(