Support context-inheriting subagents in headless mode without silent fallback

[DragonnZhang]

What would you like to be added?

Support real parent-context inheritance for subagents in non-interactive/headless execution, including qwen -p / qwen --prompt, SDK headless sessions, CI/CD, and automated evaluation harnesses.

Today, an explicit subagent_type: "fork" request is only honored when Config.isInteractive() is true. In headless mode it is silently downgraded to a fresh general-purpose subagent. The requested execution mode and the effective execution mode therefore differ without a user-visible error.

The desired behavior is:

1. Make context-inheriting subagents available in headless mode, with permission behavior appropriate for non-interactive execution.
2. Decouple history selection from TUI-only progress and permission UI. Ideally, the same regular subagent execution path could explicitly select fork_turns: "all", "none", or a positive number of recent turns, keeping lifecycle, tools, result delivery, and other behavior identical.
3. If a requested inheritance mode cannot be honored, fail clearly with a structured unsupported-mode error or warning. Do not silently run a different fresh-context agent.
4. Surface the effective context mode in logs/events/telemetry so automated callers can verify what actually ran.
5. Add coverage for qwen -p, SDK headless, and CI-style execution.

Why is this needed?

Headless execution is a first-class Qwen Code surface for CI, SDK integrations, Harbor/Agent Platform evaluations, and other automation. These environments need subagents just as much as the interactive TUI does.

The current fallback is especially risky because fork has a strong semantic promise: it inherits the parent conversation. A caller can explicitly request subagent_type: "fork", receive no error, and unknowingly run a fresh-context general-purpose subagent instead. This can cause incorrect behavior and makes controlled evaluations such as “inherited context vs fresh context” invalid—the two experimental arms may execute the same fresh-context behavior.

Interactive permission bubbling and progress display are legitimate concerns, but they should not require disabling context inheritance itself. Headless callers already have explicit approval policies and structured output/error channels that can define safe behavior.

This request is distinct from:

• Enable the fork subagent by default and let default agents bubble permission prompts #4956, which discusses enabling fork by default while explicitly retaining the interactive-only restriction.
• fork subagent hardening: unbounded turn count + permission-gated tool calls silently auto-denied #5734, which addresses turn limits and permission bubbling for interactive detached forks.

Additional context

Verified against origin/main at 9e822d6004d8c489bb4c0cb555a34fc9dca03621.

The current availability gate is in packages/core/src/tools/agent/fork-subagent.ts:

export function isForkSubagentEnabled(config: Config): boolean {
  return config.isInteractive();
}

The dispatch path in packages/core/src/tools/agent/agent.ts explicitly converts an unavailable fork request to DEFAULT_BUILTIN_SUBAGENT_TYPE and only writes a debug log:

const effectiveSubagentType = isFork
  ? undefined
  : isForkRequested
    ? DEFAULT_BUILTIN_SUBAGENT_TYPE
    : (requestedType ?? DEFAULT_BUILTIN_SUBAGENT_TYPE);

This is observable in Harbor-style automation because the Qwen Code runner starts the CLI with qwen --prompt=..., making the session non-interactive.

A robust design should make the context choice independently testable. Comparing the current detached fork with a regular subagent changes more than context inheritance—background lifecycle and result delivery differ too—so a history-selection option on the same underlying subagent path would enable cleaner behavior and evaluation.

[qwen-code-ci-bot]

Triage

• Type: feature
• Labels: type/feature-request, category/core, scope/non-interactive, priority/P2, roadmap/subagents-tools, roadmap/background-automation
• Next: accept for exploration — silent fallback fix is the high-value incremental step; full headless fork needs design discussion

Problem verified: the code confirms the silent downgrade. isForkSubagentEnabled() gates on config.isInteractive(), and the dispatch path in agent.ts falls back to DEFAULT_BUILTIN_SUBAGENT_TYPE with only a debugLogger.debug() call — no user-visible error or structured warning.

Related issues: distinct from #4956 (enable fork by default in interactive, closed) and #5734 (interactive fork hardening, closed). This issue specifically targets headless/CI execution.

Direction assessment: aligned. Headless execution (qwen -p, SDK, CI) is a first-class surface, and the silent fallback violates the principle of least surprise for automation callers. The proposed fork_turns history-selection decoupling is a clean design direction.

Suggested incremental path: point 3 alone (fail clearly with a structured error/warning instead of silent downgrade) is a small, high-value change that addresses the most dangerous aspect. Points 1–2 (actually enabling context inheritance in headless) are the larger feature that warrants a design doc given core infrastructure involvement.

中文说明

• 类型: feature
• 标签: type/feature-request, category/core, scope/non-interactive, priority/P2, roadmap/subagents-tools, roadmap/background-automation
• 下一步: 接受探索——静默回退修复是高价值增量步骤；完整 headless fork 需要设计讨论

问题已验证：代码确认了静默降级行为。isForkSubagentEnabled() 以 config.isInteractive() 为门控，agent.ts 中的分发路径回退到 DEFAULT_BUILTIN_SUBAGENT_TYPE，仅写 debugLogger.debug()——无用户可见错误或结构化警告。

相关 issue：与 #4956（在交互模式默认启用 fork，已关闭）和 #5734（交互式 fork 加固，已关闭）不同。本 issue 专门针对 headless/CI 执行。

方向评估：对齐。Headless 执行（qwen -p、SDK、CI）是一等公民，静默回退违反最小惊讶原则。提议的 fork_turns 历史选择解耦是干净的设计方向。

建议增量路径：仅第 3 点（以结构化错误/警告替代静默降级）就是一个小而高价值的改动，解决最危险的方面。第 1–2 点（在 headless 中实际启用上下文继承）是更大的功能，鉴于涉及核心基础设施，需要设计文档。

— Qwen Code · qwen3.7-max