fix(core): preserve background agent launch flags

[he-yufeng]

What this PR does

Preserves the launch-time background-agent runtime flags in the agent meta sidecar and reapplies them when the interrupted agent is resumed after a process restart.

The persisted allow-list covers the flags from #4884 that affect resumed execution behavior: approval mode, bare mode, sandbox, screen reader mode, model, max session turns, and max tool calls. The resume path applies these overrides before rebuilding the child tool registry, so a restored bare-mode agent gets the matching tool surface instead of only restored getter values.

Why it's needed

Today the resume path creates the resumed agent config through prototype delegation from the current parent session. That means an agent launched with one runtime shape can resume with the flags from a later parent process. For example, a background agent originally launched with a sandbox or a specific model can silently resume without that sandbox or under the parent's new model.

This keeps old sidecars backward compatible: sidecars without the new persisted flag snapshot continue to fall back to the current behavior. Existing resolvedApprovalMode reconciliation, including folder-trust downgrades, is preserved.

Reviewer Test Plan

How to verify

Run the focused core tests around background-agent resume and agent config overrides. The new tests assert that persisted flags are written at launch, restored during resume, and applied before tool-registry rebuild.

Commands used locally:

npm ci
npm run test --workspace=packages/core -- agents/background-agent-resume.test.ts tools/agent/agent-override.test.ts tools/agent/agent.test.ts
npm run typecheck --workspace=packages/core
npx eslint packages/core/src/agents/agent-transcript.ts packages/core/src/agents/background-agent-resume.ts packages/core/src/agents/background-agent-resume.test.ts packages/core/src/tools/agent/agent.ts packages/core/src/tools/agent/agent-override.test.ts packages/core/src/tools/agent/agent.test.ts --max-warnings 0
git diff --check upstream/main..HEAD

Evidence (Before & After)

N/A — this is a non-UI runtime correctness fix. The added tests cover the before/after behavior directly.

Tested on

OS	Status
🍏 macOS	N/A
🪟 Windows	✅ tested
🐧 Linux	N/A

Environment (optional)

Windows 11, Node/npm from the local development environment.

Risk & Scope

• Main risk or tradeoff: this extends the meta sidecar schema. The field is optional and the resume path still supports older sidecars.
• Not validated / out of scope: end-to-end process-kill/resume through the TUI; covered here with unit-level resume tests instead.
• Breaking changes / migration notes: none expected.

Linked Issues

Fixes #4884

中文说明

这个 PR 做了什么

这个 PR 会把 background agent 启动时的运行 flag 保存到 agent meta sidecar，并在进程重启后 resume 该 agent 时重新应用这些 flag。

持久化的 allow-list 覆盖 #4884 中会影响恢复执行行为的 flag：approval mode、bare mode、sandbox、screen reader mode、model、max session turns 和 max tool calls。resume 路径会在重建子 agent 的 tool registry 之前应用这些 override，所以恢复 bare-mode agent 时拿到的是匹配的工具集，而不只是 getter 值被恢复。

为什么需要

当前 resume 路径通过原型链从当前父会话派生 resumed agent config。这会导致一个用旧 flag 启动的 background agent，在之后的父进程里被恢复时悄悄继承新的父会话 flag。例如原本带 sandbox 或指定 model 启动的 agent，可能恢复成没有 sandbox 或使用父会话的新 model。

这个改动保持旧 sidecar 兼容：没有新 flag 快照的旧 sidecar 仍然走当前 fallback 行为。现有 resolvedApprovalMode 调和逻辑，包括 folder trust 被撤销时的降级，也保持不变。

Reviewer Test Plan

如何验证

运行 background-agent resume 和 agent config override 的核心测试。新增测试会验证启动时写入持久化 flag、resume 时恢复 flag，以及在 tool registry 重建前应用 flag。

本地已运行：

