Greptile Summary

This PR introduces a contextInjection config option ("always" | "first-message-only") that allows workspace bootstrap files (AGENTS.md, SOUL.md, etc.) to be injected into the system prompt only on the first message of a session, saving significant tokens on long conversations. The feature is well-structured with zero overhead in the default "always" mode and is backed by 12 tests.

Key findings:

• Logic issue — workspaceNotes commit reminder is silently dropped after message 1: The PR description explicitly states "Bootstrap metadata is still loaded for workspaceNotes detection… even when file content is skipped", but the implementation applies applyContextInjectionFilter inside resolveBootstrapFilesForRun before bootstrapFiles is returned. This means the workspaceNotes check in attempt.ts:838 always evaluates to false on subsequent messages when first-message-only is active — the "Reminder: commit your changes in this workspace after edits." line is never injected into the system prompt past message 1.

• Synchronous file I/O blocks the event loop: sessionHasAssistantMessages uses fsSync.openSync / fsSync.readSync, which are blocking calls. In deployments with first-message-only enabled, this will stall the event loop on every agent message. Converting to async/await with fs.promises is straightforward given the already-async call sites.

• Inline type duplication: params.ts redeclares the "always" | "first-message-only" union instead of importing the exported ContextInjectionMode type from bootstrap-files.ts, creating a maintenance risk if new modes are added.

Confidence Score: 2/5

• Not safe to merge without addressing the workspaceNotes metadata loss on subsequent messages, which contradicts explicit PR claims.
• The default behavior ("always" mode) is fully backward-compatible and untouched, but the new "first-message-only" mode has a critical metadata gap: the workspaceNotes commit reminder is silently dropped from the system prompt on all messages after the first, which directly contradicts the PR description's guarantee that "Bootstrap metadata is still loaded for workspaceNotes detection… even when file content is skipped." Additionally, blocking synchronous file I/O on every message in non-default mode will stall the event loop in concurrent deployments. The duplicate type union in params.ts increases maintenance risk. All three issues are fixable before or after merge, but the metadata gap in particular contradicts an explicit PR claim.
• src/agents/bootstrap-files.ts (filtering order and sync I/O), src/agents/pi-embedded-runner/run/params.ts (type duplication)

_{Last reviewed commit: 04a876a}

This is directly relevant to setups with large workspace files (SOUL.md, USER.md, TOOLS.md, AGENTS.md) — the per-message token overhead is real and adds up in longer sessions.

Notes from reviewing:

Positive:

• The first-message-only semantics are clean — opt-in is the right approach vs. changing the default
• The HEARTBEAT.md fix (dfaffc277) is important: heartbeat-light-context sessions would have silently dropped their instructions after the first assistant turn
• CI is now fully green — 23 passing, 0 failing

One open question before merge:
The remaining bot P2 about CLI backends that emit a synthetic fallback session ID (no real resumable token) — these could still trigger follow-up bootstrap skips on what is functionally a fresh session. @dsantoreis mentioned deferring to maintainer input. Would be good to have an explicit stance documented (even if the fix lands as a follow-up issue) so the behavior is predictable for affected backends.

Overall: LGTM on the implementation. The 3.4M token / ~$1.51 savings per 100-message session is meaningful for production setups.

LGTM — the synthetic CLI session ID concern from our earlier review is resolved. Commit 4c43df5ab correctly limits persistence to real resumable session IDs only. Clean fix, no further issues from our end. Thanks for the quick turnaround @dsantoreis.

🔒 Aisle Security Analysis

We found 2 potential security issue(s) in this PR:

1. 🟡 Workspace bootstrap guardrails can be skipped via contextInjection="first-message-only" (transcript-based)

Description

The new contextInjection: "first-message-only" mode can remove workspace bootstrap files (AGENTS.md, SOUL.md, USER.md, etc.) from the system prompt after any assistant message exists in the session transcript.

Why this is a security problem (depending on deployment/threat model):

