* refactor(cli): replace slash command whitelist with capability-based filtering (Phase 1)
## Summary
Replace the hardcoded ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE whitelist with a
unified, capability-based command metadata model. This is Phase 1 of the slash
command architecture refactor described in docs/design/slash-command/.
## Key changes
### New types (types.ts)
- Add ExecutionMode ('interactive' | 'non_interactive' | 'acp')
- Add CommandSource ('builtin-command' | 'bundled-skill' | 'skill-dir-command' |
'plugin-command' | 'mcp-prompt')
- Add CommandType ('prompt' | 'local' | 'local-jsx')
- Extend SlashCommand interface with: source, sourceLabel, commandType,
supportedModes, userInvocable, modelInvocable, argumentHint, whenToUse,
examples (all optional, backward-compatible)
### New module (commandUtils.ts + commandUtils.test.ts)
- getEffectiveSupportedModes(): 3-priority inference
(explicit supportedModes > commandType > CommandKind fallback)
- filterCommandsForMode(): replaces filterCommandsForNonInteractive()
- 18 unit tests
### Whitelist removal (nonInteractiveCliCommands.ts)
- Remove ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE constant
- Remove filterCommandsForNonInteractive() function
- Replace with CommandService.getCommandsForMode(mode)
### CommandService enhancements (CommandService.ts)
- Add getCommandsForMode(mode: ExecutionMode): filters by mode, excludes hidden
- Add getModelInvocableCommands(): reserved for Phase 3 model tool-call use
### Built-in command annotations (41 files)
Annotate every built-in command with commandType:
- commandType='local' + supportedModes all-modes: btw, bug, compress, context,
init, summary (replaces the 6-command whitelist)
- commandType='local' interactive-only: export, memory, plan, insight
- commandType='local-jsx' interactive-only: all remaining ~31 commands
### Loader metadata injection (4 files)
Each loader stamps source/sourceLabel/commandType/modelInvocable on every
command it emits:
- BuiltinCommandLoader: source='builtin-command', modelInvocable=false
- BundledSkillLoader: source='bundled-skill', commandType='prompt',
modelInvocable=true
- command-factory (FileCommandLoader): source per extension/user origin,
commandType='prompt', modelInvocable=!extensionName
- McpPromptLoader: source='mcp-prompt', commandType='prompt', modelInvocable=true
### Bug fix
MCP_PROMPT commands were incorrectly excluded from non-interactive/ACP modes by
the old whitelist logic. commandType='prompt' now correctly allows them in all
modes.
### Session.ts / nonInteractiveHelpers.ts
- ACP session calls getAvailableCommands with explicit 'acp' mode
- Remove allowedBuiltinCommandNames parameter from buildSystemMessage() —
capability filtering is now self-contained in CommandService
* fix test ci
* fix memory command
* fix: pass 'non_interactive' mode explicitly to getAvailableCommands
- Fix critical bug in nonInteractiveHelpers.ts: loadSlashCommandNames was
calling getAvailableCommands without specifying mode, causing it to default
to 'acp' instead of 'non_interactive'. Commands with supportedModes that
include 'non_interactive' but not 'acp' would be silently excluded.
- Apply the same fix in systemController.ts for the same reason.
- Update test mock to delegate filtering to production filterCommandsForMode()
instead of duplicating the logic inline, preventing divergence.
Fixes review comments by wenshao and tanzhenxin on PR #3283.
* fix: resolve TypeScript type error in nonInteractiveHelpers.test.ts
* fix test ci
* feat(cli): add slashCommands.disabled setting to gate slash commands
Introduces a first-class way for operators to hide and refuse to execute
specific slash commands. Useful for multi-tenant / enterprise / sandboxed
deployments where different users should see different command subsets.
The denylist is sourced from three unioned inputs:
* `slashCommands.disabled` settings key (string[], UNION merge), so
workspace scopes can only add to a denylist set at user or system
scope, never shrink it — matching the shape already used by
`permissions.deny`.
* `--disabled-slash-commands` CLI flag (comma-separated or repeated).
* `QWEN_DISABLED_SLASH_COMMANDS` environment variable.
Matching is case-insensitive against the final (post-rename) command
name, so extension commands are addressable by their disambiguated
form (e.g. `firebase.deploy`). Disabled commands are removed from
`CommandService`'s output, so they disappear from autocomplete and
produce the standard unknown-command path in both interactive TUI and
non-interactive (`--prompt`) modes.
The scope of this change is slash commands only: it does not affect
tool permissions (still `permissions.deny`) or keyboard shortcuts.
* chore(cli): regenerate settings.schema.json for slashCommands.disabled
Regenerates the companion JSON schema consumed by the VS Code extension
after adding the `slashCommands.disabled` entry to the TS schema in the
previous commit. Required by the "Check settings schema is up-to-date"
CI lint step.
* fix(cli): route disabled slash commands to unsupported, not no_command
handleSlashCommand was passing the disabled denylist straight into
CommandService.create, so disabled commands disappeared from
`allCommands` too. The fallback existence check that distinguishes
"known but not allowed in non-interactive mode" from "truly unknown"
then failed, and disabled commands like `/help` fell through to
`no_command` — causing the caller to forward them to the model as
plain prompt text.
Keep `allCommands` unfiltered and apply the denylist only when
constructing the executable set and when producing the unsupported
response. A disabled command now returns `unsupported` with a
"disabled by the current configuration" reason and never reaches the
model. Added three regression tests covering the primary case,
case-insensitive match, and the preserved no_command path for
genuinely unknown input.
* feat(core): add run_in_background support for Agent tool
Enable sub-agents to run asynchronously via `run_in_background: true`
parameter. Background agents execute independently from the parent,
which receives an immediate launch confirmation and continues working.
A notification is injected into the parent conversation when the
background agent completes.
Key changes:
- BackgroundTaskRegistry tracks lifecycle of background agents
- Agent tool gains async execution path with fire-and-forget semantics
- Background agents use YOLO approval mode to prevent deadlock
- Independent AbortControllers survive parent ESC cancellation
- CLI bridges notifications via useMessageQueue for between-turn delivery
- State race guards prevent complete/fail after cancellation
- Session cleanup aborts all running background agents
* feat(background): improve notification formatting and UI handling
- Add prefix/separator protocol to distinguish background notifications from user input
- Show concise summary in UI while sending full details to LLM
- Add 'notification' history item type with specialized display
- Add 'background' agent status for background-running agents
- Prevent notifications from polluting prompt history (up-arrow)
- Truncate long descriptions in display text
This improves the UX for background agents by showing cleaner, more concise
notifications while preserving full context for the LLM.
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* fix(background): reject run_in_background in non-interactive mode
Headless mode skips AppContainer, so the notification callback is never
registered and background agent results would be silently dropped. Return
an error prompting the model to retry without run_in_background.
* refactor(background): replace prefix/separator protocol with typed notification queue
Replace the stringly-typed \x00__BG_NOTIFY__\x00 prefix/separator
encoding with a typed notification path using SendMessageType.Notification.
- Add SendMessageType.Notification to the enum
- Change BackgroundNotificationCallback to emit (displayText, modelText)
- Move notification queue from AppContainer into useGeminiStream (mirrors
the cron queue pattern): register on registry, queue structured items,
drain on idle via submitQuery
- prepareQueryForGemini short-circuits for Notification type (skips slash
commands, shell mode, @-commands, prompt history logging)
- Remove BACKGROUND_NOTIFICATION_PREFIX/SEPARATOR constants
* refactor(background): move abortAll to Config.shutdown
Background agent cleanup belongs in Config.shutdown() alongside other
resource teardown (skillManager, toolRegistry, arenaRuntime), not in
AppContainer's registerCleanup. This also ensures headless mode gets
cleanup for free.
* fix(background): persist notification items for session resume
Background agent notifications were missing after session resume because
they were never recorded in the chat history. The model text was absent
from the API history and the display item was lost.
- Add recordNotification() to ChatRecordingService — stores as user-role
message with subtype 'notification' and displayText payload
- Thread notificationDisplayText through submitQuery → sendMessageStream
- Restore as HistoryItemNotification in resumeHistoryUtils
* fix(background): replace YOLO with deny-by-default for background agents
Background agents were using YOLO approval mode which auto-approves all
tool calls — too permissive. Replace with shouldAvoidPermissionPrompts
which auto-denies tool calls that need interactive approval, matching
claw-code's approach.
The permission flow for background agents is now:
1. L3/L4 permission rules (allow/deny) — same as foreground
2. Approval mode overrides (AUTO_EDIT for edits) — same as foreground
3. PermissionRequest hooks — can override the denial
4. Auto-deny — if no hook decided, deny because prompts are unavailable
* fix(background): add missing getBackgroundTaskRegistry mock in useGeminiStream tests
* refactor(core): move fork subagent params from execute() to construction time
Identity-shaping fork inputs (parent history, generationConfig, tool decls,
env-skip flag) were threaded through `AgentHeadless.execute()`'s options bag
and re-passed by the SubagentStop hook retry loop. They belong on the agent's
construction-time configs, not its per-invocation options.
- PromptConfig gains `renderedSystemPrompt` (verbatim, bypasses templating
and userMemory injection) and drops the `systemPrompt`/`initialMessages`
XOR so fork can carry both. createChat skips env bootstrap when
`initialMessages` is non-empty.
- AgentHeadless.execute() shrinks to (context, signal?). Fork dispatch in
agent.ts builds synthetic PromptConfig/ModelConfig/ToolConfig from the
parent's cache-safe params and calls AgentHeadless.create directly
(bypassing SubagentManager). Parent's tool decls flow through verbatim
including the `agent` tool itself for cache parity.
- Recursive-fork prevention switches from fork-side tool stripping to a
runtime guard. The previous `isInForkChild(history)` helper was dead
code (it scanned the main GeminiClient's history, not the fork child's
chat). Replaced with `isInForkExecution()` backed by AsyncLocalStorage:
the fork's background execution runs inside `runInForkContext`, and the
ALS frame propagates through the standard async chain into nested
AgentTool.execute() calls where the guard fires.
* refactor(core): move agent tool files into dedicated tools/agent/ directory
Move agent.ts, agent.test.ts, and fork-subagent.ts under
tools/agent/ and update all import paths accordingly.
* refactor(core): remove dead temp and top_p fields from ModelConfig
These fields were never populated from subagent frontmatter and served
no purpose in the fork path either. The ModelConfig interface retains
only the actively-used model field.
* refactor(core): read parent generation config directly instead of getCacheSafeParams
Fork subagent now reads system instruction and tool declarations from
the live GeminiChat via getGenerationConfig() instead of the global
getCacheSafeParams() snapshot. This removes the cross-module coupling
between the agent tool and the followup infrastructure.
* fix(core): prevent duplicate tool declarations when toolConfig has only inline decls
prepareTools() treated asStrings.length === 0 as "add all registry tools",
which is correct when no tools are specified at all, but wrong when the
caller provides only inline FunctionDeclaration[] (no string names). The
fork path passes parent tool declarations as inline decls for cache parity,
so prepareTools was adding the full registry set on top — duplicating every
non-excluded tool.
Add onlyInlineDecls.length === 0 to the condition so that pure-inline
toolConfigs bypass the registry entirely.
* feat(core): support agent-level `background: true` in frontmatter
Subagent definitions can now declare `background: true` in their YAML
frontmatter to always run as background tasks. This is OR'd with the
`run_in_background` tool parameter — useful for monitors, watchers, and
proactive agents so the LLM doesn't need to remember to set the flag.
* fix(core): address background subagent lifecycle gaps
- Inherit bgConfig from agentConfig so the resolved approval mode is
preserved for background agents (foreground would run AUTO_EDIT but
background fell back to DEFAULT, which combined with shouldAvoid-
PermissionPrompts would auto-deny every permission request).
- Honor SubagentStop blocking decisions in background runs by looping
on hook output up to 5 iterations, matching runSubagentWithHooks.
- Check terminate mode before reporting completion; non-GOAL modes
(ERROR, MAX_TURNS, TIMEOUT) are now reported as failures instead of
emitting a success notification for an incomplete run.
- Exclude SendMessageType.Notification from the UserPromptSubmit hook
guard so background completion messages are not rewritten or blocked
as if they were user input.
* feat(cli): headless support and SDK task events for background agents (#3379)
* feat(cli): unify notification queue for cron and background agents
Migrate cron from its own queue (cronQueueRef / cronQueue) to the shared
notification queue used by background agents. Both producers now push the
same item shape { displayText, modelText, sendMessageType } and a single
drain effect / helper processes them in FIFO order.
Cron fires render as HistoryItemNotification (● prefix) instead of
HistoryItemUser (> prefix), with a "Cron: <prompt>" display label.
Records use subtype 'cron' for clean resume and analytics separation.
Lift the non-interactive rejection for background agents. Register a
notification callback in nonInteractiveCli.ts with a terminal hold-back
phase (100ms poll) that keeps the process alive until all background
agents complete and their notifications are processed.
* feat(cli): emit SDK task events for background subagents
Emit `task_started` when a background agent registers and
`task_notification` when it completes, fails, or is cancelled, so
headless/SDK consumers can track lifecycle without parsing display
text. Model-facing text is now structured XML with status, summary,
truncated result, and usage stats. Completion stats (tokens, tool
uses, duration) are captured from the subagent and included in both
the SDK payload and the model XML.
* fix: address codex review issues for background subagents
- Background subagents now inherit the resolved approval mode from
agentConfig instead of the raw session config, so a subagent with
`approvalMode: auto-edit` (or execution in a trusted folder) keeps
that override when it runs asynchronously.
- Non-interactive cron drains are single-flight: concurrent cron fires
now await the same in-flight drain, and the cron-done check gates
on it, preventing the final result from being emitted while a cron
turn is still streaming.
- Background forks go through createForkSubagent so they retain the
parent's rendered system prompt and inherited history instead of
degrading to a plain FORK_AGENT.
* fix(cli): restore cancellation, approval, and error paths in queued drain
- Hold-back loop now reacts to SIGINT/SIGTERM: when the main abort
signal fires it calls registry.abortAll() so background agents with
their own AbortControllers stop promptly instead of pinning the
process open.
- Queued-turn tool execution forwards the stream-json approval update
callback (onToolCallsUpdate) so permission-gated tools inside a
background-notification follow-up emit can_use_tool requests.
- Queued-turn stream loop mirrors the main loop's text-mode handling
of GeminiEventType.Error, writing to stderr and throwing so provider
errors produce a non-zero exit code instead of silently succeeding.
- Interactive cron prompts go through the normal slash/@-command/shell
preprocessing again; only Notification messages skip that path.
* fix(cli): skip duplicate user-message item for cron prompts
Cron prompts already render as a `● Cron: …` notification via the queue
drain, so adding them again as a `USER` history item produced a
duplicate `> …` line.
* fix(cli): honor SIGINT/SIGTERM during cron scheduler wait
The non-interactive cron phase awaits a Promise that resolves only when
scheduler.size reaches 0 and no drain is in flight. Recurring cron jobs
never drop the scheduler size to 0 on their own, so the previous abort
handling (added to the hold-back loop) was unreachable — the process
hung indefinitely after SIGINT/SIGTERM. Attach an abort listener inside
the promise so abort stops the scheduler and resolves immediately,
allowing the hold-back loop to run and the process to exit cleanly.
* feat(core): propagate tool-use id through background agent notifications
Plumb the scheduler's callId into AgentToolInvocation via an optional
setCallId hook on the invocation, detected structurally in
buildInvocation. The agent tool forwards it as toolUseId on the
BackgroundTaskRegistry entry so completion notifications can carry a
<tool-use-id> tag and SDK task_started / task_notification events can
emit tool_use_id — letting consumers correlate background completions
back to the original Agent tool-use that spawned them.
* fix(cli): drain single-flight race kept task_notification from emitting
drainLocalQueue wrapped its body in an async IIFE and cleared the
promise reference via finally. When the queue is empty the IIFE has
no awaits, so its finally runs synchronously as part of the RHS of
the assignment `drainPromise = (async () => {...})()` — clearing
drainPromise BEFORE the outer assignment overwrites it with the
resolved promise. The reference then stayed stuck on that fulfilled
promise forever, so later calls short-circuited through
`if (drainPromise) return drainPromise` and never processed
queued notifications.
Symptom: in headless `--output-format json` (and `stream-json`),
task_started emitted but task_notification never did, even after
the background agent completed. The process sat in the hold-back
loop until SIGTERM.
Fix: move the null-clearing out of the async body into an outer
`.finally()` on the returned promise. `.finally()` runs as a
microtask after the current synchronous block, so it clears the
latest drainPromise reference instead of the pre-assignment null.
* fix(cli): append newline to text-mode emitResult so zsh PROMPT_SP doesn't erase the line
Headless text mode wrote `resultMessage.result` without a trailing newline.
In a TTY, zsh themes that use PROMPT_SP (powerlevel10k, agnoster, …) detect
the missing `\n` and emit `\r\033[K` before drawing the next prompt, which
wipes the final line off the screen. Pipe-captured output was unaffected,
so the bug only surfaced for interactive shell users — most visibly in the
background-agent flow where the drain-loop's final assistant message is
the *only* stdout write in text mode.
Append `\n` to both the success (stdout) and error (stderr) writes.
* docs(skill): tighten worked-example blurb in structured-debugging
Mirror the simplified blurb from .claude/skills/structured-debugging/SKILL.md
(knowledge repo). Drops the round-by-round narrative; keeps the contradiction
+ two lessons.
* docs(skill): mirror SKILL.md improvements (reframing failure mode, generalized path, value-logging guidance)
Mirror of knowledge repo commit 38eb28d into the qwen-code .qwen/skills
copy.
* docs(skill): mirror worked example into .qwen/skills/structured-debugging/
Mirrors knowledge/.claude/skills/structured-debugging/examples/
headless-bg-agent-empty-stdout.md so the .qwen copy of the skill links
resolve.
* docs(skill): mirror generalized side-note path guidance
* fix(cli): harden headless cron and background-agent failure paths
Three regressions surfaced by Codex review of feat/background-subagent:
- Cron drain rejections were dropped by a bare `void`, so a failing
queued turn left the outer Promise unresolved and hung the run. Route
drain failures through the Promise's reject so they propagate to the
outer catch.
- The background-agent registry entry was inserted before
`createForkSubagent()` / `createAgentHeadless()` was awaited. Failed
init returned an error from the tool call but left a phantom `running`
entry, and the headless hold-back loop (`registry.getRunning()`) waited
forever. Register only after init succeeds.
- SIGINT/SIGTERM during the hold-back phase aborted background tasks,
then fell through to `emitResult({ isError: false })`, so a cancelled
`qwen -p ...` exited 0 with the prior assistant text. Route through
`handleCancellationError()` so cancellation exits non-zero, matching
the main turn loop.
* test(cli): update stdout/stderr assertions for trailing newline
`feadf052f` appended `\n` to text-mode `emitResult` output, but the
nonInteractiveCli tests still asserted the pre-change strings. Update
the 11 affected assertions to expect the trailing newline.
* fix: address review comments on background-agent notifications
Four additional issues from the PR review that the prior regression-fix
commit didn't cover:
- Escape XML metacharacters when interpolating `description`, `result`,
`error`, `agentId`, `toolUseId`, and `status` into the task-notification
envelope. Subagent output (which itself may carry untrusted tool output,
fetched HTML, or another agent's notification) could contain
`</result>` or `</task-notification>` and forge sibling tags the parent
model would treat as trusted metadata. Truncate result text *before*
escaping so the truncation never slices through an entity like `&`.
- Emit the terminal notification from `cancel()` and `abortAll()`. The
fire-and-forget `complete()`/`fail()` from the subagent task is guarded
by `status !== 'running'` and was no-op'd after cancellation, so SDK
consumers saw `task_started` with no matching `task_notification`,
breaking the contract this PR establishes. Updated two race-guard
tests that asserted the old behavior.
- Call `adapter.finalizeAssistantMessage()` before the abort-triggered
early return inside `drainOneItem`'s stream loop. Without it,
`startAssistantMessage()` had already been called, so stream-json mode
left `message_start` unpaired.
- Enforce `config.getMaxSessionTurns()` in `drainOneItem` for symmetry
with the main turn loop. Cron fires and notification replies otherwise
bypass the budget cap in headless runs.
* fix: address codex review comments for background subagents
- Wrap background fork execute() in runInForkContext so the
recursive-fork guard (AsyncLocalStorage-based) fires when a
background fork's child model calls `agent` again. Previously only
the foreground fork path was wrapped, so background forks could
spawn nested implicit forks.
- Emit queued terminal task_notifications on SIGINT/SIGTERM before
handleCancellationError exits. abortAll() enqueues cancellation
notifications via the registry callback, but the process was
exiting before the drain loop had a chance to flush them — leaving
stream-json consumers that already saw task_started without a
matching terminal task_notification. Extracted the SDK-emit block
into a shared emitNotificationToSdk helper reused by the normal
drain and the cancellation flush.
- Skip notification/cron subtypes in ACP HistoryReplayer. These
records are persisted as type: 'user' so the model's chat history
keeps them for continuity, but they were never user input —
replaying them leaked raw <task-notification> XML (and cron
prompts) back into the ACP session as if the user typed them.
* test(cli): sync JsonOutputAdapter text-mode assertions with trailing newline
Commit 0da1182b7 appended a newline to text-mode emitResult output
(zsh PROMPT_SP fix) and updated the nonInteractiveCli tests, but
four assertions in JsonOutputAdapter.test.ts were missed. Update
them to expect the trailing newline so CI passes.
* refactor: simplify background subagent plumbing
- Extract the SubagentStop hook blocking-decision loop into a
runSubagentStopHookLoop helper so the foreground and background
paths no longer duplicate the iteration/abort/log scaffolding.
- Unify BackgroundTaskRegistry.abortAll to delegate to cancel,
removing copy-pasted abort/notification bookkeeping.
- Drop the unused findByName and BackgroundAgentEntry.name field.
- In nonInteractiveCli drain, hoist inputFormat and
toolCallUpdateCallback out of the inner tool loop, and drop the
unreachable try/catch around the readonly registry.
- Trim boilerplate doc/narration comments while keeping load-bearing
WHY comments.
* fix: address codex review comments for background subagents
- Use tool callId (or short random suffix) instead of Date.now() for
background agentIds; avoids registry collisions when parallel
same-type agents launch in the same millisecond.
- Reset loopDetector and lastPromptId for Notification turns so a
prior turn's loop count doesn't trip LoopDetected on the
notification response.
- Replay notification/cron displayText in ACP HistoryReplayer so
the assistant reply has an antecedent in resumed transcripts.
---------
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Change cron/loop tools from opt-out to opt-in. Cron tools are now
disabled by default and can be enabled via:
- settings.json: { "experimental": { "cron": true } }
- Environment variable: QWEN_CODE_ENABLE_CRON=1
This ensures experimental features are explicitly enabled by users
who want to try them.
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Replace isContinuation boolean with SendMessageType enum for clearer
message type semantics. Add stripOrphanedUserEntriesFromHistory() to
clean up orphaned user entries in chat history before retry operations,
preventing 'messages with role tool must be a response to preceding
message with tool_calls' API errors.
Fixes#2360
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
- Replace ConsolePatcher with centralized debugLogger utility
- Refactor errorReporting to use debugLogger instead of file-based reporting
- Remove user-facing console message components:
- Delete ConsolePatcher.ts, useConsoleMessages.ts/hook
- Delete ConsoleSummaryDisplay.tsx, DetailedMessagesDisplay.tsx
- Update all tests in packages/core and packages/cli:
- Mock debugLogger where needed
- Remove assertions for console output on non-critical errors
- Keep debugLogger assertions for fatal/network errors
- Use HOME directory mocking for hermetic file system tests
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit refactors the telemetry system to pass a object to various logging and metrics functions. This change centralizes configuration management within the telemetry system, making it more modular and easier to maintain.
The constructor and various tool execution functions have been updated to accept the object, which is then passed down to the telemetry functions. This eliminates the need to pass individual configuration values, such as , through multiple layers of the application.