npm ci
npm run test --workspace=packages/core -- agents/background-agent-resume.test.ts tools/agent/agent-override.test.ts tools/agent/agent.test.ts
npm run typecheck --workspace=packages/core
npx eslint packages/core/src/agents/agent-transcript.ts packages/core/src/agents/background-agent-resume.ts packages/core/src/agents/background-agent-resume.test.ts packages/core/src/tools/agent/agent.ts packages/core/src/tools/agent/agent-override.test.ts packages/core/src/tools/agent/agent.test.ts --max-warnings 0
git diff --check upstream/main..HEAD

Evidence（Before & After）

N/A。这是非 UI 的运行时正确性修复，新增测试直接覆盖 before/after 行为。

Tested on

OS	Status
🍏 macOS	N/A
🪟 Windows	✅ tested
🐧 Linux	N/A

Environment（可选）

Windows 11，本地开发环境中的 Node/npm。

风险与范围

• 主要风险或取舍：扩展了 meta sidecar schema。新字段是 optional，resume 路径仍兼容旧 sidecar。
• 未验证 / 不在范围内：没有做完整 TUI 进程 kill/resume 的端到端测试；本 PR 用 resume 单测覆盖该路径。
• 破坏性变更 / 迁移说明：预期没有。

关联 Issue

Fixes #4884

[wenshao]

No review findings. Downgraded from Approve to Comment: CI still running. — qwen3.7-max via Qwen Code /review

[wenshao]

@qwen-code /triage

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓ — all required sections present, bilingual, test plan included.

On direction: this is a clear correctness fix. Background agents silently inheriting the parent session's flags on resume is a real bug — an agent launched with sandbox or a specific model should resume with those same settings, not whatever the parent happens to have now. Claude Code shipped the exact same fix ("Background sessions now preserve --ide, --chrome, --bare, --remote-control, and other flags across retire→wake"). Strong alignment with the project's session-management roadmap.

On approach: the scope is tight and appropriate. Extending AgentMeta with an optional persistedCliFlags field, capturing at launch, and reapplying before tool-registry rebuild on resume is the minimal correct fix. Backward compatibility with old sidecars is handled cleanly via the ?? fallback on resolvedApprovalMode. The allow-list approach (typed interface, not a config blob) keeps the schema explicit and reviewable. +227/-4 across 6 files, with ~120 lines being tests — nothing feels over-scoped.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓ — 所有必要章节齐全，中英双语，包含测试计划。

方向：这是一个明确的正确性修复。background agent 在 resume 时悄悄继承父会话的 flag 是真实 bug——用 sandbox 或特定 model 启动的 agent，恢复时应该保持原设置，而不是变成父会话当前的配置。Claude Code 已经发布了完全相同的功能（"Background sessions now preserve --ide, --chrome, --bare, --remote-control, and other flags across retire→wake"）。与项目的 session-management 路线图高度对齐。

方案：范围紧凑合理。在 AgentMeta 增加可选的 persistedCliFlags 字段，启动时捕获，resume 时在 tool registry 重建前重新应用——这是最小正确修复。通过 resolvedApprovalMode 的 ?? fallback 兼容旧 sidecar。allow-list 方式（类型化接口而非 config blob）让 schema 保持显式可审查。+227/-4 跨 6 个文件，其中约 120 行是测试——没有过度扩大范围。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

Code Review

I read the PR description and independently proposed how I'd solve this before looking at the diff. My approach: extend AgentMeta with a typed flags snapshot, capture at writeAgentMeta in agent.ts, and reapply in the resume path before rebuildToolRegistryOnOverride. The PR's implementation matches this exactly — and does it cleanly.

What I looked at:

The core logic lives in three functions: capturePersistedCliFlags (snapshot at launch), applyPersistedCliFlagOverrides (restore on resume), and the resume path's integration in background-agent-resume.ts.

No blockers found. A few observations:

• The hasOwn helper for sandbox is necessary and correct — JSON round-trips undefined to missing, so we need to distinguish "not set" from "explicitly null" to avoid overriding a sandbox that was intentionally disabled.
• approvalMode appears in both persistedCliFlags and the top-level resolvedApprovalMode. The resume path uses meta.resolvedApprovalMode ?? meta.persistedCliFlags?.approvalMode — this preserves the existing reconciliation logic (including folder-trust downgrades) while supporting the new field. Clean separation.
• The applyPersistedCliFlagOverrides function uses the same prototype-patching pattern already established by createApprovalModeOverride — consistent with the codebase's conventions.
• The new ApprovalModeOverrideOptions parameter on createApprovalModeOverride is backward compatible (defaults to {}).

