Skip to content

docs(adr): add ADR 0158 on overlay runtime-fetch grants - #9086

Merged
waynesun09 merged 3 commits into
fullsend-ai:mainfrom
tpouyer:issue-AISDLC-500
Nov 6, 2026
Merged

waynesun09 merged 3 commits into
fullsend-ai:mainfrom
tpouyer:issue-AISDLC-500

Conversation

@tpouyer

@tpouyer tpouyer commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds ADR 0158: a matching overlay may grant runtime fetch (allowed_remote_resources, allow_runtime_fetch, max_runtime_fetches), bounded by the config-level allowlist. It amends ADR 0112, whose Decision 1 lets an overlay set any field but leaves these three with no merge rule, because base: composition drops them.

The decision, after review:

  • Every prefix an overlay adds must pass the prefix test against the config-level list, on every overlay entry, matching or not.
  • When a matching overlay sets allow_runtime_fetch, every prefix of the merged list, top level included, must pass the same test, whether or not the harness has URL references.
  • An overlay that sets allow_runtime_fetch: false or an empty allowed_remote_resources fails validation.
  • The cap is replaced, so it can be raised or lowered within ADR 0024's range; matching overlays apply in file order, and the last cap set wins.

Docs only, no implementation, per docs/contributing/adrs.md. The implementation is the AISDLC-445 work, which will stack on this PR and implement all four rules.

Review of #8829 asked for this to be recorded as a decision rather than as an annotation on the accepted ADR.

Changes

  • docs/ADRs/0158-overlays-may-grant-runtime-fetch-within-the-config-allowlist.md: new ADR, status Accepted.
  • docs/ADRs/0112-overlays-may-set-any-harness-field.md: an Amended by ADR 0158 note under Status, after the ADR 0151 note. A minor annotation; no other text changes.
  • docs/architecture.md: one sentence in the overlays bullet, still marked "Decided, not yet implemented".
  • docs/contributing/harness-fields.md: ADR 0158 added to the "Decided, not yet implemented" banner, beside ADR 0112, because the field tables there change when both are implemented. This edit goes beyond the three the issue lists.

Numbering

The issue first named this ADR 0152. 0152 is now 0152-hook-interpreter-trust on main, and open PRs #8969, #9024 and #9026 hold 0155–0157, so 0158 is the lowest number free on main and in open PRs.

