Greptile Summary

Adds agents.defaults.contextInjection config option to control when workspace context files (AGENTS.md, SOUL.md, USER.md, etc.) are injected into the system prompt. The feature uses session file existence as a signal to determine first vs subsequent messages.

Key changes:

• New config option with two modes: "always" (default, preserves current behavior) and "first-message-only" (inject only on first message)
• Implementation in src/agents/pi-embedded-runner/run/attempt.ts checks if session file exists before resolving bootstrap context, then conditionally clears contextFiles array when skipping injection
• Bootstrap metadata is preserved even when skipping injection (needed for workspaceNotes detection and systemPromptReport)
• Clean separation of concerns: schema validation, resolver function, and conditional logic are all properly isolated

Benefits:

• 93% token reduction over long conversations when using "first-message-only" mode
• Zero risk to existing deployments (opt-in, safe default)
• Agent can still read workspace files on demand using the read tool

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean implementation of an opt-in performance optimization feature. Uses safe default ("always") that preserves existing behavior. The logic is straightforward: checks session file existence to determine first vs subsequent messages. Properly handles edge cases with error handling in the fs.stat check. No breaking changes, and the feature is well-documented.
• No files require special attention

_{Last reviewed commit: ed98b12}

The token-savings idea here is good, but sessionFileExists is a pretty rough proxy for “not the first message.” A resumed/pre-created/aborted session can already have a session file before the first meaningful turn, which would skip context injection too early. I’d consider keying this off transcript contents or a real “has completed first turn” marker instead of file existence alone.

I’m not convinced sessionFileExists is a safe proxy for “this is not the first message”. Pre-created session files, aborted runs, or empty repaired sessions can all make the file exist before any real assistant turn was written, which would suppress context injection too early. I’d prefer a regression that proves this only disables injection once the session actually contains prior conversational state, not just a file on disk.

This is a great optimization, and there's a security angle worth considering too.

With workspace files injected on every message, a long conversation means those files (which often contain credentials, API keys, and personal data from AGENTS.md/TOOLS.md/USER.md) are sent to the API 100+ times. Each transmission is an exposure surface — if the API provider is compromised, cached prompts leak.

The first-message-only approach doesn't just save tokens — it reduces the number of times sensitive workspace context crosses the wire by 99%.

For anyone running sensitive workspaces: until this lands, you can also audit what's being sent using ClawMoat's secret scanner to catch credentials that shouldn't be in workspace files at all:

const { scanSecrets } = require('clawmoat');
const result = scanSecrets(fs.readFileSync('TOOLS.md', 'utf8'));
// Catches API keys, tokens, passwords before they enter the context window

+1 on merging this.

+1

if we inject workspace context on message 1 and then remove it on message 2, the system prompt changes, so the cache key changes too. that usually means a cache miss right after the first turn. whenever you send more messages you will be getting cache hits and those are very cheap $

removing injection of bootstrap files can also weaken instruction consistency, because later turns no longer include agents/soul/user unless the model reads them again

do any providers you use not have caching? that's the only situation you would save $ but then would also get worst experience for lack of agents/soul/user/core files

unless i'm missing something, i think injecting core files only on the first message does not really make sense

if that context is removed after turn 1, then later turns behave almost the same as if those core files were never there. in that case, you do not need a new flag, you can just keep core files empty and get the same result; but that also removes the whole point of having AGENTS/SOUL/IDENTITY/etc as persistent guidance, and that is a big part of what makes openclaw different from a generic ai chatbot

@dsantoreis The refinement makes a lot of sense — keeping core bootstrap (agents/soul/user) always injected while gating heavier workspace context is the right balance. You get instruction stability + cache friendliness on the core files, and still save the bulk of tokens on workspace payload.

From a security perspective this is actually better than the original approach too: the core bootstrap files (AGENTS.md, SOUL.md, USER.md) rarely contain secrets, but workspace files and daily memory notes often do. Gating those reduces exposure surface while keeping the agent's identity/instructions consistent.

One thought: it might be worth exposing which files fall into "core" vs "workspace" in the config schema, so operators can customize the boundary. Some setups have lightweight workspaces but heavy bootstrap files, and vice versa.

Really clean evolution of the PR 👏