agent

const AgentsFile = "AGENTS.md"

AgentsFile is the repo-root instruction file magus prints a managed block for but never writes, and the Status.Location CheckStatuses reports that block under - so a caller can tell the one location whose remedy magus cannot run.

const GuardSchemaVersion = 1

GuardSchemaVersion is the version of the verdict envelope every host glue parses, carried on the wire as schema_version. Bump it only when an existing field changes MEANING: adding an optional field that existing glues ignore is not a bump, and neither is adding a rule. A bump is expensive: a glue that meets a schema it does not recognize fails open, so every one of them must be re-downloaded before it guards again.

const GuardTemplateMarker = "magus-guard-template:"

GuardTemplateMarker introduces the version line each template carries, and is what a reader greps for in their own copy.

const GuardTemplateVersion = 10

GuardTemplateVersion is the revision of the hook templates a reader installs into their agent host.

The templates are the one shipped artifact with no self-correcting path. An installed skill is generated, stamped and regraded on every `magus doctor`; a hook template is COPIED into a host's config and then owned by its reader, so a fix magus makes to the source never reaches the copy, and nothing about the copy says how old it is. That is not hypothetical: a change to the guard's exit code turned every unfixed copy into one that judges a denied command twice, and on one host into one that fails open on every block. The docs were correct within the hour; every installed copy stayed wrong indefinitely.

A version rather than a content digest, because these files are explicitly the reader's to edit ("adjust to taste"). A digest would flag every legitimate customization and be switched off within a week; a marker survives editing and still answers the only question worth asking: is this copy older than the fix?

Bump it whenever a template's BEHAVIOR changes - not for a comment or a rewording. TestShippedTemplatesCarryTheCurrentVersion makes the bump total: every template must be re-stamped or the build fails.

2: docs/guides/integrations/agents/opencode-plugin.ts unconditionally passed the attribution flag, which no released binary accepts (v0.3.0 predates it) - an older binary rejected it, the plugin's judge() got unparsable stdout, and every verdict silently allowed. The sh templates already retried without attribution on exactly this failure (magus-guard-command.sh's guard()); the plugin now does the same.

3: that flag is now --agent-name (was --host, which read as a network host) and the templates' variable is GUARD_AGENT_NAME (was GUARD_HOST). A copy still passing the old spelling degrades rather than breaks - the retry that version 2 added drops attribution and keeps the verdict - so an unbumped copy loses the activity trail's host label, not its guard.

4: two changes, neither released before this. The path surface learned to render a deny arm - it handled only advise, so a deny rendered EMPTY while magus exited 2, and both scripts read empty-output-plus-nonzero as a broken guard and exit 0, which every host takes as allow. And the templates now resolve ./magus before PATH: an older PATH binary does not fail when it lacks a rule, it reads the config key that ARMS the rule as unknown and answers pass, so the guard enforces nothing at exit 0.

7: the advise arm is now suppressible. A host whose pre-tool-use hook REJECTS the context key - treating it as an error and then failing OPEN - was not merely ignoring an advisory, it was disarmed by one for that call. A copy that predates this keeps sending it and keeps failing open, which no verdict anywhere reveals. Suppression is opt-in per host (GUARD_NO_ADVISE), so the rendered response for a host that keeps the arm is byte-identical to version 6. Which hosts need it is recorded in their own guide pages, not here.

8: the templates find the binary by walking UP to the magusfile instead of testing `./magus` in the process's own directory. A hook runs in the host's SESSION directory, which is not always the workspace root, and every copy that predates this silently judges with PATH's binary there - or, where PATH's copy cannot load the workspace, does not judge at all. Version 4 established preferring the workspace's binary; this is the half of it that was only true from the root.

9: the notice a template prints when the binary is found but cannot judge now names the evidence - which binary path it resolved, that binary's version, and the error it actually printed - instead of guessing. The wording it replaces blamed "too old for session hook, or cannot load this workspace", and the second half is not a cause: the deny rules need no workspace, so a reader who took the sentence at its word went looking for a workspace problem that was never there. A copy that predates this keeps sending them, which is why this bumps even though enforcement is unchanged. 10: the two notices a template prints when the guard is not enforcing are held to one firing per session, keyed on a TMPDIR marker rather than on magus, which is the thing that is missing when they fire. Measured over recent sessions: 2,741 unavailable and 653 could-not-judge firings, 99% of them same-session repeats, and one session took 913. A copy that predates this keeps sending all of them, and a reader who has learned to skip the notice skips the one that mattered too.