Test Results

All focused tests pass:

$ cd packages/core && npx vitest run src/agents/background-agent-resume.test.ts src/tools/agent/agent-override.test.ts src/tools/agent/agent.test.ts

 ✓ src/agents/background-agent-resume.test.ts (22 tests) 326ms
 ✓ src/tools/agent/agent-override.test.ts   (9 tests)  79ms
 ✓ src/tools/agent/agent.test.ts           (101 tests) 407ms

 Test Files  3 passed (3)
      Tests  132 passed (132)

Typecheck and lint clean:

$ cd packages/core && npx tsc --noEmit
(no output — clean)

$ npx eslint packages/core/src/agents/agent-transcript.ts packages/core/src/agents/background-agent-resume.ts \
    packages/core/src/agents/background-agent-resume.test.ts packages/core/src/tools/agent/agent.ts \
    packages/core/src/tools/agent/agent-override.test.ts packages/core/src/tools/agent/agent.test.ts \
    --max-warnings 0
(no output — clean)

Real-Scenario Testing

Attempted E2E via tmux with npm run dev -- -p '...' --approval-mode yolo. The headless parent session processed the prompt directly instead of dispatching a background agent, so the full kill/resume cycle wasn't reachable in this mode.

However, the unit test artifacts confirm the sidecar is being written correctly at launch:

$ cat /tmp/qwen-test/subagents/test-session-id/agent-file-search-404e2c29.meta.json | python3 -m json.tool
{
    "agentId": "file-search-404e2c29",
    "agentType": "file-search",
    "description": "Search files",
    "parentSessionId": "test-session-id",
    "parentAgentId": null,
    "createdAt": "2026-06-13T00:22:13.342Z",
    "status": "completed",
    "lastUpdatedAt": "2026-06-13T00:22:13.392Z",
    "resolvedApprovalMode": "auto-edit",
    "persistedCliFlags": {
        "approvalMode": "auto-edit",
        "bare": false,
        "sandbox": null,
        "screenReader": false,
        "model": "parent-model",
        "maxSessionTurns": -1,
        "maxToolCalls": -1
    },
    "subagentName": "file-search",
    "resumeCount": 0
}

The persistedCliFlags field is present and correctly populated at launch time. The resume path's restoration of these flags is covered by the restores persisted launch flags while resuming an agent test, which asserts each getter returns the persisted value after resume.

Tmux Capture

runner@runnervm1li68:~/work/qwen-code/qwen-code$ npm run dev -- -p 'launch a background agent named test-bg with --bare mode to list files in the current directory' --approval-mode yolo 2>&1 | tee tmp/triage-test-5061/run.log

> @qwen-code/qwen-code@0.18.0 dev
> node scripts/dev.js -p launch a background agent named test-bg with --bare mode to list files in the current directory --approval-mode yolo

DEV is set to true, but the React DevTools server is not running. Start it with:

$ npx react-devtools

Warning: running headless with --yolo / approval-mode=yolo and no sandbox. All tool calls (shell, write, edit) auto-execute at this process's privilege level. Enable a sandbox via --sandbox / QWEN_SANDBOX, or set QWEN_CODE_SUPPRESS_YOLO_WARNING=1 to silence this notice.
Background agent completed. The working directory `/home/runner/work/qwen-code/qwen-code` contains:

- **14 hidden items** (config files, `.git`, `.github`, `.qwen`, etc.)
- **14 regular files** (docs like `AGENTS.md`, `README.md`, configs like `package.json`, `tsconfig.json`, `vitest.config.ts`)
- **9 directories** (`dist`, `docs`, `docs-site`, `eslint-rules`, `integration-tests`, `node_modules`, `packages`, `scripts`, `tmp`)
runner@runnervm1li68:~/work/qwen-code/qwen-code$

中文说明

代码审查