• Workspace bootstrap files are injected into the system prompt as # Project Context (see buildAgentSystemPrompt()), making them higher-priority than user messages.
• Many installations (and the provided template) place security-relevant guardrails in these files (e.g., “don’t exfiltrate private data”, “don’t run destructive commands”, “don’t load MEMORY.md in shared contexts”).
• With first-message-only, these guardrails are absent on subsequent turns, increasing the risk of prompt-injection success and accidental policy drift in long-running sessions.
• The decision to skip bootstrap injection is based only on detecting an assistant role in the session JSONL tail. If an attacker can tamper with the session transcript file (multi-tenant/shared host, writable state dir, compromised user, etc.), they can pre-seed a fake assistant entry so bootstrap files are skipped even on the first real run.

Vulnerable logic:

if (mode === "first-message-only" && params.hasExistingAssistantMessages) {
  return [];
}

and transcript-based detection:

const parsed = JSON.parse(line);
if (parsed?.message?.role === "assistant") {
  return true;
}

Recommendation

Treat workspace bootstrap files as potentially security-relevant and avoid making their continued injection depend solely on transcript state.

Recommended mitigations (choose one or combine):

1. Keep security-critical instructions out of user-editable bootstrap files and in a separate, always-injected system policy section.

2. If you keep first-message-only, do not skip all files. For example, always inject a minimal allowlist of “guardrail” files (e.g., AGENTS.md / IDENTITY.md) while allowing persona/verbosity files to be skipped.

3. Make skipping depend on a trusted session state flag (not on parsing user-writable JSONL). For example, persist a boolean like bootstrapInjectedOnce=true in the session store entry (sessions.json) that is written only by the agent runtime.

4. Add a safety valve: if bootstrap files changed since last injection (hash/mtime), re-inject them.

Example (persist a trusted flag):

​// pseudo-code: write to session store after first successful run
sessionEntry.bootstrapInjectedOnce = true;

​// later
if (contextInjection === "first-message-only" && sessionEntry.bootstrapInjectedOnce) {
  skipBootstrap();
}

2. 🔵 Uncaught exception from FileHandle.close() in finally can crash run (DoS)

Description

The sessionHasAssistantMessages helper attempts to be best-effort (it swallows errors from open/stat/read/JSON.parse), but the finally block awaits handle.close() without guarding errors.

• Any rejection from FileHandle.close() (e.g., intermittent I/O error, invalidated FD, unusual FS behavior) will override the earlier catch-all and cause sessionHasAssistantMessages() to throw.
• The caller (runEmbeddedAttempt) awaits this function without a surrounding try/catch, so the exception can abort the entire run, creating a denial-of-service / unexpected crash vector.

Vulnerable code:

} finally {
  await handle?.close();
}

Recommendation

Guard close() so it cannot throw out of the best-effort helper.

} finally {
  try {
    await handle?.close();
  } catch {
    ​// optionally log at debug level
  }
}

Optionally, if you want to preserve the error for logging without crashing:

} finally {
  await handle?.close().catch((err) => {
    warn?.(`session transcript close failed: ${String(err)}`);
  });
}

Analyzed PR: #40372 at commit 5cf4065

_{Last updated on: 2026-03-13T09:40:41Z}

🔒 Aisle Security Analysis

We found 2 potential security issue(s) in this PR:

1. 🟡 Prompt-safety regression: optional config can skip workspace bootstrap policy files after first assistant message

Description

The new contextInjection: "first-message-only" mode can remove all workspace bootstrap files (AGENTS.md/SOUL.md/USER.md/etc.) from the system prompt after the first assistant message, which can weaken prompt-injection resistance and allow instruction/policy drift.

Why this matters:

• Workspace bootstrap files are user/owner-controlled “policy/context” that OpenClaw injects into the system prompt (e.g., AGENTS.md template includes explicit security guidance like “Don’t exfiltrate private data. Ever.”).
• With first-message-only, subsequent turns build a system prompt without those files, so the model no longer has the owner’s persistent constraints/operating rules unless they happen to remain in the conversation window.
• This is a footgun: enabling the option to save tokens can make the agent more susceptible to gradual prompt injection (especially in long conversations / after compaction) and can cause the agent to take actions that the workspace policy would have prohibited.

Vulnerable logic (skips all bootstrap context files):

if (mode === "first-message-only" && params.hasExistingAssistantMessages) {
  return [];
}

Data-flow context:

• Input: contextInjection comes from runtime params/config (params.config?.agents?.defaults?.contextInjection) in runEmbeddedAttempt.
• Gate: sessionHasAssistantMessages(params.sessionFile) determines whether to skip.
• Sink/impact: resolveBootstrapContextForRun() returns contextFiles=[], and the system prompt is built without the workspace bootstrap contents, removing owner-defined constraints from system-level instructions.

Notes:

• Default remains "always", but the new option introduces an insecure configuration mode without an explicit security warning.

Recommendation

Do not allow first-message-only to drop all policy/context bootstrap files. Safer options:

1. Always inject a minimal “security policy” subset (e.g., AGENTS.md “Red Lines” section, MEMORY handling rules) even when skipping the rest.

2. Re-inject on high-risk turns (tool-use, external messaging, web fetch/search, filesystem writes) while allowing skipping on purely conversational turns.

3. Add an explicit security warning in config help/docs when first-message-only is enabled.

Example: keep a minimal allowlist when skipping:

const MIN_SECURITY_FILES = new Set(["AGENTS.md", "SOUL.md"] as const);

if (mode === "first-message-only" && hasExistingAssistantMessages) {
  return params.files.filter(f => MIN_SECURITY_FILES.has(f.name));
}
return params.files;

This preserves persistent owner constraints while still reducing token usage.

2. 🟡 Cost/availability DoS via truncated session head scan in sessionHasAssistantMessages

Description

The sessionHasAssistantMessages() helper only reads the first 16KB / 100 lines of a session JSONL file to determine whether the session already contains assistant messages.

Because Pi transcripts are JSONL with one JSON object per line, a single very large first user message line can push the first assistant message past the first 16KB chunk. In that case the function will:

• read only the header + a partial first message line
• fail JSON.parse() on the partial line (caught and ignored)
• return false (no assistant found)

When contextInjection is set to "first-message-only", this false negative causes the system to repeatedly inject bootstrap context on subsequent turns, increasing prompt size and token spend. A malicious user can intentionally send an extremely large initial prompt to keep assistant messages out of the scanned head region, causing sustained token/cost amplification and potentially hitting model context limits (availability degradation).

Vulnerable code (truncation + per-line JSON.parse over a partial chunk):

const buf = Buffer.alloc(SESSION_HEAD_MAX_BYTES);
const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
const chunk = buf.toString("utf-8", 0, bytesRead);
const lines = chunk.split(/\r?\n/).slice(0, SESSION_HEAD_MAX_LINES);
for (const line of lines) {
  ...
  try {
    const parsed = JSON.parse(line);
    if (parsed?.message?.role === "assistant") {
      return true;
    }
  } catch {
    ​// skip malformed lines
  }
}

Recommendation

Make assistant-history detection robust against large first lines / head truncation.

Good options (pick one):

1. Scan from the tail (recommended): read the last N bytes (e.g., 64–256KB), split into lines, skip the first partial line (since you may start mid-line), then JSON-parse each complete line and look for type:"message" + message.role=="assistant".

2. Use streaming line reading with limits: createReadStream() + readline.createInterface(), but stop after finding an assistant. If you want to avoid reading huge early lines, set a maximum scanned byte budget and/or move to tail scanning.

3. Persist a small sidecar/metadata flag in the session store (e.g., hasAssistant: true once an assistant message is appended) rather than parsing the transcript file.

Example (tail scan):

import fs from "node:fs/promises";

const TAIL_MAX_BYTES = 256 * 1024;

export async function sessionHasAssistantMessages(sessionFile: string): Promise<boolean> {
  let handle: fs.FileHandle | undefined;
  try {
    handle = await fs.open(sessionFile, "r");
    const stat = await handle.stat();
    const start = Math.max(0, stat.size - TAIL_MAX_BYTES);
    const len = stat.size - start;
    const buf = Buffer.alloc(len);
    const { bytesRead } = await handle.read(buf, 0, len, start);
    const chunk = buf.toString("utf-8", 0, bytesRead);

    const lines = chunk.split(/\r?\n/);
    ​// If we started mid-file, drop the first possibly-partial line
    if (start > 0) lines.shift();

    for (const line of lines) {
      if (!line.trim()) continue;
      try {
        const parsed = JSON.parse(line);
        if (parsed?.type === "message" && parsed?.message?.role === "assistant") return true;
      } catch {
        continue;
      }
    }
  } catch {
    return false;
  } finally {
    try { await handle?.close(); } catch { /* ignore */ }
  }
  return false;
}

This avoids the “huge first line keeps assistant messages out of the scanned head” false negative and reduces the risk of token/cost amplification when contextInjection: "first-message-only" is enabled.

Analyzed PR: #40372 at commit 34cbb95

_{Last updated on: 2026-03-13T08:13:26Z}

🔒 Aisle Security Analysis

We found 2 potential security issue(s) in this PR:

1. 🟡 Context injection policy bypass via truncated head-only scan of session transcript

Description

The new sessionHasAssistantMessages() helper reads only the first 16KB / 100 lines of the session JSONL transcript to decide whether an assistant message exists. This decision is used to enforce contextInjection: "first-message-only" (skip injecting AGENTS.md/SOUL.md/etc after the assistant has spoken).

Because it only parses the file head, a user can cause persistent false negatives ("no assistant history") even when assistant messages exist, by ensuring the first assistant message is not visible within that head window:

• Single huge first user message: if the first user JSONL line is >16KB, the first read chunk ends mid-line; JSON parsing fails and the assistant message (which starts after that long line) is never seen.
• Many user messages before first assistant reply (queue/backlog/import/replay scenarios): if >100 user-message lines occur before the first assistant message line, the assistant role is never observed.
• Long assistant/tool blocks early can similarly push the first assistant record beyond the byte cap.

Security/robustness impact when contextInjection is configured to first-message-only:

• The agent will continue re-injecting mutable workspace bootstrap files on later turns, defeating the intended behavior.
• If an untrusted user can get the agent to modify AGENTS.md/SOUL.md mid-session, those modified instructions may continue to be injected into the system prompt on subsequent turns (policy bypass / prompt-injection surface), and it can also cause repeated token/cost overhead.

Vulnerable code (head-only parsing + silent failure):

const buf = Buffer.alloc(SESSION_HEAD_MAX_BYTES);
const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
const chunk = buf.toString("utf-8", 0, bytesRead);
const lines = chunk.split(/\r?\n/).slice(0, SESSION_HEAD_MAX_LINES);
for (const line of lines) {
  try {
    const parsed = JSON.parse(line);
    if (parsed?.message?.role === "assistant") {
      return true;
    }
  } catch {
    ​// skip malformed lines
  }
}

Relevant locations:

• src/agents/bootstrap-files.ts [sessionHasAssistantMessages lines 17-55], and its use in injection gating via applyContextInjectionFilter [lines 106-121]
• src/agents/pi-embedded-runner/run/attempt.ts uses the result to decide injection behavior (diff hunk around the new hasExistingAssistantMessages assignment)

Recommendation

Make assistant-history detection robust against long/partial lines and large prefixes.

Recommended approaches (pick one):

1. Stream parse JSONL line-by-line with a maximum total bytes/lines, but do not stop at an arbitrary byte offset mid-line:

import fs from "node:fs";
import readline from "node:readline";

const MAX_LINES = 2000;
const MAX_TOTAL_BYTES = 2 * 1024 * 1024; // cap
const MAX_LINE_BYTES = 256 * 1024; // cap per record

