agents schema (1-150)

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Agent presets, retry policy, and managed runtime defaults. Model availability is defined canonically under providers.*.models plus model_discovery; legacy agents.{claude,codex,pi}.models is removed.

Field path	Type	Required	Default	Canonical description
`agents`	`section`	optional		Agent presets, retry policy, and managed runtime defaults. Model availability is defined canonically under providers.*.models plus model_discovery; legacy agents.{claude,codex,pi}.models is removed.
└ `agents.presets`	`list[map]`	optional		Reusable agent launch presets.
└ `agents.presets.id`	`string`	required		Stable preset identifier.
└ `agents.presets.label`	`string`	required		Human-readable display label.
└ `agents.presets.type`	`string`	optional		Logical agent type.
└ `agents.presets.command`	`string`	required		Shell command template for agent launch.
└ `agents.presets.profile`	`string \| list[string]`	optional		Default profile selection.
└ `agents.presets.readiness_timeout_secs`	`u64`	optional		Readiness timeout override.
└ `agents.presets.provider`	`string`	optional		Provider for agent launches (e.g. 'openai', 'anthropic', 'github-copilot'). Used with model for provider+model selection.
└ `agents.presets.model`	`string`	optional		Model to use for agent launches (e.g. 'gpt-5.4', 'claude-opus-4-6'). Passed as --model.
└ `agents.presets.node_selector`	`string`	optional		Spawn placement: local_only, round_robin, or least_overloaded.
└ `agents.presets.environment`	`map[string, string]`	optional		Non-secret env defaults merged onto the managed launch.
└ `agents.transient_compute`	`map`	optional		Provider-neutral transient per-agent compute scheduler.
└ `agents.transient_compute.default`	`string`	optional		Default transient compute provider key.
└ `agents.transient_compute.max_parallel`	`u32`	optional		Global active transient job ceiling.
└ `agents.transient_compute.max_runtime_secs`	`u64`	optional		Global transient job runtime ceiling in seconds.
└ `agents.transient_compute.launch_spec_ttl_secs`	`u64`	optional		Global launch-spec validity window in seconds, capped by the runtime ceiling.
└ `agents.transient_compute.max_retries`	`u32`	optional		Global retry-attempt ceiling recorded for transient jobs.
└ `agents.transient_compute.reaper_grace_secs`	`u64`	optional		Grace period before terminal transient jobs enter the first reaping phase.
└ `agents.transient_compute.budget_cents_per_day`	`u32`	optional		Daily transient compute admission budget in cents.
└ `agents.transient_compute.providers`	`map[string, map]`	optional		Transient compute providers keyed by name.
└ `agents.transient_compute.providers.<provider>`	`map`	optional		One transient compute provider definition.
└ `agents.transient_compute.providers.<provider>.type`	`string`	required		Provider implementation type. This slice supports 'fake' for deterministic tests.
└ `agents.transient_compute.providers.<provider>.enabled`	`bool`	optional	true	Whether this provider may accept new jobs.
└ `agents.transient_compute.providers.<provider>.dynamic_node_template`	`string`	optional		Dynamic-node template expected for joined transient runtimes.
└ `agents.transient_compute.providers.<provider>.max_parallel`	`u32`	optional		Provider-local active job ceiling.
└ `agents.transient_compute.providers.<provider>.max_runtime_secs`	`u64`	optional		Provider-local runtime ceiling in seconds.
└ `agents.transient_compute.providers.<provider>.launch_spec_ttl_secs`	`u64`	optional		Provider-local launch-spec validity window in seconds.
└ `agents.transient_compute.providers.<provider>.max_retries`	`u32`	optional		Provider-local retry-attempt ceiling.
└ `agents.transient_compute.providers.<provider>.sku`	`string`	optional		Selected provider SKU / VM size / node shape.
└ `agents.transient_compute.providers.<provider>.allowed_skus`	`list[string]`	optional		Allow-list of provider SKU / VM size / node shape values.
└ `agents.transient_compute.providers.<provider>.workload_profile`	`string`	optional		Selected workload profile / pool / class.
└ `agents.transient_compute.providers.<provider>.allowed_workload_profiles`	`list[string]`	optional		Allow-list of workload profile / pool / class values.
└ `agents.transient_compute.providers.<provider>.cost_per_minute_cents`	`u32`	optional		Estimated cents per minute for budget admission.
└ `agents.transient_compute.providers.<provider>.artifact_uri`	`string`	optional		Artifact destination hint for result-bundle import.
└ `agents.flow`	`map`	optional		Flow-created worker preferences.
└ `agents.flow.default`	`map`	optional		Shared Flow launch defaults.
└ `agents.flow.default.type`	`string`	optional		Default agent type.
└ `agents.flow.default.effort`	`string`	optional		Runtime reasoning effort; explicit requests win.
└ `agents.flow.default.profile`	`string \| list[string]`	optional		Profile or ordered list for composite composition.
└ `agents.flow.default.preset`	`string`	optional		Default preset ID.
└ `agents.flow.default.readiness_timeout_secs`	`u64`	optional	60	Readiness sentinel timeout.
└ `agents.flow.default.node_selector`	`string`	optional		Spawn placement: local_only, round_robin, or least_overloaded.
└ `agents.flow.default.resources`	`map`	optional		Per-agent resource ceilings.
└ `agents.flow.default.resources.vcpu`	`f64`	optional		Logical CPU budget (e.g. 2.0 for two cores).
└ `agents.flow.default.resources.memory`	`string`	optional		Memory ceiling (e.g. '8GiB', '512MiB').
└ `agents.flow.default.model`	`string`	optional		Model to use for agent launches (e.g. 'opus', 'sonnet'). Passed as --model.
└ `agents.flow.default.provider`	`string`	optional		Provider for agent launches (e.g. 'openai', 'anthropic', 'google', 'github-copilot').
└ `agents.flow.default.short_name_strategy`	`map`	optional		Strategy for generating a short human-friendly display name at agent creation time.
└ `agents.flow.default.short_name_strategy.strategy`	`string`	required		Short-name strategy: adj_noun, template or llm.
└ `agents.flow.default.short_name_strategy.template`	`string`	optional		Bounded display template for strategy = template. Placeholders: {adj}, {noun}, {profile}, {bead}, {node}, {n}. Names remain aliases, not identities.
└ `agents.flow.default.short_name_strategy.llm`	`string`	optional		Top-level llm alias used when strategy = llm.
└ `agents.flow.default.checkout_type`	`string`	optional	worktree	How this project's agents materialize their working checkout: worktree (default; a git worktree sharing the canonical.git, fastest startup), clone, full, read_only_symlink, or pr_branch (an existing GitHub PR head branch; requires github_integration.enabled,). made worktree the default.
└ `agents.flow.default.persistent_agent_idle_timeout_secs`	`u64`	optional	1800	Auto-restart persistent agents after this much tool inactivity.
└ `agents.flow.default.completed_retention_hours`	`u64`	optional	72	Delete acknowledged completed agent checkouts after N hours.
└ `agents.flow.default.completed_retention_count`	`u32`	optional	20	Keep at most N acknowledged completed agent checkouts per project, pruning oldest first.
└ `agents.flow.default.completed_retention_bytes`	`string`	optional	50GB	Hard cap on acknowledged completed checkout disk usage for this project.
└ `agents.flow.default.pi_extra_config_dirs`	`list[string]`	optional		Extra config directories merged into managed Pi workspaces.
└ `agents.flow.default.override_pi_agent_dir`	`string`	optional		Read-only operator-owned Pi agent directory passed directly to managed Pi launches instead of materializing .pi-agent config.
└ `agents.flow.default.warmup_cache_injection`	`map`	optional		Disabled-by-default advisory warmup-cache prompt injection settings for spawned agents.
└ `agents.flow.default.warmup_cache_injection.enabled`	`bool`	optional	false	Enable advisory warmup-cache prompt injection.
└ `agents.flow.default.warmup_cache_injection.max_age_seconds`	`i64`	optional	86400	Maximum accepted warmup summary age before skipping injection.
└ `agents.flow.default.warmup_cache_injection.max_chars`	`usize`	optional	2048	Maximum characters injected from the warmup summary.
└ `agents.flow.default.pane_error_detection`	`bool`	optional	false	Enable tmux pane content scanning for Pi agent fatal error detection.
└ `agents.flow.default.eligible_nodes`	`list[string]`	optional		Allowlist of node names for round_robin/least_overloaded placement. Manual --node overrides bypass this.
└ `agents.flow.default.friend_projects`	`list[friend_project]`	optional		Agent-default friend project overlays inherited by agents in this project.
└ `agents.flow.default.friend_projects.project`	`string`	required		Target project name.
└ `agents.flow.default.friend_projects.branch`	`string`	optional		Target branch; omitted means the friend project's default_branch. Mutually exclusive with revision.
└ `agents.flow.default.friend_projects.revision`	`string`	optional		Pinned git revision. Mutually exclusive with branch.
└ `agents.flow.default.friend_projects.permissions`	`list[string]`	optional	[checkout_read]	Granted operations: checkout_read, checkout_write, beads_read, beads_create, beads_update, beads_claim, beads_close, beads_dispatch.
└ `agents.flow.default.friend_projects.materialize`	`bool`	optional	false	Materialize a real friend checkout cloned from the friend project's remote; omitted means a virtual friend with no checkout.
└ `agents.flow.default.friend_projects.enabled`	`bool`	optional	true	Set false in a narrower layer to disable an inherited friend.
└ `agents.heartbeat`	`map`	optional		Global managed-agent heartbeat defaults and per-agent overrides. Delivery remains local-daemon owned.
└ `agents.heartbeat.enabled`	`bool`	optional	false	Enable local daemon-owned managed-agent heartbeat delivery for this scope. Defaults to false for safe rollout.
└ `agents.heartbeat.selector`	`string`	optional	persistent	Agent selector for this scope: all, persistent, workers, or none.
└ `agents.heartbeat.interval_secs`	`u64`	optional	300	Base heartbeat cadence in seconds.
└ `agents.heartbeat.jitter_secs`	`u64`	optional	0	Optional jitter in seconds; must not exceed interval_secs.
└ `agents.heartbeat.max_backoff_secs`	`u64`	optional	300	Optional delivery-failure backoff ceiling in seconds; must be at least interval_secs.
└ `agents.heartbeat.allow_runtime_opt_out`	`bool`	optional	true	Allow runtime/profile code to decline heartbeats even when config enables them.
└ `agents.heartbeat.conditions`	`list[string]`	optional		Optional OR timer gates: claimed_beads (owned unfinished claims), unmerged_prs (linked open PRs), pending_inbox (visible unread messages). Inherits when omitted; [] is unconditional. Runtime on never bypasses conditions.
└ `agents.heartbeat.overrides`	`map[string, map]`	optional		Per-agent overrides keyed by persistent declaration name, composed profile, or concrete agent id.
└ `agents.heartbeat.overrides.<agent>`	`map`	optional		One per-agent heartbeat override; inherits unspecified fields from the surrounding scope.
└ `agents.heartbeat.overrides.<agent>.enabled`	`bool`	optional		Enable or disable heartbeat for this agent.
└ `agents.heartbeat.overrides.<agent>.selector`	`string`	optional		Optional selector override: all, persistent, workers, or none.
└ `agents.heartbeat.overrides.<agent>.interval_secs`	`u64`	optional		Override base heartbeat cadence in seconds.
└ `agents.heartbeat.overrides.<agent>.jitter_secs`	`u64`	optional		Override jitter in seconds; must not exceed interval_secs when both are set.
└ `agents.heartbeat.overrides.<agent>.max_backoff_secs`	`u64`	optional		Override delivery-failure backoff ceiling in seconds.
└ `agents.heartbeat.overrides.<agent>.allow_runtime_opt_out`	`bool`	optional		Override runtime opt-out permission for this agent.
└ `agents.heartbeat.overrides.<agent>.conditions`	`list[string]`	optional		Replace inherited OR timer gates (claimed_beads, unmerged_prs, pending_inbox); [] restores unconditional delivery.
└ `agents.message_delivery`	`map`	optional		Global managed-agent message-delivery cadence defaults and per-agent overrides (wake vs batch). Delivery remains local-daemon owned.
└ `agents.message_delivery.enabled`	`bool`	optional	false	Enable local daemon-owned managed-agent message-delivery batching for this scope. Defaults to false (immediate wake) for safe rollout.
└ `agents.message_delivery.selector`	`string`	optional	all	Agent selector for this scope: all, persistent, workers, or none.
└ `agents.message_delivery.default_mode`	`string`	optional	immediate	Wake mode for a message with no explicit wake flag: immediate (wake now) or batch (defer to next heartbeat).
└ `agents.message_delivery.always_wake_kinds`	`list[string]`	optional		Message kinds that always wake regardless of mode (e.g. lifecycle, system).
└ `agents.message_delivery.allow_runtime_opt_out`	`bool`	optional	true	Allow runtime/profile code to decline batching even when config enables it.
└ `agents.message_delivery.batch_flush_interval_secs`	`u64`	optional		Optional shorter dedicated cadence in seconds for surfacing deferred (batched) messages via a coalesced summary wake, instead of waiting for the full heartbeat. A flush with no pending messages costs zero model turns.
└ `agents.message_delivery.direct_message_wake`	`bool`	optional	true	Operator- or agent-authored direct messages the batch policy would defer instead force one coalesced wake carrying them inline, including for idle, dormant and queue-parked recipients; paused or starting recipients are held until live. Automated notices, broadcast batching and heartbeat intervals are unchanged. false restores pure batching of direct messages.
└ `agents.message_delivery.overrides`	`map[string, map]`	optional		Per-agent overrides keyed by persistent declaration name or concrete agent id.
└ `agents.message_delivery.overrides.<agent>`	`map`	optional		One per-agent message-delivery override; inherits unspecified fields from the surrounding scope.
└ `agents.message_delivery.overrides.<agent>.enabled`	`bool`	optional		Enable or disable message-delivery batching for this agent.
└ `agents.message_delivery.overrides.<agent>.selector`	`string`	optional		Optional selector override: all, persistent, workers, or none.
└ `agents.message_delivery.overrides.<agent>.default_mode`	`string`	optional		Override wake mode: immediate or batch.
└ `agents.message_delivery.overrides.<agent>.always_wake_kinds`	`list[string]`	optional		Override always-wake message kinds.
└ `agents.message_delivery.overrides.<agent>.allow_runtime_opt_out`	`bool`	optional		Override runtime opt-out permission for this agent.
└ `agents.message_delivery.overrides.<agent>.batch_flush_interval_secs`	`u64`	optional		Override the dedicated batch-flush cadence in seconds.
└ `agents.message_delivery.overrides.<agent>.direct_message_wake`	`bool`	optional		Override the direct-message wake for this agent.
└ `agents.on_demand`	`map`	optional		Global runtime policy for opt-in pi-on-demand / pico-on-demand agents.
└ `agents.on_demand.idle_timeout_secs`	`u64`	optional	300	Seconds without tool activity before an on-demand Pi-family runtime is stopped and returns to dormant.
└ `agents.on_demand.max_wake_concurrency`	`u32`	optional	1	Maximum simultaneous cold wakes on one daemon (reserved for scheduler admission follow-up).
└ `agents.on_demand.warm_pool_size`	`u32`	optional	0	Pre-warmed on-demand runtimes to retain (reserved for warm-pool follow-up).
└ `agents.paratenic`	`map`	optional		Global fallback Paratenic AHP client settings; node-local agents.paratenic wins.
└ `agents.paratenic.apply_to_pi`	`bool`	optional	false	Route ordinary managed Pi delivery through an exact schema-v2 Paratenic binding first, with normal Pi fallback when evidence is absent or stale.
└ `agents.paratenic.url`	`string`	required	ws://127.0.0.1:7788/ahp	Paratenic AHP WebSocket endpoint including /ahp.
└ `agents.paratenic.token_file`	`string`	required	~/.config/paratenic/token	Owner-private Paratenic bearer-token file.
└ `agents.paratenic.backend_socket`	`string`	required	~/.local/state/paratenic/backend.sock	Owner-private Paratenic backend registration socket.
└ `agents.paratenic.extension_path`	`string`	required		Reviewed Paratenic Pi extension loaded by managed Pi.
└ `agents.paratenic.registration_timeout_secs`	`u64`	optional	30	Legacy registration timeout exported for runtime compatibility; not a launch or resume gate.
└ `agents.paratenic.dispatch_timeout_secs`	`u64`	optional	30	Maximum AHP dispatch/acceptance wait.
└ `agents.pi_daemon`	`map`	optional		Global fallback standalone Pi SDK host client settings; node-local agents.pi_daemon wins.
└ `agents.pi_daemon.socket_path`	`string`	required		Owner-local Unix socket exposed by the separately supervised standalone pi-daemon host.
└ `agents.pi_daemon.binary`	`string`	optional	pi-daemon	Standalone pi-daemon executable path/name.
└ `agents.pi_daemon.state_dir`	`string`	optional	$CACOPHONY_DIR/pi-daemon	Standalone host state directory.
└ `agents.pi_daemon.agent_dir`	`string`	optional		Pi auth/model directory; omitted uses Pi's default.
└ `agents.pi_daemon.allow_root`	`string`	optional	$CACOPHONY_DIR/agents	Canonical workload root allowed by the standalone host.
└ `agents.pi_daemon.tool_adapter_dir`	`string`	optional		Owner-private mode-0700 directory for Cacophony per-session neutral filesystem adapter sockets; used only by host_adapter mode.
└ `agents.pi_daemon.session_mode`	`enum`	optional	configured_session when api.enabled, otherwise host_adapter	Logical-session launch boundary: configured_session uses the authenticated typed Session API; host_adapter retains filesystem-only protocol-v2 compatibility/isolation.
└ `agents.pi_daemon.max_line_bytes`	`usize`	optional	1048576	Maximum NDJSON command/response bytes accepted by the Cacophony client.
└ `agents.pi_daemon.max_events_per_request`	`usize`	optional	4096	Maximum matching events retained while awaiting one terminal response.
└ `agents.pi_daemon.max_sessions`	`u32`	optional	128	Maximum resident logical SDK sessions in the standalone host.
└ `agents.pi_daemon.max_concurrent_turns`	`u32`	optional	4	Maximum concurrent model turns in the standalone host.
└ `agents.pi_daemon.max_session_queue_depth`	`u32`	optional	32	Maximum queued turns per logical session; zero allows only the active turn.
└ `agents.pi_daemon.max_connections`	`u32`	optional	64	Maximum Unix control connections in the standalone host, including wakes awaiting settlement.
└ `agents.pi_daemon.max_api_connections`	`u32`	optional	64	Maximum HTTP and upgraded WebSocket connections, independent of Unix connections.
└ `agents.pi_daemon.max_rpc_hubs`	`u32`	optional	32	Maximum concurrently attached RPC session generations.
└ `agents.pi_daemon.max_rpc_replay_bytes`	`u64`	optional	2097152	Replay byte budget per RPC hub.
└ `agents.pi_daemon.max_rpc_total_replay_bytes`	`u64`	optional	67108864	Aggregate replay budget; must cover max_rpc_hubs multiplied by max_rpc_replay_bytes.
└ `agents.pi_daemon.max_residency_leases`	`u32`	optional	256	Maximum resident-runtime leases across attached clients.
└ `agents.pi_daemon.recovery_open_timeout_ms`	`u64`	optional	30000	Startup recovery budget per retained runtime in milliseconds.
└ `agents.pi_daemon.recovery_total_timeout_ms`	`u64`	optional	120000	Total startup runtime recovery budget in milliseconds.
└ `agents.pi_daemon.node_max_old_space_size_mb`	`u32`	optional		V8 old-space MiB for the Pi-Daemon service launch, not sibling services; not an RSS reservation or CPU quota. Node child tools may inherit NODE_OPTIONS.
└ `agents.pi_daemon.idle_session_ttl_ms`	`u64`	optional	1800000	Idle SDK-session eviction interval in milliseconds; zero disables eviction.
└ `agents.pi_daemon.api`	`map`	optional		Authenticated HTTP API listener settings; omission preserves socket-only launch byte-for-byte.
└ `agents.pi_daemon.api.enabled`	`bool`	required		Explicitly enable or disable the authenticated HTTP API listener.
└ `agents.pi_daemon.api.bind`	`string`	optional		API listener address; non-loopback plaintext also requires allow_insecure_http=true.
└ `agents.pi_daemon.api.port`	`u16`	optional		API listener port; required when enabled and distinct from the embedded Dashboard port.
└ `agents.pi_daemon.api.token_file`	`string`	optional	$CACOPHONY_DIR/pi-daemon/api-token	Owner-private bearer-token file reference; bearer bytes are forbidden in config.
└ `agents.pi_daemon.api.allow_insecure_http`	`bool`	optional	false	Explicit acknowledgement required for non-loopback plaintext API binding.
└ `agents.pi_daemon.web`	`map`	optional		Embedded browser Dashboard settings in the same supervised pi-daemon process.
└ `agents.pi_daemon.web.enabled`	`bool`	required		Explicitly enable or disable the embedded Dashboard in the supervised host process.
└ `agents.pi_daemon.web.bind`	`string`	optional		Embedded Dashboard listener address.