← Back to Blog

The Lock Ceremony

May 2026 • 6 min

Tier 2 Architecture Seed Agent Plugins Plugin Kit PLUGIN-LOCK TEST-LOCK Safe-lock Historian

By Hadi Nayebi & Claude Opus 4.8

Listen to this article (6 min)

Essay 7.8 — The Plugin Kit, Part 8 of 9.

Essay 7.7 closed the kit’s anatomy — the smaller organs that round out specialized plugins, and the brain-root wiring file that decides which hooks ever fire. With every organ named, one question is left: how does the hard substrate get edited safely once the plugins are alive? Hooks, scripts, tests, hidden state, and plugin birth can corrupt the plugin or the agent’s whole enforcement layer when mishandled; soft narrative and voice surfaces have their own phase discipline. This sub-essay opens the ceremony that protects hard-substrate edits.

The Parts of the Ceremony

Plugin code does not get edited the way ordinary files do. Each plugin’s hooks, scripts, tests, and code-bearing files have earned their current shape; the test suite enshrines that shape; any change pays the cost of opening the plugin, editing inside it, and re-passing the tests before the change commits. ^ⓘ

The parts of the ceremony form a closed loop: PLUGIN-LOCK opens an edit session, TEST-LOCK gates test edits inside it, safe-lock close-out commits or reverts on the test result, and the historian ratchet can refuse to open the lock at all when the plugin’s narrative has fallen behind. Each part guards a different risk; together they make plugin edits earn their landing.

`[PLUGIN-LOCK]` — Opens an Edit Session

The agent issues a structured AskUserQuestion prefixed [PLUGIN-LOCK] <plugin_name> with a body long enough to surface the cognitive work (currently a 100-word floor in the prototype, configurable) naming which plugin it will open, the specific changes it intends to make, why this plugin specifically, and the tests it will run. The operator approves; lock-manager.sh captures a git rev-parse HEAD SHA as checkpoint_ref and writes the unlocked plugin name into plugin_integrity's hidden data.json. From that moment, edits inside the unlocked plugin proceed; edits anywhere else under .claude/plugins/ are rejected. ^ⓘ

Two protected contexts for plugin-substrate edits. Editing an existing plugin or birthing a new one requires one of two protected contexts: (A) [GMODE] with a body long enough to surface the cognitive work (currently a 100-word floor in the prototype, configurable) — the operator’s deliberate maintenance lane; or (B) a focused job whose top-level plugin_lock_approval flag is set — established by the user confirming one of two agent-proposed approval questions: [JOB-APPROVE-CREATION], which mints a new job already cleared for plugin work, or [JOB-APPROVE-PLUGIN], which raises the same flag on the focused job already in flight when its work turns out to need a plugin edit. Either way the flag is set; a job is never locked into creation-time-only approval. New-plugin birth does not bypass the gate. Creating a plugin writes the agent’s enforcement substrate too, so the same approval rule applies whether the target directory already exists or not. ^ⓘ

`[TEST-LOCK]` — A Finer-Grained Sub-Session

By default, the unlocked plugin’s shell test files are still frozen even inside the unlocked plugin. To edit a specific test-*.sh file, the agent issues [TEST-LOCK] <test_file>. The reason: it is too easy to silently rewrite a correctly-failing test to make a broken change look passing. Test edits demand explicit, named permission. ^ⓘ

Two-tier lock — PLUGIN-LOCK opens the cell; TEST-LOCK opens a specific shell test file inside the cell. The agent never gets a blanket "all shell tests editable while the plugin is unlocked" pass. Each shell test file the change touches earns its own ceremony. ^ⓘ

Safe-Lock Close-Out — Pass or Revert

Two scripts share the close-out duty. The agent invokes lock-cmd.sh when edits are done — the active path: the plugin’s full test suite runs at the lock boundary; on PASS the change commits and the lock clears; on FAIL the failures surface to stderr and the working tree is preserved (no revert) so the agent can fix and re-run. The defensive partner is safe-lock.sh, which fires automatically when the agent attempts a non-whitelisted operation while a plugin is unlocked — editing outside the plugin’s directory, transitioning phases, finalizing a job: on FAIL the working tree rolls back to the captured checkpoint_ref, the plugin’s hidden state records a structured revert entry, and a voice line writes to the operator’s terminal. The agent does not get to ship a plugin change that breaks the plugin’s own self-test. ^ⓘ

The cycle is symmetric to PLUGIN-LOCK: every lock opened gets closed by one of the two mechanisms above, with the test suite as the gate. There is no inline override; the deliberate [GMODE] route covered above (plus the user-approved-job route) are the only ways to admit an existing-plugin edit, and both leave an auditable trail. There is no "commit anyway"; there is no "I will fix it next session." Either the active-lock cycle leaves the agent looking at preserved failures it now has to fix, or the auto-revert cycle removes the broken edit from the working tree entirely. ^ⓘ

The safe-lock cycle's pass-or-revert branch — Image 7.8. Test pass-or-revert. Every plugin edit passes through the same gate.

The Historian Ratchet — Refuses the Lock

The lock can be refused before it opens. Each plugin keeps the 2000-word-capped docs/evolution.md narrative covered in Essay 7.5; drift-check.sh counts commits landed against the plugin since evolution.md was last touched. If drift exceeds threshold, lock-manager.sh rejects the [PLUGIN-LOCK] approval and tells the agent to dispatch the plugin’s historian subagent first. The historian re-narrates the cycles since last sync, commits the refreshed evolution.md, and the drift counter resets. Only then does the lock open. A plugin cannot be edited indefinitely without periodically forcing its own history to be re-told. ^ⓘ

A Closed Loop — The Only Way to Evolve a Plugin Is to Have Already Understood It

PLUGIN-LOCK gates the operator-approved entry. TEST-LOCK forces deliberate shell-test edits. Safe-lock makes hard-substrate close-out conditional on tests passing or reverts the working tree. The historian ratchet refuses unlock when the plugin’s narrative has fallen behind.

Each part, a risk closed: - An edit landing without operator approval (closed by PLUGIN-LOCK). - A correctly-failing test silently rewritten to mask a broken change (closed by TEST-LOCK). - A change committing despite a failing test (closed by safe-lock). - A plugin getting edited without anyone re-reading the cycles that produced its current shape (closed by the historian ratchet).

Plugin_integrity itself follows the same ceremony when its own hooks are edited — there is no privileged path. The plugin that enforces the ceremony submits to it. That is what makes the ceremony credible: it is not enforcement that lives outside the system; it is enforcement built into the same cell membrane every other plugin lives behind. ^ⓘ

A research lab’s seed could install the same ceremony around an experiment-protocol plugin — [PROTOCOL-LOCK] opens the edit session; [REVIEWER-LOCK] gates changes to the validator tests; the safe-lock cycle reverts if the IRB-checklist tests fail; the historian ratchet forces re-narration of the protocol’s evolution before another edit lands.

The ceremony is the safety rail. The next sub-essay puts it on the track — a walkthrough of what guiding your seed to create a brand-new plugin actually looks like in motion, with every lock fired in the order the plugin needs it.

Essay 7.8 — The Plugin Kit, Part 8 of 9.

Previous: Essay 7.7 — Smaller Organs and Brain-Root Wiring — config, tests, template, e2e, and the wiring file that lives outside every cell wall. Next: Essay 7.9 — Building a New Plugin — the tier-3 walkthrough; the lock ceremony exercised through a real birth.