在阅读 PR 描述后，我先独立构思了解决方案再对照 diff。我的方案是：扩展 AgentMeta 加类型化 flag 快照，在 agent.ts 的 writeAgentMeta 时捕获，在 resume 路径的 rebuildToolRegistryOnOverride 之前重新应用。PR 的实现与此完全一致，而且做得很干净。

未发现阻塞性问题。hasOwn 辅助函数处理 sandbox 是必要且正确的（JSON 会把 undefined 转为缺失，需要区分"未设置"和"显式 null"）。approvalMode 在 persistedCliFlags 和顶层 resolvedApprovalMode 中都有出现，resume 路径通过 ?? 正确处理了向后兼容。

测试结果

所有 132 个测试通过，typecheck 和 lint 均无问题。

真实场景测试

通过 tmux 尝试了 E2E 测试，但 headless 父会话直接处理了 prompt 而未派发 background agent，因此无法触发完整的 kill/resume 流程。不过单元测试产物确认 sidecar 在启动时被正确写入（见上方 JSON），resume 路径的 flag 恢复由专门的测试用例覆盖。

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

Reflection

Stepping back: this PR fixes a genuine correctness bug where background agents silently lose their launch-time configuration on process restart. The impact is real — an agent launched with sandbox protection could resume without it, or silently switch to a different model. These are the kinds of bugs that are hard to notice and harder to debug.

My independent proposal matched the PR's approach exactly: typed flag snapshot in AgentMeta, capture at launch, restore before tool-registry rebuild. The implementation is faithful to this design and doesn't add anything extraneous.

What I'm confident about:

• The bug is real and the fix addresses it directly
• The scope is minimal — every changed line serves the fix
• Backward compatibility is handled (old sidecars without persistedCliFlags still work)
• All 132 tests pass, typecheck and lint are clean
• The sidecar is correctly writing the flags at launch (confirmed from test artifacts)
• The code follows the project's existing patterns (prototype-patching for Config overrides)

What I'd note:

• E2E testing of the full kill/resume cycle wasn't achievable in headless mode — the model chose to handle the prompt directly rather than dispatching a background agent. The unit tests cover the resume path thoroughly, but a manual TUI test by a maintainer would add confidence.
• The persistedCliFlags schema is an allow-list, not a full config snapshot. This is the right choice (explicit, reviewable), but future flags need to be added here manually. That's a feature, not a bug — it forces conscious decisions about what survives restart.

Verdict: approve. This is a clean, well-tested correctness fix that ships what it promises.

中文说明

反思

这个 PR 修复了一个真实的正确性 bug：background agent 在进程重启后会悄悄丢失启动时的配置。影响是实际的——带 sandbox 启动的 agent 可能恢复后失去 sandbox 保护，或者悄悄切换到不同的 model。这类 bug 难以发现，更难调试。

我独立构思的方案与 PR 实现完全一致：在 AgentMeta 中加入类型化 flag 快照，启动时捕获，resume 时在 tool registry 重建前恢复。实现忠于设计，没有多余内容。

确认：bug 真实且修复直接命中；范围最小化；向后兼容处理得当；132 个测试全部通过，typecheck 和 lint 干净；sidecar 在启动时正确写入 flag（从测试产物确认）；代码遵循项目现有模式。

注意：headless 模式下无法完成完整的 kill/resume E2E 测试（模型直接处理了 prompt 而未派发 background agent）。单元测试充分覆盖了 resume 路径，但维护者做一次手动 TUI 测试会增加信心。

结论：通过。这是一个干净、测试充分的正确性修复。

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[wenshao]

Local end-to-end verification report (maintainer test pass)

Built this PR locally and exercised the real TUI kill/resume flow under tmux with live model sessions — the exact end-to-end path the PR lists as "not validated / out of scope". The fix works as described, including the legacy-sidecar fallback. LGTM from a runtime-behavior standpoint. This also adds the macOS datapoint missing from the PR's test matrix.

Environment: PR head da53ec2, local bundle (dist/cli.js, v0.18.0), macOS (darwin 25.5), Node v22.22.2, live API sessions, --openai-logging enabled so every request body (including its model field) is captured on disk as hard evidence. Test workspace: a scratch project with a lab-worker subagent (no model: in its definition, so it follows the parent config — the field this PR must preserve).