const LocalSkillName = "magus-local-development"

LocalSkillName is reserved for a workspace's OWN rules, and magus must never ship a skill by that name.

Nothing in the installer or the verifier knows this constant, and that is the design rather than an omission: install writes only the names in skillSources, and grading skips any file magus did not write, so a name magus does not ship is untouchable by structure rather than by exception. The reservation exists so it stays that way - a future shipped skill called magus-local-development would, on the first --force after the upgrade, silently overwrite every early adopter's file. TestLocalSkillNameIsReserved is what makes the promise enforceable.

const SkillVersion = 51

SkillVersion changes when the installed skill contract changes. It is part of the generated provenance and lets verification explain stale installs.

37: a --simple install also writes each skill's always-full <name>-full twin (see fullTwinSuffix), and both entries carry a cross-reference in their description. The content digest cannot catch this on its own - it hashes the SOURCE bodies, which did not change, while what an install writes did. 38: magus-commit-composition - restructuring an unpushed branch into reviewable commits from project ownership, declared outputs and blast radius. 39: `magus graph verify` is gone; the installed copies are graded by `magus doctor`'s agent skills check, which every skill that named the old verb now points at. 40: magus-multi-agent learns two lease failure modes observed in the field: a worker's actual base can differ from the handed checkpoint (verify it, or materialize and re-record), and a lease whose environment cannot execute magus gets ROOT-DEFERRED validation up front. 41: the vocabulary drops "unit" for a row of the ledger, in the skill, the ledger table, and the tools it names. 42: the lease runtime reaches the skills - magus-multi-agent teaches ledger register, environment enrollment and the guard's deny/advise split, attention events for a blocked worker, and the session audit of what a lease ran; both it and magus-vcs-hygiene read `magus diff --impact` before landing. 43: the session CLI family (`magus session`, `session attention`, `session dispose`, `session hook`, `session notify`) replaces the sessions/attention/ notify/hook top-level verbs in the skill text; there are no compat aliases. 44: enrollment moves to the W3C channels - a worker exports BAGGAGE=magus.lease=<id>, plus TRACEPARENT and magus.spawner when its host has them. The magus-specific environment variable it replaces is gone. 45: the concept is a LEASE - the ledger row, the `--lease` flag, the BAGGAGE member magus.lease - and magus-delegate-multi-agent is renamed magus-multi-agent. Nothing answers to the old names. 46: verification instructions become proof obligations wherever the evidence is cheap - a gate you added is shown FAILING before its green counts (magus-run), drift is proven by a second regenerate rather than by reading the diff (magus-vcs-hygiene), fan-out waits on the collision check REPORTING the write sets disjoint and the root reopens a lease's evidence itself (magus-multi-agent), and every audit finding carries the command that reproduces it (magus-context-audit). 47: magus-multi-agent names `magus graph build` as the prerequisite for its central evidence command - in a fresh worktree `magus refs --occurrences` answers "unknown, not absent" rather than reporting the edit sites, and the partition is then built on a silence. 48: magus-query teaches the doc-section layer - every markdown heading is a `docsection` node, so prose is retrieved with `magus query kind=docsection` (a `path#anchor` pointer to one passage) instead of reading the whole file. Pairs with the guard's doc-search advisory on a cat/grep of a `.md`. 49: the query grammar teaches operators - kind=spell (match), kind!=op (exclude), id=~regex (regex) - with the `:`/`-kind:op` spelling kept as a compat alias. `=` reads as a match over a structured graph, and `!=` removes the flag collision the dash negation carried. 50: magus-handoff-journal gains the `elimination` record: a hypothesis an investigation killed, carrying the why plus an `excerpt` of the evidence that killed it. The excerpt is required because an output ref resolves only from the checkout that minted it, which leaves the ref beside it a best-effort handle. 51: magus-handoff-journal teaches what `put` writes: the fields the caller sends, keeping the rest, so refreshing a status does not drop the body. Clearing a field or changing a type is a delete and a create, and `allow_missing: false` (CLI `--amend`) says the entry is meant to exist.