154. Agent entries may overlay harness fields
Date: 2026-10-30
Amends: ADR 0049, ADR 0080, ADR 0081, ADR 0091
Status
Accepted
Context
An agent's tuning knobs are variables in its harness env.runner and env.sandbox. ADR 0049, ADR 0080 and ADR 0081 leave a repo one way to change one: compose a harness through base: (or copy it). ADR 0091 lets an agents: entry set runtime, model and effort but keeps config.yaml from composing a harness; entries have since gained subagents (ADR 0104) and trigger (#8726). A base: harness pins an agents commit that nothing moves forward automatically (#5802), so a repo that changes one value stops getting agent updates. That has blocked REVIEW_FINDING_SEVERITY_THRESHOLD (#6822, #8143), GITHUB_SIGNED_COMMITS (#8903, closed in favor of #8143) and a longer code-agent timeout (#7223).
The discussion on #7719 asked for one general way to override harness fields from config.yaml, not a config field per setting. Harness overlays already merge a partial harness onto a resolved one (mergeForgeConfig), and ADR 0112 decides that overlays may set any harness field (not yet implemented). config.yaml comes from the same ref as a local harness file: on GitHub, the PR base SHA for pull_request_target and pull_request_review and github.sha otherwise (reusable-dispatch.yml, the same expression in every agent job); on GitLab, the default branch (run-agent-job.sh).
This ADR aims to let a repository change an agent's knob from config.yaml without composing and pinning a harness, and without adding a config field per setting.
Options
- Harness fields directly on the entry, such as a bare
env:(as #8143's triage shows) ortimeout_minutes(#7223). Each needs its own placement and merge rules and shares a namespace with the entry's own fields, such asmodel. - Keep
base:and automate pin updates (#5802). A repo still keeps a harness file per change; this complements the decision. - A file overlay like
customized/(ADR 0035), which ADR 0064 removed as redundant withbase:composition. - A
harness:block on the entry. Chosen: it reuses the overlay merge and keeps harness fields apart from the entry's own.
Decision
We let an agents: entry carry a harness: block that overrides harness env values, so a repo can change an agent's knob without a base: harness.
agents:
- name: review
harness:
env: # runner and sandbox are set independently
runner: { REVIEW_FINDING_SEVERITY_THRESHOLD: medium }
sandbox: { REVIEW_FINDING_SEVERITY_THRESHOLD: medium }- Fields. The block takes only
env, where every knob above lives. Any other harness field, including those ADR 0112 lets overlays set, joins only through a later decision. It may sit on any enabled entry. - When.
fullsend runandfullsend lintread the entry before harness composition (todayfullsend runreads per-agent settings after it) and merge the block with the overlay merge afterbase:,forge:and the harness's overlays, before validation. Dispatch andfullsend lockdo not merge it. Values get the harness's${VAR}expansion and checks. Each key replaces the harness value, or adds it when theforge:block or overlay that declares it did not apply, and an empty string sets it empty, as an overlay'senvdoes. - Precedence. A per-run override where the variable has one, then the block, then the harness, then the default, as in ADR 0091.
- Layers. Block keys merge per key across
config.base.yamlandconfig.yaml,config.yamlwinning. A~inconfig.yamldrops a keyconfig.base.yamlset, so the harness value applies again, as~does forsubagents; unlike in a harness file,~is not an empty value. - Checks. Mistakes fail loudly, as #8143 asks. Agent-entry validation (
ValidateAgentEntries, applied byfullsend run,fullsend lintand dispatch) rejects an unknown key in the block and a name the sandbox gate reserves, in either section.fullsend runandfullsend lintreject a name the harness does not declare in that section, naming the agent and variable. A name is declared if any layer of the harness, the file or abase:ancestor, sets it in that section at top level, in aforge:block or in an overlay, whatever the forge or event; composition records these names before it resolvesforge:blocks and overlays. Run and lint then agree on a variable such asGITHUB_SIGNED_COMMITSthat only a forge overlay declares. Adding an undeclared name still takesbase:. Strict decoding of the rest of the entry stays with #7223. - Settings. A non-empty block counts as a setting (
HasSettingsand the dispatch workflow's entry check), so a block-only entry stays override-only and registers no harness.
This amends the override convention of ADR 0049, ADR 0080 and ADR 0081: a knob stays one harness variable, settable in the harness or through the block, so ADR 0080's "one settable location" becomes one name with two places. It loosens ADR 0091's rule that config.yaml does not compose a harness, for env only.
Forge scope
Forge-neutral: the CLI merges the block on every forge.
- GitHub: the reusable dispatch workflow's entry check must count the block.
- GitLab: no workflow-side entry check exists; nothing else changes.
- Forgejo: fullsend has no Forgejo support yet; nothing to change.
Consequences
- A repo sets
REVIEW_FINDING_SEVERITY_THRESHOLDorGITHUB_SIGNED_COMMITSin one entry and keeps getting agent updates; a longer timeout (#7223) needs a later decision that addstimeout_minutesto the block. - Whoever changes
config.yaml,config.base.yamlor therepos.yamlthat renders them reaches as far as abase:harness'senv, which ADR 0112 accepts from config as a trusted source: expanding a runner variable into the sandbox, setting a declaredGH_TOKENto another runner variable, or emptyingREVIEW_PROTECTED_PATHS. - ADR 0122's safety gate does not compare block values, so a
repos.yamlchange that emptiesREVIEW_PROTECTED_PATHSis not flagged; extending the gate is follow-up work. - The plan output names
config.yamlas the source,fullsend agent setgains a way to write the block, and docs here and in fullsend-ai/agents that namebase:as the only override path are updated. - An older workflow pin or CLI rejects a block-only entry, and an older CLI ignores the block beside another setting, so repos update both.
