Conformance#

Required vs. optional — summary matrix#

Element	Level	See
Single-file `agent.hcl` at project root	MUST	`README.md`
Global config never contains provider auth	MUST	`settings-and-global.md`
`required_providers`/`provider`/`policy`/`agent_profile`/`hook`/`settings` as the only top-level blocks	MUST	`blocks-reference.md`
Schema-to-`cty` bridge via `ConfigSchema`	MUST	`blocks-reference.md`
`sensitive` attributes reject literal expressions	MUST	`blocks-reference.md`
`env()` fails fast on unset variable	MUST	`blocks-reference.md`
`source`/`version` constraint syntax matching Terraform's operators	MUST	`blocks-reference.md`
Provider aliasing (multiple instances per entry)	Not supported (v1), confirmed	`blocks-reference.md`
`token_budget` as reserved convention field	MUST, where applicable	`blocks-reference.md`
Most-specific-wins policy conflict resolution	MUST	`policy-dsl.md`
Identical-specificity-and-value policy conflict	MUST be config-load-time error	`policy-dsl.md`
Policy evaluation covers `data_source` and `interactive` calls (allow/deny only)	MUST	`policy-dsl.md`
`ask` on a `data_source`/`interactive` match downgrades to `deny` with a logged warning	MUST	`policy-dsl.md`
`PolicyMatch.kind` restricted to `resource`/`data_source` (no `interactive` value)	Documented v1 limitation	`policy-dsl.md`
Implicit root profile named `default`	MUST	`agent-profiles.md`
Structured `model` block (primary + fallback)	MUST	`agent-profiles.md`
Capability-aware fallback eligibility	MUST	`agent-profiles.md`
Strict-default (empty) tool scoping when `tools` omitted	MUST	`agent-profiles.md`
Strict-default (empty) `slash_commands` scoping when omitted	MUST	`agent-profiles.md`
Inherited, only-shrinking `max_depth` budget	MUST	`agent-profiles.md`
Loop bounds as `agent_profile` fields, no separate `session` block	MUST	`agent-profiles.md`
Explicit `hook` block for non-default subscriptions	MAY	`agent-profiles.md`
Textual-position ordering across implicit + explicit hook subscriptions	MUST	`agent-profiles.md`
`settings{}` block, including `retry{}` canonical defaults	MUST (block exists); values operator-overridable	`blocks-reference.md` / `settings-and-global.md`
`observability{}` all-or-nothing once declared	MUST	`blocks-reference.md`
`dev_overrides` in global config	MUST (mechanism); SHOULD (used)	`settings-and-global.md`
`registry_mirror` with per-prefix `mirror{}` blocks	MAY	`settings-and-global.md`
`registry_mirror`/`mirror.auth` forbids literal secrets	MUST	`settings-and-global.md`
Kernel-written lock file, `lock_file_version` checked on open	MUST	`lock-file.md`
Lock file checksums cover every installed platform, not just the invoking one	MUST	`lock-file.md`
Checksum re-verified on every install, not just first resolution	MUST	`lock-file.md`

Open questions#

Provider aliasing / multiple instances is not supported in v1: running the same required_providers entry twice with different config (e.g. two filesystem roots with different permissions) is out of scope. The real syntax design this would need (naming collisions, disambiguated tool-reference syntax) is deliberately deferred. This interacts with the memory provider's MemoryScope, which resolves the specific cross-scope-memory case that aliasing would otherwise have been needed for — see ../memory/README.md.
No import/split mechanism remains genuinely live — a direct consequence of the single-file decision (see README.md#file-location--loading): large configs have no relief valve if they outgrow one file comfortably. Not raised as a problem in practice yet, but worth watching as real agent.hcl files grow.