Reference

Configuration keys

Key	Default	Notes
`subagents.timeout_seconds`	1800	Default timeout in seconds for built-in subagents
`subagents.max_turns`	unset	Global turn override for built-in subagents
`subagents.max_total_per_run`	6	Delegations per run, 1 to 50
`subagents.token_budget.enabled`	true
`subagents.token_budget.max_tokens`	2,000,000; 1,000,000 when summarization is on	Once set explicitly, no longer coupled to the summarization switch
`subagents.token_budget.warn_threshold`	0.7	At this fraction, warns the model once on its next call
`subagents.agents.<name>.timeout_seconds`		Per-agent override, applies to subagents from any source
`subagents.agents.<name>.max_turns`
`subagents.agents.<name>.model`
`subagents.agents.<name>.skills`		`null` inherits all, `[]` none
`subagents.agents.<name>.token_budget`
`subagents.custom_agents.<name>.*`		`description` and `system_prompt` required; `max_turns` 50, `timeout_seconds` 900
`subagent_runtime.max_running`	3	Process-wide concurrency, 1 to 64, restart required
`subagent_runtime.max_queued`	64	0 to 10,000
`subagent_runtime.admission_policy`	`queue`	`queue` or `reject`
`subagent_runtime.queue_timeout_seconds`	300	1 to 86,400
`subagent_batches.enabled`	false	Requires a SQL database
`subagent_batches.max_items_per_batch`	5,000
`subagent_batches.default_max_live_items`	100	Cap `max_live_items_per_batch` 1,000
`subagent_batches.default_max_running_items`	3	Cap `max_running_items_per_batch` 64
`subagent_batches.max_attempts`	3
`subagent_batches.max_result_chars`	100,000	`result_preview_max_chars` 2,000
`subagent_batches.lease_seconds`	120	`poll_interval_seconds` 1
`acp_agents.<name>.*`		`command` and `description` required; `timeout_seconds` 1800; `auto_approve_permissions` false
`verification.receipts_enabled`	true	Tool receipts and citation verification
`loop_detection.*`	see Limits	Shared with the Lead Agent
`summarization.*`	see Limits	Shared with the Lead Agent
`tool_search.enabled` / `auto_promote_top_k`		Deferred MCP tool loading
`token_usage.enabled`	true	Whether cards show tokens
`agent_storage.backend`	`file`	Where managed subagents are stored, `file` or `db`
`sandbox.allow_host_bash`	false	Whether the `bash` subagent is available under the local sandbox
`sandbox.environment.MAX_SHELL_SESSIONS`	image default 10	Must be at least `subagent_runtime.max_running + 1`
Environment variable `DEER_FLOW_DATE_TIMEZONE`	server timezone	IANA zone used for the `current_date` reminder

Request context keys

Key	Notes
`subagent_enabled`	Whether delegation is allowed; the web UI sets it in Ultra mode
`max_concurrent_subagents`	Per-response concurrency, 1 to 64, capped by `subagent_runtime.max_running`
`max_total_subagents`	Temporary override of the per-run total, 1 to 50
`allowed_subagents`	Not read from the request: comes from the Custom Agent definition, `null` all, `[]` none, a list as allowlist; snapshotted into run metadata at run start

Tool signatures


task(prompt: str, subagent_type: str, *,
     acceptance_criteria: list[str] | None = None,
     description: str = "",
     context_mode: "isolated" | "snapshot" = "isolated")

batch_task(title: str, items: list[{key, prompt, acceptance_criteria?}], subagent_type: str,
           max_live_items: int | None = None, max_running_items: int | None = None)
batch_status(batch_id: str)
cancel_batch(batch_id: str)

invoke_acp_agent(...)   # external ACP agents, see Subagent Catalog

Canonical acceptance criteria: file:<path> exists, file:<path> non-empty, file_written:<path>, tests_passed:<command>. At most 20 entries of 500 characters each.

Statuses and cap reasons

Field	Values
`subagent_status`	`completed`, `failed`, `cancelled`, `timed_out`, `polling_timed_out`
`subagent_stop_reason`	`token_capped`, `turn_capped`, `loop_capped`
Acceptance leaf	Booleans `checked` and `holds`; rendered as `holds` / `does not hold` / `UNVERIFIED`
Receipt verification	`resolved`, `failed`, `unknown`, `no_citation_claims`
Delegation ledger status	`in_progress` plus the five terminal statuses
Batch status	`queued`, `running`, `paused`, `completed`, `failed`, `cancelled`
Batch item status	`pending`, `queued`, `leased`, `running`, `succeeded`, `failed`, `cancelled`

Result text formats: Task Succeeded. Result: ..., Task Succeeded (capped: <label>). Result: ..., Task failed., Task failed (capped: <label>)., Task cancelled by user., Task timed out., Task polling timed out after N minutes. ...; failed, cancelled, and timed_out results may append Error: <detail>.

Tool result metadata keys: subagent_status, subagent_stop_reason, subagent_error, subagent_result_brief, subagent_result_sha256, subagent_model_name, subagent_token_usage, subagent_tool_receipts, subagent_receipt_verdict, subagent_acceptance_verdict. Contract file: contracts/subagent_status_contract.json (version 2).