Evidence for claims about current behavior (at 04fc17a)

  • base: composition drops the three fetch fields. The "NOT merged from base" comment is at internal/harness/compose.go:918, in mergeBaseIntoChild. docs/reference/harness-reference.md:507 says the same.
  • The commands test a harness's list by prefix after normalization. This is (*Harness).ValidateAllowedRemoteResources, at internal/harness/harness.go:1067.
  • The top-level list is checked only by run, lint and lock, and only when the harness has URL references. The checks are behind HasURLReferences() at internal/cli/run.go:780, internal/cli/lint.go:344 and internal/cli/lock.go:335.
  • A non-empty top-level list starts the fetch service in every context (the deprecated implicit opt-in, [Tracker] Deprecated features that need to be removed at some point #7155). See shouldStartFetchService at internal/cli/run.go:3274.
  • An omitted config-level list means the default prefixes, and an explicit [] stays empty. See config.EnsureDefaultAllowedRemoteResources at internal/config/config.go:669.
  • lock does not compose a harness whose lock entry is current. It returns at internal/cli/lock.go:234.
  • The runtime fetch service fetches only GitHub-hosted URLs. See internal/fetchsvc/service.go:174.
  • Overlay fetch keys are inert today. OverlayEntry holds only when and ForgeConfig (internal/harness/forge.go:38), and ForgeConfig has no fetch fields.

Scope notes

  • The interim refusal of agent, agent_input, plugins and api_servers in the overlays of a URL-fetched harness is not part of this ADR. It is an implementation limitation documented in the field reference and removed by later work.
  • The last Consequence names an existing gap and leaves it as separate work: unless a matching overlay sets allow_runtime_fetch, a harness's own top-level list is checked against the config-level list only by run, lint and lock, and only when the harness has URL references.

Overlapping open PRs

Checks

  • make lint passes, including the ADR status, number and frontmatter linters and the markdown link check. go vet passes too.
  • hack/ci-local/ci-local go-test passes.
  • ADR 0158 is 78 content lines.

Jira: AISDLC-500

@tpouyer
tpouyer requested a review from a team as a code owner November 3, 2026 19:53
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown

E2E tests did not run

E2E tests run automatically for pull requests authored by users with write access or higher.

For other contributors, someone with write access must add the ok-to-test label after the latest push.

Reason: unauthorized

See E2E testing guide for details.

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Document bounded runtime-fetch grants for harness overlays

📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Record ADR 0158’s decision to permit context-specific runtime fetch without exceeding the config
 allowlist.
• Specify validation of every overlay prefix, including entries that do not match the current
 context.
• Cross-reference the decision in ADR 0112 and living documentation; implementation remains future
 work.
Diagram

graph TD
  A["Overlay entry"] --> C{"Prefix allowed?"} --> D["Merged harness"] --> E["Runtime fetch grant"]
  B["Config allowlist"] --> C
  C --> F["Reject harness"]
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Exclude fetch fields from overlays
  • ➕ Avoids introducing overlay-specific fetch validation.
  • ➖ Requires a separate composed harness for context-specific fetch permissions.
  • ➖ Creates an exception to ADR 0112’s general overlay decision.

Recommendation: The ADR’s bounded-grant approach supports per-context fetch without expanding the repository’s configured allowlist. Recording it separately from implementation also preserves ADR 0112 as a point-in-time decision.

Files changed (4) +102 / -4

Documentation (4) +102 / -4
0112-overlays-may-set-any-harness-field.mdAnnotate ADR 0112 with its runtime-fetch amendment +4/-0

Annotate ADR 0112 with its runtime-fetch amendment

• Adds a short Status-section cross-reference to ADR 0158 without rewriting the accepted decision.

docs/ADRs/0112-overlays-may-set-any-harness-field.md

0158-overlays-may-grant-runtime-fetch-within-the-config-allowlist.mdRecord the bounded overlay runtime-fetch decision +89/-0

Record the bounded overlay runtime-fetch decision

• Defines how matching overlays grant fetch fields and how every added prefix is checked against the config-level allowlist. Covers rejected grants, base composition, forge scope, and consequences.

docs/ADRs/0158-overlays-may-grant-runtime-fetch-within-the-config-allowlist.md

architecture.mdAdd the planned fetch grant to the overlay architecture +4/-1

Add the planned fetch grant to the overlay architecture

• Links ADR 0158 from the overlay design summary and retains its not-yet-implemented status.

docs/architecture.md

harness-fields.mdFlag future harness-field behavior from ADR 0158 +5/-3

Flag future harness-field behavior from ADR 0158

• Adds the runtime-fetch decision to the pending-implementation notice while leaving the current-behavior field tables unchanged.

docs/contributing/harness-fields.md

@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can tweak Display settings with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:57 PM UTC · Completed 8:05 PM UTC

Commit: 5b30833 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.77

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://b47d2e80-site.fullsend-ai.workers.dev

Commit: 466670b3b281487e9755cb927ce09302d0391a68

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Documentation-only PR adding ADR 0158 with no protected paths or security-sensitive changes, elevated to moderate risk by high commit churn and multi-author contention on existing architecture documentation.

Previous run

<!-- fullsend:risk-assessment -->
Risk Assessment: moderate (2/5)

Details

Documentation-only PR adding ADR 0158 with no protected paths or security-sensitive changes, elevated to moderate risk by high commit churn and multi-author contention on existing architecture documentation.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Looks good to me

Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOltdfQ== -->

Looks good to me

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 3, 2026
@codecov

codecov Bot commented Nov 3, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ADR review: 0158, overlays may grant runtime fetch within the config-level allowlist

The direction is right: give the three fetch fields a merge rule, and bound an overlay's prefixes by the config-level list. I checked every code claim in the PR body against 04fc17ae2, and they all hold. I found no way around the prefix test: case, .. (including %2e%2e), an org/ vs org-evil/ mismatch, ports, userinfo, and a query or fragment in an entry all fail closed. The 0112 note is an annotation only, and 0158 doesn't collide with main or any open PR.

Requesting changes for item 1. Items 2 and 3 are medium. Details are in the inline comments.

Blocking

  1. Turning fetch on also enables a top-level list that was never checked. At fetch time, the service checks a URL only against the harness's own merged list (fetchsvc/service.go:160). The config-level list isn't consulted. This ADR checks only the prefixes an overlay adds, and the top-level list is checked only when the harness has URL references (the gap the last Consequence names). An overlay that sets just allow_runtime_fetch: true therefore enables fetch over a list the ADR never bounds.
    • Today this is hidden because any non-empty top-level list already starts the fetch service (#7155). Once that opt-in goes, the overlay switch becomes the way fetch turns on, and "bounded by the config-level allowlist" no longer holds for that run.
    • Suggest adding to the Decision: "When a matching overlay turns fetch on, every prefix of the merged list must pass the same test." At minimum, extend the last Consequence to say the bound covers only the prefixes the overlay adds.

Medium

  1. max_runtime_fetches "replaced" has no stated direction. An overlay can raise the cap up to ADR 0024's maximum, and nothing bounds that the way the allowlist bounds prefixes. An overlay meant to lower the cap for a narrower context does nothing whenever its condition doesn't match. Please say whether an overlay may raise the cap, only lower it (min), or both. Also say how several matching overlays combine: prefixes append in order, and the last cap set wins?

  2. Cross-field rules are checked only on the merged harness, so lint and dispatch miss them. Prefixes are checked on every entry without an event, but the cross-field rules run after overlay resolution, and an overlay keyed on an event never matches there. Examples:

    • An overlay sets allow_runtime_fetch: true, with no prefix in the overlay or at top level.
    • max_runtime_fetches is set at top level with allow_runtime_fetch only in an overlay. Every context where the overlay doesn't match then fails, and dispatch skips the agent.

    Suggest checking each overlay entry merged alone onto the top level, or adding a Consequence that these failures surface only in runs where the overlay matches.

Low

  • An overlay allow_runtime_fetch: false is silently ignored. ADR 0112 drops false, zero and empty overlay values. "An overlay cannot turn fetch off" is right, but an author who writes false on a fork-PR overlay gets no error. Consider making a false or empty value in an overlay a validation error.
  • Overlays in a base: harness. Their prefixes are checked against the child's config list, but mergeBaseIntoChild drops the fetch fields, so the grants never reach the child. A shared base can then break children whose config lacks the prefix, for no security gain. Either skip the allowlist check for base overlays, or name bases in Consequence 3.
  • Consequence 3 overstates where failures surface. lock returns early when its entry is current, so it fails only when it recomposes. Dispatch skips the agent with an error annotation, or falls back to the write-access gate, rather than failing.
  • Implicit opt-in. While #7155 remains, an overlay that only adds prefixes also starts the fetch service. One sentence would say so.
  • Readability.
    • Gloss "overlay", "base: composition" and "config-level allowlist" on first use.
    • List the three merge rules as bullets.
    • Split the "check runs on every overlay entry" sentence.
    • Make Options two bullets.
    • In docs/architecture.md, change "inside the config-level allowlist" to "within".

@rh-hemartin rh-hemartin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me.

Record the decision that a matching overlay may grant runtime fetch,
with every prefix it adds bounded by the config-level allowlist, and
annotate ADR 0112, docs/architecture.md and the harness field reference.
Refs https://redhat.atlassian.net/browse/AISDLC-500.

Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
Land round 1: the doc edits the round's change needs.

Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
Land round 1: the doc edits the round's change needs.

Signed-off-by: Tim Pouyer <tim.pouyer@gmail.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 12:48 PM UTC · Completed 12:57 PM UTC

Commit: 466670b · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.89

@fullsend-ai-review fullsend-ai-review Bot removed the ready-for-merge All reviewers approved — ready to merge label Nov 4, 2026
@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 4, 2026 12:57

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 4, 2026

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 466670b. All five findings from my review are addressed in the ADR text: an overlay that turns on fetch now makes the whole merged list, top level included, pass the config-level prefix test; the cap is replaced within ADR 0024's range with the last overlay winning; Consequence 3 says where each failure shows; false or an empty list fails the load; and a base's fetch fields stay in the base while its entries are still checked. The remaining top-level gap is named as separate work. 0158 is still free on main.

@waynesun09
waynesun09 added this pull request to the merge queue Nov 6, 2026
Merged via the queue into fullsend-ai:main with commit 1289493 Nov 6, 2026
63 checks passed

This branch was successfully deployed

1 active deployment
site-preview — 466670b3 Deployed Nov 4, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-merge All reviewers approved — ready to merge risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants