Skip to content

Agent Config as a Managed Supply Chain

Pin agent config files by content hash and declared permissions so consumers know what bytes they read and approvers see every change.

Agent configuration files — CLAUDE.md, AGENTS.md, .cursor/rules/, IDE-specific markdown — propagate across repositories as an undeclared shared-component supply chain. A 2026 prevalence study of 10,008 public GitHub repositories (Carey et al., arxiv:2606.26924) measured 6,145 such files and found three governance gaps that justify managing them with the same discipline mature ecosystems apply to packages: cross-org duplication, near-zero revision cadence, and almost no declared permission boundaries.

When the Pattern Applies

Content addressing, pinning, and permission declaration add operational surface — a registry, a pinning convention, a drift detector, an approval workflow. They earn their keep under specific conditions:

  • Multiple repos consume the same config bytes — a scaffolder, a template, or a platform team distributing one canonical AGENTS.md to every service repo.
  • Multiple environments need different versions of the same config, with tag-based promotion replacing copy-paste.
  • Regulated or audited environments where "what did the agent read at runtime" is an evidence requirement.
  • Cross-team policy distribution where silent drift between copies is the failure mode being guarded against.

Single-repo single-team stacks already get versioning, PR review, and rollback from git on the consuming repository. Adding a control plane buys little there.

What the Study Found

Carey et al. (arxiv:2606.26924) measured three governance gaps across 6,145 agent config files in 10,008 public repos:

Signal Measurement Comparator
Cross-repo duplication 10.1% of paths are SHA-256 exact duplicates (fork-adjusted) —
Cross-org propagation 75.5% of clone pairs cross organisational boundaries —
Revision cadence 58% single-commit; 0.4 commits/month 0.6 commits/month for comparator files
Permission declarations <1% of agent configs declare permission boundaries 33% of GitHub Actions workflows

The duplication is mostly cross-organisation — these are not just fork copies. The revision rate is half that of comparable repo files. And where GitHub Actions workflows reached a third-of-files-declare-permissions baseline, agent configs sit near zero. The same paper proposes a "deterministic control plane" — content addressing, permission enforcement, state-machine promotion, drift detection — as the structural response (arxiv:2606.26924).

The Four Control-Plane Mechanisms

The paper's prescription, mapped to artifacts a practitioner team can adopt incrementally:

  1. Content addressing. Hash the bytes (SHA-256) and pin consumers to a specific hash, not a path or a moving branch. Every agent run can prove which exact configuration produced its behavior — the question "what did the agent actually read?" becomes answerable from a log.
  2. Permission declaration. Add an explicit boundaries section to the config — tools the agent may use, paths it may read, paths it may write, network destinations it may reach. This is the same shape as a GitHub Actions permissions: block, which is why the 33% baseline is a meaningful comparator.
  3. State-machine promotion. Tag environments (dev, staging, prod) and promote a hash from one tag to the next under PR review. The config never advances silently. This is the same control-plane / data-plane split that worked for feature flags and that the Shared Context Bundle Registry applies to multi-agent context.
  4. Drift detection. Continuously compare the pinned hash against the consuming repo's runtime bytes and the upstream canonical bytes. A mismatch is a notification, not a silent regression.

Convergent 2026 research reaches similar architectural conclusions from a security angle: Trinity (arxiv:2602.09947) treats the LLM as untrusted and runs a deterministic policy check between proposal and execution; AgentGuardian (arxiv:2601.10440) learns access-control policies for agent behavior.

Why It Works

The mechanism is auditability and rollback, not compliance. The causal chain runs in three steps: hashing the bytes creates a stable referent that a log entry can name; the referent enables a byte-for-byte diff between two versions of the config; the diff enables an approval gate that catches every change before it advances to a tagged environment. Without addressing, the config is just bytes at HEAD — the same diff is possible in principle but no log entry can prove which bytes ran. With addressing, every change is a hash transition tied to an approval (Carey et al., arxiv:2606.26924). The supply-chain analogy is load-bearing: shared components without provenance and declared permissions are the documented attack surface every package ecosystem has had to retrofit, from npm to PyPI to GitHub Actions.

Example

The mature comparator is a GitHub Actions workflow's permissions: block, already present in 33% of workflows (Carey et al., arxiv:2606.26924):

# .github/workflows/release.yaml
permissions:
  contents: read
  pull-requests: write

Two pieces of information land in one block: the agent's allowed surface and a structured artifact the consuming repo, CI, and any downstream auditor can read. The supply-chain prescription is to give agent configs the same shape — a declared permissions surface that lives next to the prose, plus a hash-and-tag pinning convention so consumers know which exact bytes they are using. The paper proposes "Rel(AI)Build" as one such control plane (arxiv:2606.26924); the practitioner takeaway is the shape, not the specific tool.

When This Backfires

The qualified scope is not decoration — several conditions invert the recommendation:

  • Compliance is not the benefit. McMillan (2026, arxiv:2605.10039) ran a factorial study across 1,650 Claude Code sessions and found rearranging configuration files does not measurably change compliance within realistic file sizes. The gain from this pattern is governance, not behavior — see Configuration File Structure Does Not Drive Compliance.
  • The execution layer is the real security boundary. Hooks for Enforcement vs Prompts for Guidance blocks deterministically regardless of what the markdown says; a config-layer permission DSL whose violations are advisory adds review overhead without closing the breach path.
  • Single-repo single-team stacks. Carey et al.'s 75.5% cross-org clone rate is the population the pattern is for; a config consumed only by agents in its own repo gets versioning and rollback from existing git history for free.
  • Short-lived projects. Hashing, pinning, and drift detection only amortise across repeated promotion cycles.
  • Apples-to-oranges permission gap. The <1% vs 33% comparison is partly a measurement artifact: agent configs often declare boundaries in unstructured prose the Carey et al. regex-based detector cannot pick up. Leading with the comparison overstates the gap.
  • Standardised duplication is not negligent duplication. The 10.1% exact-duplicate rate does not distinguish copy-paste-and-forget from deliberate adoption of an industry template (the agents.md spec is itself copy-able). The failure mode is unpinned duplication, not duplication.
  • Developer outcomes are unvalidated. Carey et al. explicitly defer "developer outcomes" to future work — the control plane's mechanisms are tested for conformance only.

Key Takeaways

  • A 2026 prevalence study of 10,008 repos found agent configs are an undeclared shared-component supply chain: 10.1% exact-duplicate rate, 75.5% cross-org propagation, near-zero revision cadence, <1% permission declarations (Carey et al., arxiv:2606.26924).
  • Four control-plane mechanisms close the governance gap: content addressing, permission declaration, state-machine promotion, drift detection.
  • The pattern earns its keep at multi-repo, multi-team, or regulated scale. Single-repo single-team stacks already get the benefit from git.
  • The benefit is provenance and rollback, not model compliance. McMillan 2026 shows file structure does not move compliance — the pattern's value lies elsewhere.
  • The execution layer (hooks, sandboxes, capability tokens) is the real security boundary. Config-layer permission DSLs are governance artifacts, not enforcement mechanisms.
Emerging — single recent source Last reviewed: 2026-06-26
Feedback