--append-system-prompt(-file) is silently dropped for background-agent and daemon-respawned sessions

Status Open
Reported on v2.1.219
Maintainer reply None cached
Activity 0 comments · opened Jul 25, 2026

Summary

A system prompt supplied with --append-system-prompt / --append-system-prompt-file is silently lost for sessions that the background-agent daemon spawns or respawns — background agents, /bg dispatch, and --resume through the daemon/desktop app. The parent session has the appended text; its children do not, with no warning.

Verified on 2.1.219 and 2.1.220, macOS.

Reproduction

  1. Start a session with --append-system-prompt-file /path/to/steer.md containing something identifiable.
  2. Confirm it landed: ask the session to quote a heading from that file. It can.
  3. Have that session dispatch a background agent (or resume it via the desktop app / daemon).
  4. Ask the child the same question. The appended text is absent.

Corroborating evidence without needing a model in the loop:

  • respawnFlags in ~/.claude/jobs/*/state.json never contains --append-system-prompt-file, for either the claude or the bg job template — including for jobs created from a parent that was launched with it.
  • ps shows daemon-owned sessions invoked as .../versions/<v> --session-id … --agent … --permission-mode …, with no append flag.

Mechanism

Respawn/dispatch argv is not inherited or filtered from the parent — it is rebuilt from a curated field list, and that list has no entry for this flag:

  • The dispatch-extra-args builder propagates only --settings, --plugin-dir, --plugin-dir-no-mcp, --add-dir, --mcp-config, --strict-mcp-config.
  • The dispatch-defaults builder adds --model, --effort, --permission-mode, --allow-dangerously-skip-permissions, --json-schema, and an inline --append-system-prompt taken from a dispatchDefaults.appendSystemPrompt field — but the claude agents call site never populates that field, and there is no --append-system-prompt-file field at all.

The interesting part: the persisted-state sanitizer allowlist already lists --append-system-prompt, --append-system-prompt-file and --append-subagent-system-prompt as flags safe to keep across a respawn. So the consumer side is ready and the producer side never sets them — the two have drifted. This is a plumbing omission rather than a discard, which is why there is no "stripped flag" to find in a log.

Why it matters beyond tidiness

This is not cosmetic. In an A/B on opus[1m] (7 runs per arm, same task, same cwd), the only difference being whether an appended system prompt was present, the arm without it took a materially different strategy in 7 of 7 runs. Users who rely on --append-system-prompt to steer behaviour get that steer on some sessions and not others, with nothing surfacing the difference — the failure mode is a silent behavioural inconsistency, not an error.

Suggested fix

Populate the existing dispatch field from the parent's already-resolved appended prompt. Since --append-system-prompt-file is read into a string at startup anyway, passing the resolved inline value through the existing appendSystemPrompt field would cover both flags without adding a file-path field or re-reading the file in the child.

Possibly related

  • #58943 — --mcp-config / --settings not preserved across /bg → respawn (closed as duplicate of #50172). Same mechanism family, different flags.
  • #77569 — another respawnFlags defect.

View original on GitHub ↗