export async function sessionHasAssistantMessages(sessionFile: string): Promise<boolean> {
  const stream = fs.createReadStream(sessionFile, { encoding: "utf8" });
  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
  let lines = 0;
  let totalBytes = 0;

  try {
    for await (const line of rl) {
      lines++;
      totalBytes += Buffer.byteLength(line, "utf8") + 1;
      if (lines > MAX_LINES || totalBytes > MAX_TOTAL_BYTES) break;
      if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) continue; // skip huge record but keep scanning

      if (!line.trim()) continue;
      try {
        const parsed = JSON.parse(line);
        if (parsed?.type === "message" && parsed?.message?.role === "assistant") return true;
      } catch {
        ​// skip malformed line
      }
    }
  } finally {
    rl.close();
    stream.destroy();
  }
  return false;
}

2. Alternatively, scan the tail (last N lines/bytes) as well as the head, ensuring you start parsing on newline boundaries, so long initial user records cannot hide assistant messages.

Also consider tightening the predicate to parsed.type === "message" && parsed.message.role === "assistant" to avoid accidentally matching non-message records that might contain a message field.

2. 🔵 Extra bootstrap hook execution + bootstrap file loading when contextInjection is meant to skip context (metadata-only path)

Description

In runEmbeddedAttempt, when contextInjection === "first-message-only" and the session already has assistant messages, the code intentionally skips injecting bootstrap context via resolveBootstrapContextForRun(...).

However, it then performs a second call to resolveBootstrapFilesForRun with contextInjection: "always" purely to compute workspaceNotes.

Impact:

• Unexpected extra internal hook execution: resolveBootstrapFilesForRun always invokes applyBootstrapHookOverrides(), which triggers the agent:bootstrap internal hook event. Hook handlers are arbitrary JS/TS code (often workspace-provided) and can perform expensive work or side effects (network/FS).
• DoS/perf risk: This adds an additional hook dispatch per message in this mode, and may force full bootstrap file materialization (including file contents) even though context injection was skipped for token/perf reasons.
• Breaks “skip context” expectations: Even though context files are not injected into the model prompt, this path still loads them and passes them through the hook pipeline, re-introducing side effects and potential sensitive-data handling by hooks.

Vulnerable code (2nd hook-triggering call in skipped mode):

const bootstrapMetadataFiles =
  contextInjection === "first-message-only" && hasExistingAssistantMessages
    ? await resolveBootstrapFilesForRun({
        ...,
        contextInjection: "always",
        hasExistingAssistantMessages: false,
      })
    : hookAdjustedBootstrapFiles;

Relevant behavior: resolveBootstrapFilesForRun unconditionally triggers the internal hook event:

• applyBootstrapHookOverrides(...) → triggerInternalHook(event)

This makes the metadata-only check a hook execution sink.

Recommendation

Avoid running the full bootstrap resolution + hook pipeline just to detect whether BOOTSTRAP.md exists.

Mitigations (choose one):

1. Direct filesystem existence check (no hooks, no file content load):

import fs from "node:fs/promises";
import path from "node:path";

const hasBootstrap = await fs
  .access(path.join(effectiveWorkspace, "BOOTSTRAP.md"))
  .then(() => true)
  .catch(() => false);

2. Add a metadata-only API (e.g., resolveBootstrapFileMetadataForRun) that returns {name, missing} without reading file contents and without calling applyBootstrapHookOverrides.

3. If hook overrides are required, add a flag to resolveBootstrapFilesForRun like skipHooks: true and use it for metadata-only checks.

Also consider caching by sessionId when sessionKey is absent to avoid repeated reads during long sessions.

Analyzed PR: #40372 at commit 34cbb95

_{Last updated on: 2026-03-13T08:45:38Z}

Closing this PR because the author has more than 10 active PRs in this repo. Please reduce the active PR queue and reopen or resubmit once it is back under the limit. You can close your own PRs to get back under the limit.

To use Codex here, create an environment for this repo.