Configurable background task limit / queued subagents for multi-agent workflows

[Phantomthedog]

Summary

Kimi CLI appears to have a hard concurrency limit of 4 background/subagent tasks. When a workflow tries to launch a 5th subagent, the 5th task fails with a "too many background tasks" style error instead of being queued or handled gracefully.

This blocks larger planned multi-agent workflows where the task has been intentionally divided into 5 or more specialized subagents.

Environment

• Kimi CLI running in WSL
• Multi-subagent workflow
• 4 subagents started successfully
• 5th subagent failed because of background task limit

Observed behavior

The CLI successfully started 4 subagents:

• Subagent A: Alchemist WordPress
• Subagent B: Google Ads
• Subagent C: OpenClaw
• Subagent D: Infra + Skills

When trying to start the 5th subagent:

• Subagent E: Future Project Coordinator

the task failed because there were already too many background tasks.

Relevant output:

Used TaskList (active)
  agent-11tu8kjc [running] Subagent D: Infra + Skills
  agent-kh1freha [running] Subagent C: OpenClaw
  agent-38suvuzr [running] Subagent B: Google Ads
  agent-cw8ku7m9 [running] Subagent A: Alchemist WordPress

4 subagents are running. The 5th (Subagent E) failed because of too many background tasks. I need to wait for one to complete before starting Subagent E.

The CLI then continued checking task output and waiting:

Used TaskOutput (agent-cw8ku7m9)
  agent-cw8ku7m9 [running] Subagent A: Alchemist WordPress

Used TaskOutput (agent-38suvuzr)
  agent-38suvuzr [running] Subagent B: Google Ads

Used TaskOutput (agent-kh1freha)
  agent-kh1freha [running] Subagent C: OpenClaw

Used TaskOutput (agent-11tu8kjc)
  agent-11tu8kjc [running] Subagent D: Infra + Skills

All 4 subagents are running and reading files. I need to wait for at least one to finish so I can start Subagent E.
Used Shell (sleep 15 && echo "checking...")

Reproduced: 15-agent swarm test (2026-05-04)

The limit was reproduced with a controlled test attempting to launch 15 subagents simultaneously, each running a simple count-1-to-10 task with a 10-second pause between each number (~90-100 seconds per agent).

Launch results

Agent #1  - Started (4fq6oz2g / a20836732)
Agent #2  - Started (qgbt4qda / a038b32b7)
Agent #3  - Started (u2dq2bwh / a48b6f53b)
Agent #4  - Started (tixysjt3 / a96f1addf)
Agent #5  - ERROR: Too many background tasks are already running
Agent #6  - ERROR: Too many background tasks are already running
Agent #7  - ERROR: Too many background tasks are already running
Agent #8  - ERROR: Too many background tasks are already running
Agent #9  - ERROR: Too many background tasks are already running
Agent #10 - ERROR: Too many background tasks are already running
Agent #11 - ERROR: Too many background tasks are already running
Agent #12 - ERROR: Too many background tasks are already running
Agent #13 - ERROR: Too many background tasks are already running
Agent #14 - ERROR: Too many background tasks are already running
Agent #15 - ERROR: Too many background tasks are already running

Summary

Agents	Result
#1-#4	Started and running
#5-#15	Rejected with "Too many background tasks are already running"

11 out of 15 agents (73%) were instantly rejected with no queuing, no backpressure, and no suggestion to retry. The 4 that started would take ~90-100 seconds each to complete.

Expected behavior

One of the following would be better:

1. Allow more than 4 concurrent background/subagent tasks.
2. Expose the background task limit clearly in the CLI or config.
3. Allow users to configure the max number of background tasks.
4. Automatically queue the 5th and later subagent tasks instead of failing them.
5. Avoid indefinite polling/waiting behavior when the planned workflow is blocked by the concurrency limit.

Why this matters

For larger codebase or workspace review tasks, it is useful to split work across 5+ specialized subagents.

In this case, the planned review was intentionally divided into:

• WordPress
• Google Ads
• OpenClaw
• Infrastructure + Skills
• Future Project Coordinator

The 4-task limit prevented the full planned coverage from running.

Suggested improvement

Please consider adding a configurable setting such as:

kimi --max-background-tasks 8

or a config option like:

{
  "maxBackgroundTasks": 8
}

At minimum, it would help if the CLI surfaced the limit explicitly and queued extra subagent tasks rather than failing them.

[ktwu01]

Hit this myself while skimming for related issues. Two findings worth surfacing before any code lands:

1. The 4-task limit is already configurable — just not discoverable

The "Too many background tasks are already running" error in your repro comes from src/kimi_cli/background/manager.py:164:

if self._active_task_count() >= self._config.max_running_tasks:
    raise RuntimeError("Too many background tasks are already running.")

The config field is in src/kimi_cli/config.py:101:

class BackgroundConfig(BaseModel):
    max_running_tasks: int = Field(default=4, ge=1)

So in your kimi config (TOML), this should already work today:

[background]
max_running_tasks = 16

If it doesn't — that's a real bug to fix first, but the option exists. The user-visible problem is that the error message doesn't say "raise [background] max_running_tasks in config to allow more", so users hit the limit and conclude it's a hard wall.

Smallest possible PR (purely DX, no semantic change):

# src/kimi_cli/background/manager.py:164
if self._active_task_count() >= self._config.max_running_tasks:
    raise RuntimeError(
        f"Too many background tasks are already running "
        f"(limit: {self._config.max_running_tasks}). "
        f"Increase via [background] max_running_tasks in your config, "
        f"or wait for a task to finish."
    )

Two-line fix for the second raise at line 227 too. Surfaces the limit + the knob. Happy to send this PR — it's a 4-line change and unblocks the agent in this issue's repro from infinite-polling without needing the bigger queueing work.

2. Queueing vs. raising is a real design choice — Claude Code's Agent View is one reference

For reference, Claude Code's "agent view" model (claude agents, see https://code.claude.com/docs/en/agent-view) takes a different approach: it has no hard concurrency cap on dispatch. Sessions just start, isolated under .claude/worktrees/<id>/, and a supervisor process keeps them alive. The user is the rate-limiter. Their --capacity 32 flag exists on the server-mode bridge, not on per-tool-call dispatch.

That suggests two design directions for kimi-cli:

Option A (small): keep the cap, add queueing.
When _active_task_count() >= max_running_tasks, push the task onto an asyncio.Queue and start it when an active task completes. The agent's tool-call returns immediately with status queued instead of error, and task_view includes the queue position. Resolves the "agent infinite-polls trying to start subagent E" pathology in this issue's repro because the agent gets a successful queued status and can move on.

Option B (larger): isolate sub-agent writes via worktrees, lift the cap, and rate-limit the LLM provider instead of the local process count.
Every sub-agent gets a git worktree add .claude/worktrees/<task_id>. The "rate limit" then becomes whatever your LLM provider's concurrency caps are (which is the real scarce resource — a sub-agent isn't expensive locally, it's expensive in tokens). This matches Claude Code's worktree-isolated background model. Bigger change to BackgroundTaskManager, but unblocks 10+ agent swarms cleanly. Per CONTRIBUTING.md this would need maintainer alignment first.

My recommendation: ship the 4-line error-message fix immediately so users find the existing knob, then have the design discussion about A vs. B in this issue or a separate RFC. The MVP unblocks everyone today; the bigger work happens with maintainer input on which direction matches the Kimi CLI roadmap.

Happy to send the small error-message PR if that's the right next step.