Events

Kind	Names
SSE custom events	`task_started`, `task_running`, `task_completed`, `task_failed`, `task_cancelled`, `task_timed_out`
Persisted run events	`subagent.start`, `subagent.step`, `subagent.end` (category `subagent`)
Middleware audit	`middleware:loop_detection` (category `middleware`, `changes.is_subagent`, `changes.agent_id`)
Extension lifecycle	`on_task_start` / `on_task_stop`, `TaskInfo.kind = "subagent"`, `TaskOutcome` `completed` / `aborted` / `failed`

HTTP routes

Route	Purpose
`GET/POST /api/subagents`, `PUT/DELETE /api/subagents/{name}`	Managed subagent catalog; `GET` is open to all users (system prompts for administrators only), writes are administrators only
`GET /api/threads/{thread_id}/runs/{run_id}/events`	Run events, filtered by `event_types` and `task_id`
`GET /api/threads/{thread_id}/token-usage`	Thread token usage with `by_model` and `by_caller`
`/api/threads/{thread_id}/subagent-batches/...`	Durable batches, see Observability
`GET /api/models`	Includes `token_usage.enabled`

Change log (June to September 2026)

Pull requests merged to the main branch between June 1 and September 22, 2026 whose titles concern subagents or delegation, newest month first.

September 2026

#5559 Remote acceptance probes recognize empty regular files.
#5507 Close in_progress delegations a stopped run left in the ledger.
#5525 Drain the owned batch service stop across cancellation.
#5221 Close the stream before releasing the sandbox lease on cooperative cancellation.
#5488 create_deerflow_agent gains DurableContextMiddleware, making the per-run total, summarization, and token budget effective.
#5485 Convert max_turns into the super-step budget from middleware node counts.
#5178 Raise AIO MAX_SHELL_SESSIONS to max_running + 1 when that exceeds the image default.
#5477 Shield capacity slot release from repeated cancellation.
#5476 Trim the subagent acceptance checklist agent guidance.
#5454 Keep the subagent system prompt through context compaction.
#5407 A subagent error no longer turns the parent run into error.
#5367 Add the context_mode="snapshot" parent-context snapshot.
#5162 Make acceptance checks portable on Windows.
#5262 Filter the assembly descriptor by allowed_subagents.
#5289 Acceptance criteria on durable batch items.
#5287 Separate execution completion from acceptance; keep unmet examples after compaction.
#5170 Subagents can discover historical uploads.
#5153 UTC-aware result timestamps.
#5134 Per-subagent execution leases and shell sessions.
#5109 Deterministic acceptance checklist for delegations (RFC #4651, layer 2).

August 2026

#5069 Clean up the background task entry when the poller exits unexpectedly.
#5098 Thread-id route contract test covers the batch routes.
#5090 Subagent report contract and delegation acceptance criteria.
#5086 Background registry and capacity snapshot edge cases.
#5076 Receipt citation verification.
#4998 Unified process capacity and durable batch execution.
#4887 Managed subagent catalog and Custom Agent delegation scopes.
#4928 Strong references for deferred cleanup tasks.
#4797 Isolated date-only context.
#4758 Key the background registry by a server-side execution id.

July 2026

#4384 Route subagents by net benefit.
#4497 Isolate parent callbacks and activate skills lazily.
#4440 Document runaway guards and the token budget.
#4081 Concurrency floor lowered to 1.
#4356 Load user-scoped skills.
#4215 Inherit the parent checkpoint namespace.
#4161 The general-purpose prompt declares task unavailable.
#4157 Escape subagent descriptions before the prompt.
#4115 Per-run delegation total cap.
#4056 , #4042 Classify LLM error fallbacks as failed.
#4059 Keep loop_capped when run_id is None.
#4082 Re-buffer subagent events on flush failure.
#4049 Show model and token usage on task cards.
#4040 Inject durable context before compaction.
#4009 Inherit the summarization middleware (#3875 phase 3).
#3980 Unify subagent_stop_reason and add the token budget (phase 2).
#3949 Keep the partial result when turns run out (phase 2).
#3931 Inherit loop detection (phase 1).
#3845 Persist and display step history.
#3877 System-maintained delegation ledger.

June 2026

#3687 Deduplicate streamed messages with a set.
#3639 No stale running state on subtask cards after stop.
#3611 Attribute Langfuse spans to the parent thread session.
#3610 Raise general-purpose turns to 150 and the timeout to 30 minutes.
#3559 Compile subgraphs with checkpointer=False.
#3432 Deferred MCP tool loading for subagents.
#3154 Structured subagent_status field.

Titles without “subagent” that changed subagent paths: #4659 tool receipts (RFC #4651, layer 1), #3887 and #3906 durable context, #4407 subgraph stream frames, #4432 card ordering, #5436 token budget signals without a run_id, #5447 provider blocks after guards strip calls, #5563 content-less terminal messages, #3658 per-model token attribution, #5127 loop detection events, #4636 and #4684 extension contribution points, #3926 channel user id propagation, #5224 tool assembly off the event loop, #5214 tool-progress event attribution, #4361 summarizing with the subagent’s own model, #5154 date timezone, and #4155 , #4128 , #4002 input and tool-result sanitization.