Test design

The key trick: session B (the resuming parent) was deliberately started with a model that is unauthorized in my environment (-m qwen3.6-flash). Under the old behavior the resumed agent inherits the new parent's model and would fail its very first API call; with this fix it must keep its launch-time qwen3.7-max and succeed. Both outcomes are unambiguously observable.

#	Scenario	Result
T1	Launch-time snapshot. Session A: -m qwen3.7-max --max-session-turns 37 (settings: approvalMode: yolo), launch lab-worker in background (sleep 120 task), inspect meta sidecar	✅ persistedCliFlags written with all 7 fields, each correct: approvalMode: "yolo", bare: false, sandbox: null, screenReader: false, model: "qwen3.7-max", maxSessionTurns: 37, maxToolCalls: -1
T2	Kill + cross-flag resume (core). tmux kill-session mid-sleep (meta stays running) → session B: -m qwen3.6-flash --max-session-turns 200 --resume <id> → "Recovered 1 interrupted background agent" → background-tasks dialog → r	✅ Agent resumed and ran to completion (DONE-SLEEPING, meta completed, resumeCount: 1). Request logs: both post-resume agent requests sent model: qwen3.7-max while the parent session's own turn failed with API Error: 该模型需要授权, model: qwen3.6-flash — same screen, perfect A/B contrast. Without this PR the agent would have died with exactly that parent error.
T3	Legacy-sidecar fallback. Launched a second agent, killed the session, hand-stripped persistedCliFlags from the meta (simulating a sidecar written by a pre-PR build), resumed from a new parent (--max-session-turns 99)	✅ No crash, resume proceeds under current-parent config (the documented fallback), agent completed (DONE-SLEEPING-2, resumeCount: 1), and no persistedCliFlags was spuriously re-introduced into the patched meta
T4	Unit tests from the PR's validation list (background-agent-resume.test.ts, agent-override.test.ts, agent.test.ts)	✅ 3 files, 132 tests pass locally (CI is also green on all three OS runners)

