Skip to content

v1.8.1 — DSL dual-key bypass closed

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 16:28
· 4 commits to main since this release

What's new in v1.8.1

A targeted fix for a latent bypass in the §7 Comprehension Contract enforcement, flagged by the external review of v1.8.0.

The bug

Before v1.8.1, _apply_changes had a backwards-compat fallthrough that silently deep-merged any unknown top-level key as a literal YAML patch. A caller passing the legacy capability_add name (singular — the exact v1.6.x bug key) bypassed the DSL entirely:

  1. _change_action_class inferred mirror_patch (not mirror_capability_add)
  2. ACTION_BLAST_RADIUS[mirror_patch] is not in the table → default Local
  3. Blast-radius-ceiling check passed trivially
  4. Forbidden-list keyword match missed ("add new teaching" doesn't appear in "Patch mirror with keys: ['capability_add']")
  5. _apply_changes deep-merged capability_add as a top-level YAML key — the exact v1.6.x failure mode the DSL was meant to kill

The review's exact words: "the Comprehension Contract enforcement can still be fully bypassed by a caller using the legacy key name."

The fix

Three lines, as the reviewer suggested. Both substrates now reject any top-level key not in {add_capability, remove_capability, patch} up front:

KNOWN_DSL_KEYS = {"add_capability", "remove_capability", "patch"}
for key in changes:
    if key not in KNOWN_DSL_KEYS:
        raise ValueError(f"Unknown change DSL key: {key!r}. …")

Unknown keys get a "did you mean …" hint in the exception message for ergonomics, but they raise. No fallthrough.

Four new regression tests

In examples/teaching_colony/tests/test_contract_enforcement.py:

  1. test_legacy_capability_add_key_is_rejected — provokes the exact v1.6.x bypass
  2. test_random_unknown_dsl_key_is_rejected — generalises to any non-DSL key
  3. test_patch_key_still_works_for_legitimate_literal_updates — confirms the explicit patch escape hatch survives
  4. test_mixed_dsl_and_legacy_key_rejects_entire_change — atomic gate: a mix of valid and invalid keys rejects the whole change before any mutation

Four existing tests migrated

Tests that used the pre-DSL nested-dict form {"capabilities": {"capabilities": [...]}} now use the semantic add_capability DSL key instead. This was necessary because the nested-dict form relied on the (now-removed) fallthrough.

Test results

76 passed, 3 deselected (live), 2 xfailed

Four more tests than v1.8.0. Every pre-existing mock-mode test still green.

Why v1.8.1 and not fold into v1.9

The review landed after v1.8.0 shipped. Folding this into v1.9 would mean releasing v1.8 with a known governance hole for however long v1.9 takes. That repeats the v1.6.x failure mode the §7 hardening was meant to close. Tiny targeted patch, ship now, keep v1.9 a clean increment.

The §7 enforcement story — final form

After v1.7.0 the Comprehension Contract had four real checks (co-signer presence, blast-radius-ceiling, forbidden-list, policy freshness) implemented in update_mirror. The review's finding was that these checks ran on the wrong classification when the caller used an unknown top-level key, because the fallthrough turned the change into a literal patch. v1.8.1 removes the fallthrough. The §7 enforcement story no longer has a qualifier.


Cite as:

Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.1). https://github.com/DavidROliverBA/agent-colony-pattern