config.toml

config.toml is the main AGH runtime desired-state file. AGH loads the built-in defaults, then overlays global and workspace files when they exist. The daemon only treats a change as runtime truth after ConfigApplyService advances the active generation and writes a config_apply_records audit row.

Unknown TOML keys are errors. Sandbox profiles are implemented under [sandboxes.<name>]; the old Use only [sandboxes.<name>] for session execution boundaries.

Quick Reference

Load And Merge Order

TOML [[mcp_servers]] entries merge fields by name: non-empty command, non-empty args, and new env keys overlay the existing server. JSON sidecars replace same-name servers as whole objects.

Daemon boot uses the home config for boot-time daemon settings. The general config loader applies global and workspace MCP sidecars for session and runtime resolution.

Complete Annotated Example

# ~/.agh/config.toml

[daemon]
# Path to the Unix domain socket used by AGH CLI commands.
socket = "~/.agh/daemon.sock"

[daemon.reload_timeouts]
# Provider runtime reload budget. Valid range: 1s to 60s.
providers = "5s"
# MCP runtime reload budget. Valid range: 1s to 60s.
mcp = "10s"
# Bridge runtime reload budget. Valid range: 1s to 300s.
bridges = "30s"

[http]
# HTTP/SSE API bind address.
host = "localhost"
port = 2123

[defaults]
# Agent name used when a command or API request does not specify one.
agent = "general"
# Provider used by AGENT.md files that omit provider.
provider = "claude"
# Sandbox profile used when a workspace does not set sandbox_ref.
sandbox = "local"

[limits]
# Positive daemon-wide agent concurrency bound.
max_concurrent_agents = 20

[session.limits]
# 0 means no configured wall-clock timeout. Use Go durations such as "30m" or "2h".
timeout = "0s"

[session.supervision]
# Short heartbeats update durable liveness only. They are not persisted as session events.
activity_heartbeat_interval = "30s"
# 0 disables periodic progress events.
progress_notify_interval = "10m"
# 0 disables inactivity warnings.
inactivity_warning_after = "15m"
# 0 disables inactivity timeout.
inactivity_timeout = "30m"
# Grace period after cooperative prompt cancel before AGH stops the session as timeout.
timeout_cancel_grace = "30s"

[agents.soul]
# Disabling pauses prompt injection but keeps inspect/validate/write/delete/history/rollback available.
enabled = true
# Hard cap for SOUL.md body bytes after normalization.
max_body_bytes = 32768
# Compact /agent/context projection budget. Must be <= max_body_bytes.
context_projection_bytes = 2048

[agents.heartbeat]
# Disabling pauses wake decisions but keeps managed authoring available for repair.
enabled = true
# Bounded HEARTBEAT.md body size (snapshot uses normalized body).
max_body_bytes = 32768
# Compact projection budget for status surfaces.
context_projection_bytes = 4096
# Hard floor for authored preferences.min_interval. Files below this are clamped.
min_interval = "5m"
# Default cadence baseline used when authored files omit min_interval.
default_interval = "30m"
# Cooldown between wakes for a single session.
wake_cooldown = "1m"
# Maximum scheduler-cycle wakes across the daemon.
max_wakes_per_cycle = 25
# When true, wake only sessions in active runtime state.
active_session_only = true
# When true, authored active_hours/quiet_windows preferences are honored within bounds.
allow_active_hours_preferences = true
# Retention for agent_heartbeat_wake_events audit rows. Minimum 1h.
wake_event_retention = "168h"
# Idle age before metadata-only presence is treated as stale for wake eligibility.
session_health_stale_after = "2m"
# Minimum interval between session.health.update.after hook fires for the same session.
session_health_hook_min_interval = "1m"

[permissions]
# Valid values: deny-all, approve-reads, approve-all.
mode = "approve-all"

[tools]
# Disables registry dispatch and hosted MCP exposure when false.
enabled = true
# Enables AGH-hosted local MCP projection for session-visible tools.
hosted_mcp_enabled = true
# Default result cap for tool descriptors that do not set a smaller cap.
default_max_result_bytes = 262144