Request-log timeline for the resumed agent (T2), logs/openai/*subagent-lab-worker*:

00:35:46  qwen3.7-max   launch, session A (parent model qwen3.7-max)
00:35:49  qwen3.7-max   launch, session A
-- kill; session B starts with -m qwen3.6-flash --
00:38:35  qwen3.7-max   first post-resume request  ← restored, not inherited
00:40:37  qwen3.7-max   post-sleep final turn → "DONE-SLEEPING"

Also checked in passing: both writeAgentMeta call sites (background and foreground launch paths) capture the snapshot consistently; the snapshot survives post-resume meta patches (persistedCliFlags still present after completed), so a second kill/resume cycle would still have it.

Scope notes (what this pass did not observe directly)

• bare / sandbox / screenReader restore: not exercisable in this environment (no docker sandbox on this Mac; bare/screen-reader produce no externally observable difference for a headless worker of this shape). Their restore is covered by the PR's unit tests (agent-override.test.ts asserts the rebuilt child registry drops write_file under restored bare: true, and getter values for the rest). The write side of all 7 fields is real-world verified (T1).
• maxSessionTurns / maxToolCalls restore: write side verified live (37 / -1 in the sidecar); the restored getter values are unit-asserted — making a real agent burn 37 turns to observe the cap was not practical.
• The resumed agent re-runs the interrupted tool call (the sleep restarts from zero). That's pre-existing resume semantics, unrelated to this PR — noted so other reviewers aren't surprised by it during testing.

中文版（Chinese version）

本地端到端验证报告（维护者测试）

本地构建本 PR，在 tmux 中以真实模型会话走通了完整的 TUI kill/resume 流程——正是 PR 自述「未验证 / 不在范围内」的端到端路径。修复行为与描述一致，旧 sidecar 兼容回退也成立。从运行时行为角度 LGTM。 同时补上了 PR 测试矩阵中缺失的 macOS 数据点。

环境： PR head da53ec2，本地 bundle（dist/cli.js，v0.18.0），macOS（darwin 25.5），Node v22.22.2，真实 API 会话，启用 --openai-logging 把每个请求体（含 model 字段）落盘作为硬证据。测试工作区为独立临时项目，含一个 lab-worker subagent（定义中不写 model:，使其跟随父 config——这正是本 PR 需要保持的字段）。

测试设计

关键技巧：会话 B（执行 resume 的新父进程）故意使用一个在我环境中未授权的模型（-m qwen3.6-flash）。旧行为下 resumed agent 会继承新父进程的 model，第一次 API 调用就会失败；修复后它必须保持启动时的 qwen3.7-max 并成功。两种结果都可以被无歧义地观察到。

#	场景	结果
T1	启动时快照。 会话 A：-m qwen3.7-max --max-session-turns 37（settings：approvalMode: yolo），后台启动 lab-worker（任务 sleep 120），检查 meta sidecar	✅ persistedCliFlags 七字段完整写入且全部正确：approvalMode: "yolo"、bare: false、sandbox: null、screenReader: false、model: "qwen3.7-max"、maxSessionTurns: 37、maxToolCalls: -1
T2	kill + 跨 flag resume（核心）。 sleep 中途 tmux kill-session（meta 停留 running）→ 会话 B：-m qwen3.6-flash --max-session-turns 200 --resume <id> → 提示 "Recovered 1 interrupted background agent" → 后台任务对话框 → 按 r	✅ Agent 恢复并跑完（DONE-SLEEPING，meta completed，resumeCount: 1）。请求日志：resume 后 2 个 agent 请求全部 model: qwen3.7-max，而父会话自己的轮次报 API Error: 该模型需要授权, model: qwen3.6-flash——同屏 A/B 对照。若无本 PR，agent 会在 resume 第一轮报出与父会话完全相同的错误。
T3	旧 sidecar 回退。 启动第二个 agent，kill 会话，手工从 meta 中删除 persistedCliFlags（模拟 PR 之前版本写出的 sidecar），从新父进程（--max-session-turns 99）resume	✅ 不崩溃，按文档化的回退行为以当前父 config 恢复，agent 跑完（DONE-SLEEPING-2，resumeCount: 1），且修补后的 meta 中没有被误重新写入 persistedCliFlags
T4	PR 验证清单中的单测（background-agent-resume.test.ts、agent-override.test.ts、agent.test.ts）	✅ 3 个文件 132 个测试本地全过（CI 三平台亦全绿）

T2 resumed agent 的请求日志时间线（logs/openai/*subagent-lab-worker*）：

00:35:46  qwen3.7-max   launch，会话 A（父 model qwen3.7-max）
00:35:49  qwen3.7-max   launch，会话 A
-- kill；会话 B 以 -m qwen3.6-flash 启动 --
00:38:35  qwen3.7-max   resume 后第一个请求  ← 恢复而非继承
00:40:37  qwen3.7-max   sleep 结束后的最终轮 → "DONE-SLEEPING"

顺带检查：两处 writeAgentMeta 调用点（后台与前台 launch 路径）一致地捕获快照；快照在 resume 后的 meta patch 中保留（completed 后 persistedCliFlags 仍在），因此第二次 kill/resume 循环仍可使用。

范围说明（本轮未直接观察到的部分）

• bare / sandbox / screenReader 的恢复：本环境无法实测（这台 Mac 没有 docker sandbox；bare/screen-reader 对这种形态的 headless worker 没有外部可观察差异）。其恢复行为由 PR 单测覆盖（agent-override.test.ts 断言恢复 bare: true 后重建的子 registry 不含 write_file，其余字段断言 getter 值）。七字段的写入侧均已真实验证（T1）。
• maxSessionTurns / maxToolCalls 的恢复：写入侧已实测（37 / -1 进 sidecar）；恢复后的 getter 值由单测断言——让真实 agent 烧满 37 轮去观察上限不现实。
• resumed agent 会重放被中断的 tool call（sleep 从零重跑）。这是既有 resume 语义，与本 PR 无关——在此注明以免其他 reviewer 测试时感到意外。