[tools.hosted_mcp]
# Non-secret launch correlation nonce lifetime before UDS peer binding.
bind_nonce_ttl_seconds = 30

[tools.policy]
# Valid values: disabled, ask, enabled.
external_default = "disabled"
# Bounded wait for daemon-mediated approval flows.
approval_timeout_seconds = 120
# External read-only sources trusted for approve-reads. Entries use kind:owner.
trusted_sources = []

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/work"]
env = { LOG_LEVEL = "info" }

[[mcp_servers]]
name = "remote-docs"
transport = "sse"
url = "https://mcp.example.com/sse"

[mcp_servers.auth]
type = "oauth2_pkce"
issuer_url = "https://auth.example.com"
client_id = "agh-desktop"
client_secret_ref = "env:REMOTE_DOCS_MCP_CLIENT_SECRET"
scopes = ["mcp.read", "mcp.write"]

[providers.claude]
# Overrides the built-in Claude provider command and records native auth diagnostics.
command = "npx -y @agentclientprotocol/claude-agent-acp@latest"
auth_mode = "native_cli"
auth_status_command = "claude auth status"
auth_login_command = "claude auth login"

[providers.claude.models]
# Pre-session catalog defaults consumed by the daemon-owned model catalog.
default = "claude-sonnet-4-6"

[[providers.claude.models.curated]]
id = "claude-sonnet-4-6"
display_name = "Claude Sonnet 4.6"

[[providers.claude.models.curated]]
id = "claude-haiku-4-5"
display_name = "Claude Haiku 4.5"

[model_catalog.sources.models_dev]
# Optional models.dev enrichment source for catalog metadata.
enabled = true
endpoint = "https://models.dev/api.json"
ttl = "24h"
timeout = "10s"

[[providers.claude.mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
secret_env = { GITHUB_TOKEN = "env:GITHUB_TOKEN" }

[sandboxes.local]
backend = "local"
sync_mode = "none"
persistence = "reuse"
runtime_root = "~"

[sandboxes.daytona-dev]
backend = "daytona"
sync_mode = "session-bidirectional"
persistence = "reuse"
runtime_root = "/home/daytona/workspace"

[sandboxes.daytona-dev.env]
NODE_ENV = "development"

[sandboxes.daytona-dev.network]
allow_public_ingress = false
allow_outbound = true
allow_list = ["api.example.test"]
deny_list = ["metadata.google.internal"]

[sandboxes.daytona-dev.daytona]
api_url = "https://app.daytona.io/api"
target = "team-default"
snapshot = "snap-agent-base"
image = "ubuntu:24.04"
class = "cpu-2"
auto_stop = "30m"
auto_archive = "24h"

[observability]
enabled = true
retention_days = 7
max_global_bytes = 1073741824

[observability.transcripts]
enabled = true
segment_bytes = 1048576
max_bytes_per_session = 268435456

[log]
level = "info"
max_size_mb = 10
max_backups = 5
max_age_days = 30
compress_backups = false

[memory]
enabled = true
global_dir = "~/.agh/memory"

[memory.controller]
mode = "hybrid"                              # hybrid | rules | llm
max_latency = "300ms"
default_op_on_fail = "noop"

[memory.controller.llm]
enabled = true
model = "anthropic/claude-haiku-4"
top_k = 5
prompt_version = "v1"
timeout = "250ms"
max_tokens_out = 256

[memory.controller.policy]
max_content_chars = 4096
max_writes_per_min = 60
allow_origins = ["cli", "http", "uds", "tool", "extractor", "dreaming", "file", "provider"]

[memory.recall]
top_k = 5
raw_candidates = 50
fusion = "weighted"
include_already_surfaced = false
include_system = false

[memory.recall.weights]
bm25_unicode = 0.55
bm25_trigram = 0.20
recency = 0.15
recall_signal = 0.10

[memory.recall.freshness]
banner_after_days = 1

[memory.recall.signals]
queue_capacity = 256
worker_retry_max = 3
metrics_enabled = true

[memory.decisions]
prune_after_applied_days = 90
keep_audit_summary = true
max_post_content_bytes = 65536

[memory.extractor]
enabled = true
mode = "post_message"
throttle_turns = 1
deadline = "60s"
sandbox_inbox_only = true
inbox_path = "$AGH_HOME/memory/_inbox"
dlq_path = "$AGH_HOME/memory/_system/extractor/failures"
model = ""

[memory.extractor.queue]
capacity = 1
coalesce_max = 16

[memory.dream]
enabled = true
agent = "dreaming-curator"
min_hours = 24
min_sessions = 3
debounce = "10m"
prompt_version = "v1"
check_interval = "30m"

[memory.dream.gates]
min_unpromoted = 5
min_recall_count = 2
min_score = 0.75

[memory.dream.scoring]
recency_half_life_days = 14

[memory.dream.scoring.weights]
frequency = 0.30
relevance = 0.35
recency = 0.20
freshness = 0.15

[memory.session]
ledger_format = "jsonl"
ledger_root = "$AGH_HOME/sessions"
events_purge_grace = "24h"
cold_archive_days = 30
hard_delete_days = 0
max_archive_bytes = 10737418240
unbound_partition = "_unbound"

[memory.daily]
max_bytes = 1048576
max_lines = 5000
rotate_format = "{date}.{seq}.md"
dreaming_window = 7
cold_archive_days = 30
hard_delete_days = 0
max_archive_bytes = 1073741824
sweep_hour = 3
archive_path = "_system/archive"

[memory.file]
max_lines = 200
max_bytes = 25600

[memory.provider]
name = ""                                    # empty = bundled local provider
timeout = "2s"
failure_threshold = 5
cooldown = "30s"

[memory.workspace]
toml_path = "<workspace>/.agh/workspace.toml" # informational; not configurable
auto_create = true

[skills]
enabled = true
disabled_skills = ["experimental-skill"]
poll_interval = "3s"
allowed_marketplace_mcp = ["clawhub:@team/search-skill"]
allowed_marketplace_hooks = ["clawhub:@team/format-hook"]

[skills.marketplace]
registry = "clawhub"
base_url = "https://registry.example.com"

[extensions.marketplace]
registry = "github"
base_url = "https://api.github.com"

[automation]
enabled = true
timezone = "UTC"
max_concurrent_jobs = 5
default_fire_limit = { max = 12, window = "1h" }

[[automation.jobs]]
scope = "workspace"
name = "daily-doc-check"
agent = "docs"
workspace = "workspace-id-or-path"
prompt = "Review changed docs and report stale links."
enabled = true
fire_limit = { max = 2, window = "24h" }

[automation.jobs.schedule]
mode = "cron"
expr = "0 9 * * 1-5"

[automation.jobs.retry]
strategy = "backoff"
max_retries = 3
base_delay = "2s"

[[automation.triggers]]
scope = "workspace"
workspace = "workspace-id-or-path"
name = "failed-session-summary"
agent = "general"
prompt = "Summarize why session {{ index .Data \"session_id\" }} stopped."
event = "session.stopped"
enabled = true

[automation.triggers.filter]
kind = "session.stopped"
data.stop_reason = "error"

[autonomy.coordinator]
# Disabled by default. When enabled, a workspace-scoped coordinated task run may start
# one coordinator session for that workspace after publish, start, approval, or an
# equivalent execution boundary enqueues the run.
enabled = false
agent_name = "coordinator"
# Optional provider/model overrides. Empty values fall through to agent/provider defaults.
provider = ""
model = ""
default_ttl = "2h"
max_children = 5
max_active_sessions_per_workspace = 5

[task.orchestration]
# Bounds for task summaries, context bundles, scheduler health, and max-runtime watchdog.
summary_max_bytes = 4096
context_body_max_bytes = 8192
context_prior_attempts = 5
context_recent_events = 50
spawn_failure_limit = 5
scheduler_bad_tick_threshold = 6
scheduler_bad_tick_cooldown = "5m"
# Zero disables the per-task max-runtime watchdog default. Tasks may still set a per-task override.
default_max_runtime = "0s"

[task.orchestration.profile]
# Defaults that apply when a task does not persist its own execution profile.
default_coordinator_mode = "inherit"
default_worker_mode = "inherit"
default_sandbox_mode = "inherit"
# Gate task-level provider/model overrides on the profile.
allow_task_provider_override = true
# Gate task-level sandbox = "none" selections.
allow_task_sandbox_none = true

[task.orchestration.review]
# Defaults for the post-terminal review gate. See the review-gate docs for end-to-end behavior.
default_policy = "none"
max_rounds = 3
max_review_attempts = 2
timeout = "20m"
rapid_terminal_window = "2m"
rapid_terminal_limit = 3
missing_work_max_items = 20
missing_work_item_max_bytes = 512
reason_max_bytes = 2048
review_text_max_bytes = 12000
next_round_guidance_max_bytes = 4096
failure_policy = "block_task"

[task.recovery]
# When true, agent identities may use force release, force fail, retry, and bulk recovery surfaces.
# Set false to reserve those verbs for non-agent operator identities.
allow_agent_force = true

[[hooks.declarations]]
name = "record-session-start"
event = "session.post_create"
mode = "async"
required = false
priority = 500
timeout = "5s"
command = "printf"
args = ["session started\n"]
env = { HOOK_LOG = "1" }

[hooks.declarations.matcher]
agent_name = "general"

[network]
enabled = true
default_channel = "default"
port = -1
max_payload = 1048576
greet_interval = 30
max_replay_age = 300
max_queue_depth = 100

[daemon]

[http]

[defaults]

[limits]

[session.limits]

[session.supervision]

Session supervision keeps long-running prompts observable without turning every heartbeat into a stored event. AGH updates session metadata on short heartbeats and only writes durable events for lower-frequency progress, warnings, and timeout classification.

This timeout is based on inactivity, not total runtime. A prompt can run for hours as long as AGH continues to observe runtime activity or controlled waiting heartbeats.

[agents.soul]

[agents.soul] controls the optional SOUL.md authored persona artifact. Config owns body limits, compact projection budget, and the enabled toggle. SOUL.md cannot redefine any of these keys, and forbidden operational fields in SOUL.md are rejected. See Agent Soul.

Workspace overlay merges scalar fields predictably; setting any key zero-clamps to the validated positive value or fails with a typed validation error. Disabling at runtime does not clear stored snapshots; managed authoring keeps working so operators can repair a broken file.

[agents.heartbeat]

[agents.heartbeat] controls the optional HEARTBEAT.md advisory wake policy and the runtime health/wake-audit subsystem. Config owns cadence, rate limits, retention, and stale thresholds; authored files express bounded preferences only. See Agent Heartbeat.

[agents.heartbeat] does not own task-run lease heartbeat (task_runs + ClaimNextRun + HeartbeatRunLease), [session.supervision] activity heartbeat, or AGH Network [network] greet presence. Those four authorities remain independent.

HEARTBEAT.md snapshot digest covers the normalized body, canonical frontmatter JSON, and a canonical digest of the resolved [agents.heartbeat] config subset. Editing any field that affects parsing, preference resolution, eligibility, retention, or coalescing invalidates the digest and triggers a fresh resolution at the next wake decision.

[permissions]

[tools]

Tool registry configuration is loaded before runtime policy and dispatch consume it. These keys only establish defaults and parse-time guardrails; dispatch still revalidates visibility, permission, availability, hooks, and approval state per call. When enabled = true, the runtime injects the agh__bootstrap and agh__catalog discovery toolsets for every agent unless effective policy denies them, and a startup prompt section teaches the search → info → invoke loop.

[tools.hosted_mcp]

[tools.policy]

trusted_sources does not store credentials. Remote MCP OAuth tokens remain in the MCP auth store, and hosted MCP bind nonces are transient session launch state.

[[mcp_servers]]

Top-level MCP servers are merged with provider, agent, and skill MCP servers during session startup. They can point at local stdio processes or remote HTTP/SSE MCP endpoints.

OAuth-enabled remote servers store only metadata in config. Token material is kept in the AGH Vault as encrypted refs and is exposed through API, settings, CLI, logs, and the agent-callable agh__mcp_status / agh__mcp_auth_status tools only as redacted status. Login/logout happen on CLI and HTTP. These are operator-only management flows.

Configure one of metadata_url, issuer_url, or both authorization_url and token_url, then authenticate with:

agh mcp auth login remote-docs
agh mcp auth status remote-docs
agh mcp auth status remote-docs --refresh
agh mcp auth logout remote-docs

Agents can read the same redacted status from inside a session through agh__mcp_status or agh__mcp_auth_status. These tools never trigger an OAuth browser flow; missing or expired authentication is repaired through the operator login/logout commands above. Auth-blocked MCP tools are omitted from callable discovery while status/probe output explains the repair path.

[providers.<name>]

Provider keys override built-ins with the same name or create a custom provider. Built-ins are claude, codex, gemini, opencode, copilot, cursor, kiro, blackbox, cline, goose, hermes, junie, kimi-cli, openclaw, openhands, qoder, qwen-code, pi, openrouter, zai, moonshot, vercel-ai-gateway, xai, minimax, mistral, and groq.

The flat keys default_model, supported_models, and supports_reasoning_effort are no longer accepted. Config that still sets them is rejected with a deterministic hard-cut error citing the exact path. Move every value into [providers.<id>.models] below.

Provider and model aliases are small and explicit. Provider aliases such as claude-code, ai-gateway, vercel, kimi, glm, x.ai, grok, open-code, and qwen resolve to the canonical provider ID before config is applied. Provider-scoped model aliases such as sonnet, opus, haiku, gpt5, mini, kimi, glm, grok, and qwen resolve to the concrete model ID for the selected provider. Runtime diagnostics, session metadata, and model catalog rows use the canonical resolved value.

The old providers.<id>.aliases config key was removed for v1. Reference providers by canonical name only; config files that set aliases = [...] under a provider are rejected during load.

auth_mode = "none" means No auth required and is only valid when the provider needs no AGH or provider-owned credential. Set none_security to state why that is safe: local-only transport, external identity enforcement, or public read-only access. No-auth providers cannot define credential_slots, auth_status_command, or auth_login_command; those keys are rejected during config validation.

[providers.<id>.models]

Pre-session model defaults and curated metadata are owned by the daemon-owned model catalog. The catalog merges builtin defaults, the operator config, the optional models.dev enrichment source, live provider discovery sources, and extension model sources, and exposes the result through HTTP, UDS, CLI, the OpenAI-compatible projection, the Host API, and the web. Active ACP configOptions continue to govern model and reasoning controls inside a running session, so curated entries are metadata, never an allowlist.

Discovery adapters use the resolved provider auth, env, and home policy. Discovery never creates an ACP session; if discovery is unavailable or fails, the catalog records source status and falls back to stale or lower-priority rows. Session creation never depends on a successful discovery refresh.

OpenClaw, Hermes, and Pi only register a live provider source when models.discovery.enabled = true and either command or endpoint is set; with no discovery wiring, those providers stay on builtin/config rows plus the optional models.dev enrichment.

Top-level [model_catalog.sources.models_dev] controls the cross-provider models.dev enrichment source documented in the next section.

env_policy = "filtered" preserves ordinary operator context such as PATH, HOME, and locale while stripping secret-shaped daemon variables before launch. env_policy = "isolated" starts from a small operational allowlist and then adds only AGH session metadata, provider-home variables, and explicit bound_secret slots. home_policy = "operator" lets native CLIs reuse existing login state. home_policy = "isolated" creates $AGH_HOME/providers/<provider> with private permissions, sets PROVIDER_HOME, XDG directories, and known provider-specific home variables such as CLAUDE_CONFIG_DIR, CODEX_HOME, and OPENCODE_CONFIG_DIR.

Credential slots use this shape:

[providers.openrouter]
auth_mode = "bound_secret"

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "vault:providers/openrouter/api-key"
kind = "api_key"
required = true

secret_ref supports env:NAME for operator-managed environment variables and vault:providers/<provider>/<slot> for AGH-managed encrypted provider credentials written through the settings API, agh vault, or web provider editor. The vault: form accepts lowercase provider/slot identifiers only, with letters, numbers, hyphens, underscores, or dots; arbitrary vault paths are not valid provider credential refs.

The slot required flag is enforced at session start for both env: and vault: refs. credential_slots are valid only when auth_mode = "bound_secret". Direct ACP built-ins and the direct pi provider use native_cli by default and do not preflight provider API keys. Pi-backed API-key wrappers such as OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, and Groq default to AGH-managed bound_secret slots while AGH runs Pi under the hood.

[model_catalog.sources.models_dev]

The models.dev enrichment source feeds catalog metadata such as token windows, tool support, and reasoning hints. It is cross-provider, daemon-owned, and never proves account-level availability.

[model_catalog.sources.models_dev]
enabled = true
endpoint = "https://models.dev/api.json"
ttl = "24h"
timeout = "10s"

models.dev rows write provider-scoped status: a single models.dev refresh records one (source_id="models_dev", provider_id) status row per AGH provider mapped, never a global empty-provider sentinel. Disabled sources still expose status but skip outbound calls. Refresh lifetime is daemon-owned: requests trigger refreshes but the daemon detaches the work, applies an explicit deadline, and joins outstanding refresh workers during shutdown.

Live provider discovery is configured per provider through [providers.<id>.models.discovery]. Discovery refresh is serialized per provider_id before any subprocess or provider-home work, and concurrent refresh requests for the same provider coalesce behind the in-flight refresh.

[observability]

[observability.transcripts]

[log]

The daemon writes structured logs to $AGH_HOME/logs/agh.log. Rotation is owned by the daemon's LogSink, so operators do not need an external logrotate rule for the default file.

Changing any [log] key is restart-required in v1. The daemon applies the new rotation writer on the next start.

[memory]

The [memory] tree is the Memory v2 runtime configuration. Memory v2 is the only memory subsystem; there is no [memory.v2] enabled flag and no parallel compatibility namespace. Disabling [memory] enabled short-circuits prompt assembly, the controller, recall, dreaming, the extractor, and the bundled local provider.

[memory.controller]

[memory.controller.llm]

[memory.controller.policy]

[memory.recall]

[memory.recall.weights]

Weights are blended into the recall score. Defaults sum to 1.0.

[memory.recall.freshness]

[memory.recall.signals]

[memory.decisions]

WAL retention controls. Pruned rows are replaced by a redaction-safe summary so audit history survives.

[memory.extractor]

The extractor consumes the session.message_persisted hook and writes structured proposals via the controller. inbox_path and dlq_path are validation-locked to the canonical AGH-managed locations.

[memory.extractor.queue]

[memory.dream]

If enabled = false, the remaining dream validation is skipped.

[memory.dream.gates]

[memory.dream.scoring]

[memory.dream.scoring.weights]

Defaults sum to 1.0 across the four factors.

[memory.session]

Forensic ledger materialization. The materializer writes one read-only ledger.jsonl under <ledger_root>/<workspace_id>/<session_id>/. Sessions without a workspace use <unbound_partition> instead of a workspace_id segment.

[memory.daily]

[memory.file]

[memory.provider]

name = "" selects the bundled local provider. Setting a configured provider name routes runtime calls through the registered MemoryProvider while keeping the local provider as a circuit-breaker fallback (see Extensions).

[memory.workspace]

[skills]

If enabled = false, skill polling and marketplace validation are skipped.

[skills.marketplace]

[extensions.marketplace]

[automation]

[[automation.jobs]]

Jobs are appended by overlays; they do not replace earlier jobs with the same name.

[[automation.triggers]]

Triggers are appended by overlays; they do not replace earlier triggers with the same name.

See Vault for the CLI, HTTP, UDS, web, and session-scoped surfaces that store and inspect encrypted AGH-managed secret refs.

[autonomy.coordinator]

Coordinator config controls whether AGH may start a workspace coordinator when executable task-run work is enqueued. Task creation is not executable work. Creating or saving a task does not enqueue a run, create a coordination channel, or spawn a coordinator. Publish, start, approval, and equivalent run-enqueue APIs are the execution boundary.

Coordinator launch only applies to workspace-scoped coordinated runs with a stable coordination_channel_id. Global runs and intent-only tasks do not start coordinators in the MVP.

Provider and model resolution is intentionally narrow. The daemon applies:

1. Workspace .agh/config.toml override for the resolved workspace.
2. Global $AGH_HOME/config.toml.
3. The bundled/default coordinator agent definition and provider defaults.

Safe-spawn limits still apply after a coordinator starts. Coordinator children inherit the workspace and coordination channel, must use a positive TTL, and can only narrow the coordinator's permission set.

[task.orchestration]

[task.orchestration] controls bounded task orchestration behavior: run summaries, task context bundles, scheduler health telemetry, the spawn-failure circuit breaker, and the per-task max-runtime default. The defaults shown below are loaded from internal/config/task_orchestration.go and apply when neither the global file nor a workspace overlay sets a value.

[task.orchestration] keys are agent-mutable through the existing config tool surface (agh config set and the agh__config_* native tools). Workspace overlays apply through the existing config loader without any special handling.

Config and hook mutation tools return lifecycle truth in their structured payloads. Writes under hooks.* and extensions.* are persisted as desired state with applied=false, lifecycle="restart-required", and next_action="restart-daemon"; agents should not treat those writes as active runtime truth until the daemon restarts.

[task.orchestration.profile]

Defaults and gates that apply when a task does not store its own execution profile, plus the gates that allow or reject task-level provider/sandbox overrides. See Task Execution Profiles for the runtime behavior.

Profile validation runs in task.Service when a profile is created or updated; the normalized profile is then stored. Session start loads the persisted profile (or the default inherit profile when none exists) without re-running validation. Updates and deletes are rejected while the task has an active run (tasks.current_run_id is set); resolve or release the run before retrying.

Per-task profiles also store sandbox.mode and runtime.mode. sandbox.mode accepts inherit, none, or ref; ref requires sandbox.sandbox_ref and resolves a named [sandboxes.<name>]. runtime.mode accepts default or evidence. Evidence mode adds runtime evidence guidance and widens session permissions only when the same profile explicitly selects sandbox.mode = "ref"; inherited or disabled sandbox modes keep the configured permission policy.

[task.orchestration.review]

Defaults and bounds for the post-terminal review gate. These values shape the task.review_policy defaults and the bounded reviewer evidence enforced by task.Service.RecordRunReview.

Workspace overlays may tighten or relax these values per workspace through <workspace>/.agh/config.toml. Unknown keys still fail validation.

[task.recovery]

[task.recovery] controls who may call the task-run recovery verbs documented in Task Runs and Leases. The setting does not change normal token-fenced claim, heartbeat, complete, fail, or release tools.

Set allow_agent_force = false when recovery should require a non-agent operator identity. The CLI/API/UDS surfaces then return a deterministic authorization diagnostic for agent callers and leave the run unchanged.

[[hooks.declarations]]

Config hooks merge by name; a later overlay replaces the whole hook declaration with the same name.

Supported matcher fields are agent_name, agent_type, workspace_id, workspace_root, session_type, input_class, acp_event_type, turn_id, tool_name, tool_namespace, tool_read_only, decision_class, message_role, message_delta_type, compaction_reason, and compaction_strategy.

Current hook events are:

session.pre_create
session.post_create
session.pre_resume
session.post_resume
session.pre_stop
session.post_stop
input.pre_submit
prompt.post_assemble
event.pre_record
event.post_record
automation.job.pre_fire
automation.job.post_fire
automation.trigger.pre_fire
automation.trigger.post_fire
automation.run.completed
automation.run.failed
agent.pre_start
agent.spawned
agent.crashed
agent.stopped
turn.start
turn.end
message.start
message.delta
message.end
tool.pre_call
tool.post_call
tool.post_error
permission.request
permission.resolved
permission.denied
context.pre_compact
context.post_compact

[network]

Related Pages

• mcp.json documents JSON sidecars and whole-object replacement.
• AGENT.md documents agent-local mcp_servers and hooks.
• Providers covers [providers.<id>.models] shape and models.discovery defaults.
• Provider Model Catalog explains the catalog projection, OpenAI-compatible endpoint, and extension model.source.
• File Locations lists the exact global and workspace paths.