ulyssesleolee/magos
Multi-Agent Git Orchestrator (MAGOS): nine explicit Git command skills (git-recon, git-analyze, git-recommend, git-integrate, git-cleanup, git-converge, git-sweep, git-plan, git-protect) that inspect, plan, integrate, clean up, converge, and protect branches and worktrees. Each skill reads the shared orchestrator rules in the package-root SKILL.md and references/.
Changelog
Every version of the magos package (the version in plugin.json, .claude-plugin/plugin.json, plugin.yaml, SKILL.md and the lane guard's GUARD_VERSION). A release is tagged v<version> on its release commit. The tag v1.0 marks the skill release 3.4.0 from before the package became a plugin and was renumbered; it is not a plugin version. Install, pin, upgrade and roll back as references/installation.md describes.
1.1.3
Tag v1.1.3. Claude Code no longer runs a batch file: its hooks start the guard through a POSIX shell launcher, so no Claude Code hook starts cmd.exe. Every verdict of the guard is that of 1.1.2.
Changed
- The POSIX launcher
hooks/run-guard. Claude Code runs its hooks under Git Bash on Windows, and Git Bash hands a file named*.cmdto cmd.exe, so every hooked tool call used to start cmd.exe on the batch-and-shell launcherhooks/run-guard.cmdin the plugin cache, which some security products block.hooks/hooks.jsonnow runssh "${CLAUDE_PLUGIN_ROOT}/hooks/run-guard" ..., a plain shell script, on every platform. On Windows it triespy -3first, as the cmd launcher does. - The entries
installprints. The Claude snippet, the Codexcommandand the Hermes entry outside Windows runsh '<guard home>/guard/hooks/run-guard'; the CodexcommandWindowsand the Hermes entry on Windows still runrun-guard.cmd.installcopies both launchers. doctorcompares both copied launchers (a missing copy is named as missing), and names a generated entry an earlier install wrote that still runsrun-guard.cmd, with the install command that writes the new one: a Codex or Hermes entry that runs it throughsh(it keeps working), and a Claude entry, which under Git Bash on Windows still starts cmd.exe.install --host hermesnames a Hermes plugin that holds another guard version on every platform, also one laid out before 1.1.3.- The POSIX launcher turns off a
nounsetorerrexitthat the host'sSHELLOPTSexports, and readsMAGOS_GUARD=offin any case, as the cmd launcher does.
Known limits
- Codex and Hermes on Windows still start cmd.exe on
run-guard.cmdfor each hooked call, so a security product that reacts to batch files may still react there. hooks/run-guard.cmdis unchanged, so the Codex and Hermes entries you merged before 1.1.3 keep working; they move torun-guardonly when you merge the new entry.- If you merged the Claude entry that
install --host claudeprinted into~/.claude/settings.json(instead of using the plugin), it keeps runningrun-guard.cmd, and on Windows cmd.exe, until you merge the new entry. - On Windows, Git Bash reads a hook's payload one byte at a time, so a payload of 1 MB costs about 1.5 s more than through cmd.exe; a tool call's payload is usually a few KB.
Upgrade
- Upgrade the plugin on each host and restart it: Claude Code
claude plugin marketplace update magos, thenclaude plugin update magos@magos; Codexcodex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos. - Copies under
~/.magos/guard(Codex and Hermes entries) are refreshed by runninginstall --host <host>again;doctornames a stale copy and a generated entry that still runsrun-guard.cmd;doctorreads the entriesinstallgenerated under~/.magos/guard/generated/, not~/.claude/settings.jsonor the Codex and Hermes configuration: afterinstallhas written the new entry, replace the old one there yourself. On Linux and macOS, merge the entryinstallprints into the Codex or Hermes configuration to move it torun-guard; on Windows, if you use theinstall --host claudeentry instead of the plugin, merge the new Claude entry into~/.claude/settings.json.
1.1.2
Tag v1.1.2. A feature release for the override of a denial: nobody has to copy or retype its 12-hex fingerprint any more when the repository has exactly one live denial. Branch protection and every verdict of the creation check are those of 1.1.1.
Added
- Codex:
magos_approvewithout a fingerprint. Foroverridethe tool'sfingerprintargument is optional. When the repository has exactly one live denial record, the tool takes its fingerprint, and the dialog says that the guard filled it in and shows the lane, the target and the conflicting branches the override lets through; the user ticks Approve and accepts as before. With none or several live denials the call fails with a text that says so and lists them, and no dialog opens. The Options text of a denial in Codex names the call with the repository and the reason only. override --reason ...without--fingerprintin a real terminal. The command takes the only live denial of the repository; with several it lists them (at most six, then the count of the rest), with none it says so (both exit 2).- A confirmation instead of a retyped fingerprint. While the denial record is live, the console shows what the override lets through (the lane, the target, the conflicting branches and the reason, quoted and cleaned of control characters) and the user types
y; the fingerprint is still accepted. A denial without a live record is confirmed as before, by retyping the fingerprint.
Changed
- Claude Code and Hermes refuse an
overridewithout--fingerprint(their approval binds the words of the command, so the denial has to be named in it); a repository atmagos.approvalterminalreports its level first. - Denial records are retired when their lane no longer waits for an answer: a new denial of a lane replaces the older one of the same manifest, an override removes the record it answered,
plan,set-plan,releaseandset-releaseremove the records of the lanes they register, change or release, and an allowed creation removes those of the lane's registered manifest (a deniedplan --amendkeeps its own). A damaged record (a time that is no finite number, JSON nested too deeply to read, a file that vanishes while it is listed) no longer breaks the reading, and an override or approval record nested too deeply counts as unreadable instead of ending the command with an internal error. - The text printed after an override tells the agent to run
planfor the lane again and then create it.
Known limits
- The click is the route of 1.0.8: the user ticks Approve and accepts in Codex's dialog. Under Codex's approval policy
neverCodex declines the form itself and the terminal remains; Codex's hooks cannot ask the user, so a denial cannot open a dialog by itself. - A denial that names no conflicting branch, and a denial of
check, leave no record: their fingerprint has to be given.
Upgrade
- Upgrade the plugin on each host and restart it: Claude Code
claude plugin marketplace update magos, thenclaude plugin update magos@magos; Codexcodex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos. - Copies under
~/.magos/guard(Codex and Hermes entries) are refreshed by runninginstall --host <host>again;doctornames a stale copy.
1.1.1
Tag v1.1.1. A maintenance release of 1.1.0: the guard, the commands and every verdict are those of 1.1.0.
Fixed
- Tests on Linux with Python 3.9.
ubuntu-latestnames Ubuntu 26.04, which has no Python 3.9 build, so the Linux 3.9 leg of the test workflow could not start. The test workflow runs its Linux legs onubuntu-24.04, and the minimum Python (3.9) is tested on Linux again as well as on Windows.
Upgrade
- Upgrade the plugin on each host and restart it: Claude Code
claude plugin marketplace update magos, thenclaude plugin update magos@magos; Codexcodex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos. - Copies under
~/.magos/guard(Codex and Hermes entries) are refreshed by runninginstall --host <host>again;doctornames a stale copy.
1.1.0
Tag v1.1.0. A feature release: the ninth command, /GitProtect, lets the user protect a branch so that agents can no longer commit to it, merge into it or rewrite it through the hooked tools of Claude Code, Codex and Hermes. The release also fixes how the hook reads Codex commands on Windows, cmd's cd words and PowerShell's colon parameters, and how the Hermes plugin finds the directory a terminal call runs in.
Added
/GitProtect <branch> [--release] [--status]. It runs the new guard subcommandsprotect(user-only: approved by your click in the host's prompt or run in your own terminal, at every approval level,--releaseincluded) andprotect-show(read-only). The protection lives in<git-common-dir>/magos/protected.json, belongs to the repository and holds in every worktree; up to 64 branches per repository; a branch can be protected before it exists. Codex approves it throughmagos_approve(subcommandprotect,branch,release), Hermes through the plugin's question.- The hook rule. In a repository that holds a protection, the hook refuses (code
BRANCH_PROTECTED, no override) every agent write to a protected branch in the ordinary spellings of git and the shell:commit(also--amend),merge,pull,cherry-pick,revert,rebase,am,reset,update-ref,symbolic-ref, the forced, deleting and renaming forms ofbranch,checkout -B/switch -C, a worktree that checks it out, the creation of its name, a fetch into it (a refspec on the line or a configuredremote.<name>.fetch), a push orsend-packinto it through a local repository,reflog --updateref, and any write whose target the hook cannot read. It reads the line in order:git switch -c feat && git commit -am xon a protectedmainwritesfeatand is allowed;git switch main; git commitis refused, and the denial says how to split or join the calls. Reads, checking a protected branch out, creating other branches and writing them stay allowed. - The record is guarded. A write of an existing protection record or its store (also through globs, brace expansions,
.segments, Windows trailing dots, acdanywhere before it,find ... -delete, a read piped into a writer, a git read with--output) and a write of the refs of a protected repository are refused;magos.guard offdoes not silence a protection: onlyMAGOS_GUARD=offin the host process and/GitProtect <branch> --releasedo.doctorlists the protections; a record that cannot be read protects every branch until you inspect it.
Fixed
- Codex on Windows. A string command is read in the PowerShell dialect, as Codex runs it, so
git -C C:\...\repo commitandSet-Location C:\...\repo; ...name that repository for the creation check and the protection. - cmd.
cd/d <dir>,cd..,cd\andcd;<dir>change the directory, and;no longer ends a command in cmd text. - PowerShell.
Set-Location -Path:<dir>,-LiteralPath:<dir>and their prefixes and aliases change the directory. - Hermes plugin. A terminal call without
workdiris judged in the directory the session's terminal is in (the directory an earliercdleft, elseTERMINAL_CWD), not in the Hermes process directory. - Repository discovery. The hook finds a repository as git does (real paths through junctions and symbolic links, a
.gitdirectory git would skip, bare and nested git directories) without a Git call in a repository that holds no protection.
Known limits
- A protection is an accident guard, not a boundary against an agent that sets out to evade it: settings, environment variables and options that make git run a program (an editor, a pager, an ssh command, a hook, a filter,
--upload-pack, ...), URL rewriting (url.<base>.insteadOf), git's control files edited between calls, interpreters and the file tools the hook does not see are not judged. Pushes to a remote host andgh pr mergeare guarded by the hosting service's own branch protection; your own terminal and Git itself are not affected; Gemini CLI has no tool hook, so no protection is enforced there. - A
\"inside double quotes in PowerShell and cmd text and PowerShell's<# ... #>block comments are read as before (references/lane-split.mdsection 12).
Upgrade
- Upgrade the plugin on each host and restart it: Claude Code
claude plugin marketplace update magos, thenclaude plugin update magos@magos; Codexcodex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos. - Copies under
~/.magos/guard(Codex and Hermes entries) are refreshed by runninginstall --host <host>again;doctornames a stale copy.
1.0.9
Tag v1.0.9. A security and fix release after a full review of 1.0.8: the tamper filter now reads every part of a command before it decides, and the approval routes of Codex and Hermes read their directories and commands exactly. In 1.0.8 the hook was the only barrier between an agent's own shell and the approval server it could start, so each gap the review found let a plain shell command approve a user-only guard command (override, arm, disarm, install) without a human.
Fixed
- The most severe finding wins, wherever it stands. A harmless-looking edit of the guard's state in a quoted word, a child shell or an earlier target of the same command no longer hides a later
mcp,hookor user-only subcommand, or a write into an approval store; the hook also reads the command a second time with the guard home and the store whenever the first reading found nothing that is always denied. - Here-documents. A
<<inside quotes or after#no longer starts a here-document, so the lines afterecho "<<E"are read as commands; a body is read as commands when a shell named by a path or in quotes (/bin/bash <<E,"bash" <<E,cat <<E | /bin/sh) or on the line after the body reads it. - The subcommand slot. A brace expansion or a glob before the subcommand (
--json{,} mcp,-* mcp) is denied like a variable. - The guard word. The guard is recognised also as
ma$''gos_guard.py, with trailing dots (magos_guard.py.) and by its Windows 8.3 short names (MAGOS_~1.PY,RUN-GU~1.CMD); every Python build (python3.14t,python3.12-dbg,pypy3) counts as an interpreter. - Git alias values. The value of
git -c alias.<name>=<value>is read like the text of a child shell, sogit -c "alias.c=!git config magos.guard off" cis denied in every repository and!rm .git/magos/ARMEDwhere the guard is armed. - Deeply nested text. A command whose text nested deeper than three levels (child shells, here-documents, quoted guard commands, alias values) names MAGOS is denied on every host with a text of its own instead of passing unread.
- Long commands. The subcommand slots of a command are read in one pass, so a command of many guard-like words is read in linear time (8,000 such words took about 30 s in 1.0.8, past the hook's 25 s limit).
- Codex denial. The
magos_approvearguments a denial names are offered only for exactly one plain invocation of this guard; after acd, an environment assignment such asMAGOS_HOME=.., or with another guard file the denial names the form of the tool instead of arguments for another repository or home. - Directories of the approval routes. On Linux and macOS a backslash in a repository, Hermes home or script path stays part of the name; Hermes refuses a
workdirthat is no existing absolute directory (a drive-less/xon Windows) and a~interpreter or script word where the call names no directory, before the user is asked. - Hermes plugin under
plugins.isolation: host. Guard commands that namemagos_guard(plan,version,git add scripts/magos_guard.py) are no longer blocked as unprepared. doctorreads a Hermes flow list with a]in its comment (enabled: [magos] # see [docs]) correctly.- Documents.
SKILL.mdandreferences/lane-split.mdname the click of every host.
Known limits
- The Codex approval server still cannot tell Codex from an agent's own pipe. The hook's text filter is the barrier, and it reads the spellings named above; a copy of the guard under another name, or the guard run through an interpreter's own code, is not read (as in 1.0.8).
- A Hermes terminal call without
workdiris judged in the directory of the Hermes process, not in the directory an earliercdof the session left (as in 1.0.7 and 1.0.8).
Upgrade
- Upgrade the plugin on each host and restart it: Claude Code
claude plugin marketplace update magos, thenclaude plugin update magos@magos; Codexcodex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos. - Copies under
~/.magos/guard(Codex and Hermes entries) are refreshed by runninginstall --host <host>again;doctornames a stale copy. Armed repositories keep working;doctorsays whenarmshould run again.
1.0.8
Tag v1.0.8. A feature release: the click that 1.0.7 gave Claude Code now exists in Codex and in Hermes, each through the approval prompt of that host, so a user-only guard command (override, arm, disarm, install) no longer has to be typed in a terminal there either.
Added
- One click in Codex. The guard has a hidden subcommand
mcp: a local MCP server (standard input and output, no network) with one tool,magos_approve. After a denial the agent calls the tool; Codex shows the user a form with one required checkbox, Approve. Only the answer accept with the box ticked runs the command; an unticked box, decline, cancel, no answer within 120 seconds or a client that cannot ask runs nothing. Under Codex's approval policynever(anddanger-full-access) Codex declines the form by itself, then the terminal remains. There is no click-free path in this route:auto-safeasks here. The plugin brings the server in the new rootmcp.json(Codex starts it throughgit);install --host codexprints the same server as aconfig.tomlentry for installs without the plugin. - One click in Hermes. The plugin entry registers two
pre_tool_callcallbacks that run the guard: the verdict (the command rebuilt with a one-time token) and the approval (Hermes's own human-approval prompt, with a request key of its own so that "always" can never pre-approve a later request). The plugin sends the click route only when Hermes will really ask a person: with/yolo,--yolo,-z,-q,approvals.mode off, an unattended run or an older Hermes without the approval directive, the terminal remains. The record livesmin(max(approvals.timeout, 120), 900) + 30seconds, 330 by default. doctorandinstallknow both routes.doctorreports the Codex server file, the Hermes plugin route, ahooks:entry that Hermes has not approved (Hermes skips it without a word) and the double route (ahooks:entry next to the plugin denies before Hermes asks);install --host codex|hermesprints the entries and what to do next.- A route field in records and audit. Approved runs through the Codex server carry
routemcpand the client name; Hermes runs carryroutehermes.
Changed
- The subcommand of a guard run must be a plain word. A shell command that runs the guard with a variable, a substitution, an
xargsorfind -execfeed,hook, an empty slot or an unknown word in the subcommand position is denied on every host (a plain command such aspy -3 magos_guard.py plan --branch x --paths a bis unaffected). The user-only subcommands andmcpkeep their own handling: a tool command may never startmcp. - The Hermes plugin turns the guard on. After
hermes plugins update magosand a restart, every Hermesterminalcall goes through the guard, as the Claude Code plugin does for Bash. Turn it off withMAGOS_GUARD=off,git config --local magos.guard offorhermes plugins disable magos. - The ready terminal command printed with a denial is quoted for Windows PowerShell 5.1; a value it cannot carry (a double quote, or a blank before a trailing backslash) is replaced by a placeholder for the user's own words.
- Texts and documents. The denial (
options),need_tty, the token errors, the install footer anddoctorname the click in each host and the terminal fallback;SKILL.md,references/lane-split.md,references/installation.md,references/pressure-tests.mdand the three READMEs describe the three routes, what the plugin runs and writes, and the limits.
Fixed
- A single-use approval token can no longer be used twice at one instant on Windows. The command renamed the token's record to mark it used, but two processes that rename the same record at the same moment both succeed on NTFS (measured: 300 of 300 rounds), so one token could run two commands. This was true of 1.0.7 too and was found by the CI of 1.0.8. The command now claims the token with an exclusively created file first; the second use answers 27 (used) and runs nothing, and a record that stays busy fails closed. The token never reaches the agent, so the exposure was a second process holding the same token, not an agent forging one.
- A POSIX
--homepath keeps its backslashes. The guard turned every backslash of the guard home into a slash on every platform, so a home such as/t/home \bwas written to/t/home /b; only Windows now does that.
Known limits
- The Codex server cannot authenticate its client: an agent that starts its own copy of the server by a route the text detector cannot read (a renamed copy,
python -c) and plays the MCP client can answer its own form. It is the same class as forging state files, which 1.0.6 and 1.0.7 already state; the barrier remains the hook that denies every plain shell command reaching the server. - Nobody has clicked the real Codex app or the real Hermes prompt yet: the routes were checked with each host's own test protocol (the Codex 0.163 app-server and Hermes' ACP interface) and with a fake model, not with a person. The first real click is the user's.
- The Codex hook (the lane guard itself) still comes from
install --host codex: merge the printed entry into your Codex hook file and review it once in/hooks; the plugin brings the approval server, not the hook. - In Hermes a session
/yoloand-zcannot be seen by a shell hook; the plugin sees them through Hermes internals that are not documented. If those names change, the plugin falls back to the terminal. - An open Codex form does not count against the 300 second tool limit of a plugin server, but the server withdraws it after 120 seconds.
- Hermes shows the approval card with the guard's message only; once the user allows, Hermes sends the rewritten command, token included, to every connected viewer. The token is single use and bound to that command.
Upgrade
- Upgrade the plugin on each host and restart it: Codex
codex plugin marketplace upgrade magos, thencodex plugin add magos@magos; Hermeshermes plugins update magos; Claude Codeclaude plugin marketplace update magos, thenclaude plugin update magos@magos. After the Hermes update the guard is on for every terminal call. - Codex: merge the hook entry that
py -3 scripts/magos_guard.py install --host codexprints into your Codex hook file and review it once in/hooks(the plugin does not carry the hook). Hermes: remove any MAGOShooks:entry from the Hermes config (the plugin replaces it;doctorreports the double route). - Nothing needs configuring:
promptis the default level;git config --local magos.approval terminalkeeps the terminal route.
1.0.7
Tag v1.0.7. A feature release: a user-only guard command (override, arm, disarm, install) is approved with one click in Claude Code instead of a command typed in a terminal, at three levels of the new setting magos.approval.
Added
- One-click approval in Claude Code. After a denial the agent asks you first; on your yes it runs the guard command, and Claude Code shows its own permission dialog that says what is approved (the subcommand, the repository, branch, host or fingerprint, and the reason the agent wrote, quoted and marked as the agent's) and that your click is the approval. The level is the local git config
magos.approval, written only by you:terminal(you run the command in a real terminal, as before),prompt(the default) andauto-safe(a plainarmand aninstallinto the default guard home run without a click;override,disarmand every other form still ask). Any other value counts asterminal, anddoctorreports it. - A single-use approval token. For one direct invocation of this guard by the Bash or PowerShell tool with a user-only subcommand, the hook hands Claude Code the command rebuilt from its words with
--approval=<token>. The token is single use, valid for 120 seconds and bound to the exact arguments and the repository or guard home; the command accepts it instead of a real console and its challenge. A token that is unknown (exit 25), expired (26), used (27) or for another command (28) is an error and never falls back to a prompt. A command in which the agent wrote--approvalis denied.installis approved only when the running guard itself is the script. - Audit of the route. Every approved run records
via(terminal,promptorauto-safe); an override approved by a click records its reason as written by the agent (reason_by). The hook keeps the branches and the lane of a conflict denial in<git-common-dir>/magos/denials/<fp>.jsonso that the override dialog can name them.
Changed
- The documents state the levels.
SKILL.md,references/lane-split.md,references/installation.md,references/pressure-tests.md,PR_DESCRIPTION.mdand the three READMEs say that a user-only command needs your approval, as a click in Claude Code or in your own terminal, that Codex and Hermes always use the terminal, and that an agent never setsmagos.approval. The READMEs disclose the approval and denial records. - The agent asks first. After a denial the agent quotes the fingerprint and asks you, with the host's question tool where it has one, before it runs anything.
- The texts of the guard name the click. The denial (
options),protected,need_ttyanddoctortexts describe the levels; the writes of the hook now include approval and denial records, and writes into an approval store are denied.
Known limits
- No level lets an agent run
overrideordisarmunattended: an agent that approved its own bypass would be no guard. The opt-out isgit config --local magos.guard off, which only you set. - The token is convenience, not access control: the barrier is Claude Code's own dialog. File tools are not hooked, so a deliberately malicious agent can still forge state files, the approval store or the audit log, as in 1.0.6;
viaandreason_byare provenance, not proof. - Codex and Hermes keep the terminal route whatever
magos.approvalsays; the approval route exists in Claude Code only, for the Bash and PowerShell tools. - The route relies on Claude Code holding a hook's
askuntil you click and applying the rewritten command. On Claude Code 2.1.310, headless runs showed anaskheld in each of the five permission modes, apermissions.allowrule not overriding it, and the rewritten command being applied and run once, for Bash and PowerShell; the click in the real dialog is not covered by those runs. - The reason in the dialog is text the agent wrote, shown quoted and shortened: read it before you click.
- A guard older than 1.0.7 given
--approvalstops with a usage error.
Upgrade
- Upgrade the plugin on each host (
references/installation.md) and restart every running Claude Code session:claude plugin marketplace update magos, thenclaude plugin update magos@magos. - Nothing needs configuring:
promptis the default. To keep typing every user-only command in a terminal, rungit config --local magos.approval terminalin each repository. To refresh a guard copy, rundoctorfrom the new version and theinstall --host <host>commands it prints.
1.0.6
Tag v1.0.6. A patch release: the / menu of Claude Code lists the eight commands under one naming, the READMEs say what the plugin runs, sends and fetches, and the texts that name the commands of each host are corrected. The behaviour of the lane guard is unchanged; its GUARD_VERSION follows the package.
Added
- What it runs, sends and fetches. A section at the top of
README.md,README.en.mdandREADME.ja.mdlists what the hooks run, what the guard reads and writes (inside<git-common-dir>/magos/, plus the two steps you run yourself,installandarm), that it sends and fetches nothing, which commands touch the network only when you ask, and how to turn the guard off. The security scan of Anthropic's plugin directory reads the README for exactly this.
Changed
- One naming in the Claude Code menu.
skills/git-orchestratorsetsuser-invocable: false: the/menu lists the eight/magos:GitXxxcommands and nothing else, and Claude still loads the orchestrator on its own when you describe a problem (the model is offered it as before). Codex and Hermes ignore the key. Checked on Claude Code 2.1.309 by loading the plugin files and reading the commands and skills it lists. - The texts name the commands each host offers. The three READMEs, the eight adapters of
skills/and the design of__init__.pyno longer say that Claude Code lists/magos:git-<name>: there the commands are/magos:GitXxx, the adapters are/magos:git-<name>in Hermes and$magos:git-<name>in Codex, and the explicit invocation of a write adapter in Claude Code is its command. - The disclosure is exact. The model is kept from starting the five write commands in Claude Code and Codex; Hermes has no such switch, so the adapters tell the agent to run only on your explicit invocation. The guard runs no program other than the local Git commands the README lists.
- The package contract requires
user-invocable: falseand nodisable-model-invocationon the entry skill and drops the unusedWRITE_ADAPTERS; the README test reads a#inside quotes as part of the command; the test design (TC-104) states the rule and names the tests. - The notes of 1.0.5 credit the plugin directory, not Claude Code, with reading the icon, and name the hosts that may honour the two keys.
Known limits
- Claude Code does not document how
user-invocable: falseanddisable-model-invocation: truecombine: the one set of commands and the model's view of the entry skill were checked on 2.1.309 only. - A host other than Claude Code that reads the same frontmatter keys hides the adapters there too.
- A second set can still come from files outside the package: command copies in
~/.claude/commands/(delete them) and a clone below~/.claude/skills/.
Upgrade
- Upgrade the plugin on each host (
references/installation.md, "升级"):claude plugin marketplace update magos, thenclaude plugin update magos@magos, and restart every running Claude Code session. A Hermes install pinned with--refmoves its pin withhermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.6> --force --enable. - The guard changes only in its version number. To refresh the guard copy under
~/.magos/guard, rundoctorfrom the new version and theinstall --host <host>commands it prints.
1.0.5
Tag v1.0.5. A patch release: Claude Code shows one set of commands, /magos:GitRecon and its siblings from commands/; the adapters of skills/ (/magos:git-recon and so on, made for Codex and Hermes) are hidden there. The behaviour of the lane guard is unchanged; its GUARD_VERSION follows the package.
Added
- Listing icon.
.claude-plugin/icon.png, a 1024 x 1024 PNG (under 2 MB, as the plugin directory requires), is the image of the plugin; the plugin directory finds it by its place, so the manifest keeps only metadata keys.claude plugin validate --strictpasses without a warning.
Changed
- One set of commands in Claude Code. The eight command adapters of
skills/(git-recon,git-analyze,git-recommend,git-integrate,git-cleanup,git-converge,git-sweep,git-plan) setuser-invocable: falseanddisable-model-invocation: true. Claude Code lists only the eight commands ofcommands/(/magos:GitRecon.../magos:GitPlan) and the entry skillgit-orchestratorin its/menu, and offers the model only the three read-only commands and the entry skill (checked on Claude Code 2.1.309 by loading the plugin files and reading the commands and skills it lists). Codex reads only the fields it knows and Hermes reads the frontmatter as a mapping, so both ignore the two keys:$git-reconand/git-reconwork as before. - The package contract requires both keys on the eight adapters and neither on the entry skill and the root
SKILL.md; the strict frontmatter reader accepts exactly one boolean per key (truefordisable-model-invocation,falseforuser-invocable). - Installation notes.
references/installation.mdstates the one set and names the usual sources of a second one: command copies in~/.claude/commands/(the placescripts/sync_hosts.py --host claudewrites) and a clone below~/.claude/skills/(its rootSKILL.mdis also a personal skill).
Known limits
- A second set can still come from files outside the package: command copies in
~/.claude/commands/(delete them) and a clone below~/.claude/skills/. - The two host keys were checked on Claude Code and on the frontmatter reader of Hermes; Codex, which reads only the fields it knows (as it already does for
disable-model-invocation), was not available for a check. - A host other than Claude Code that reads the same two frontmatter keys hides the adapters there too, and stops offering the three read-only adapters to its model.
Upgrade
- Upgrade the plugin on each host (
references/installation.md, "升级"):claude plugin marketplace update magos, thenclaude plugin update magos@magos, and restart every running Claude Code session. A Hermes install pinned with--refmoves its pin withhermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.5> --force --enable. - Delete command copies in
~/.claude/commands/(Git*.md): the plugin provides the commands. - The guard changes only in its version number. To refresh the guard copy under
~/.magos/guard, rundoctorfrom the new version and theinstall --host <host>commands it prints.
1.0.4
Tag v1.0.4. A feature release: the new command /GitPlan, which plans, before any sub-agent starts, how one task is divided into lanes that own different files and are merged back as one whole, lists the requirements, the lanes and their outcomes in tables, and later converges the lanes and supplements that list with what each lane changed, backed by four new subcommands of the lane guard (scripts/magos_guard.py). Every install should upgrade, and the guard copies under ~/.magos/guard that the Codex and Hermes hooks run must be refreshed: a guard of 1.0.3 has no set subcommand, and /GitPlan stops at its version check.
Added
/GitPlan. The eighth command (/GitPlanin Claude Code,/git-planin Hermes,$git-planin Codex), with the adapterscommands/GitPlan.mdandskills/git-plan/(SKILL.md,agents/openai.yaml) and the contractreferences/commands.mdsection 8. Forms:/GitPlan <set> --into <branch>(preview),--into <branch> --apply [--create],<set> --status,<set> --amend --expect-revision <n> [--apply [--create]],<set> --converge [--include-active],<set> --converge --apply [--include-active] [--land] [--expect-revision <n>]and<set> --release. The set name is[a-z0-9][a-z0-9-]{0,23}, and--intois a local branch that is notmain. A preview investigates Git (branches, worktrees, open claims, the target tip, remote freshness as the local records show it) and the code (layout, entry points, the repository's build, test and lint commands, shared files, hot spots, imports across boundaries), writes the requirements of the task, divides it into at most 12 lanes with exclusive file ownership that are named after the topic of their change, proves the division withmagos_guard.py set-plan --dry-runand ends with a readiness verdict (READYorBLOCKED), the next command and the remedy of every failed gate; it fetches nothing, registers nothing, and its only write is a scratch spec file outside every worktree.--applyregisters exactly the spec of the latest preview of the same set and target, byte for byte, and makes a new preview and stops when there is none, when the user asked for a change since, when itsbasediffers from the live target tip, or, for an amendment, when it was built from another record revision than the current one;--createalso creates the registered lane branches and worktrees from the recordedbase, and without it the report prints thegit worktree addlines.- Requirements, lanes and outcomes in tables. The plan states the requirements of the task (1 to 12, each an id such as
R1and one sentence), and every lane serves 1 to 12 of them and states the outcome it delivers (serves,outcome). Every report that shows the plan prints two tables, rendered from the data the guard proved (a preview) or stores (afterwards) and never from memory: the Requirements table (Req,Requirement,Lane(s),Planned outcome, one row per requirement) and the Lanes table (Lane,Branch,Worktree,Owns,Needs,Acceptance, one row per lane;--statusand--convergeaddStateandHead), then the merge line, the owner lane of every shared file (lockfiles, generated files, registries, migration numbers, version files, changelogs) and at most five risks. The stored sheet holds them in at most 8192 characters.--statusand--convergeprint the tables again from the record, with[x]for the lanes that arereadyorintegratedand their recorded heads, followed by Remaining TODO: the lanes still to finish, the merges, the repository checks, the post-merge tasks, the land and the release. The tables are both the plan the user reviews and the TODO reference for the merge. A requirement that no lane serves, a lane that serves none, and a requirement id that is unknown, repeated or missing inservesare refused with exit 24 (UNSERVED,UNKNOWN_REQUIREMENT,DUPLICATE,RANGE,MISSING), naming the field. - Names show the topic of the change. A lane id is a topic slug (
[a-z0-9][a-z0-9-]{0,23}, one to three words such asclaim-store,sweep-readiness,launcher-exit-codes), the lane branch is exactlyagent/<set>/<id>and the name of the lane worktree directory ends with-<set>-<id>(by default<parent of the main worktree>/<repository directory name>-<set>-<id>), sogit branchandgit worktree listread as a list of topics. The guard refuses an ordinal or generic id (only digits, one letter,l1,lane-2,task3,worker-1and the like, and the reservedintegration:GENERIC_ID,RESERVED,FORMAT,DUPLICATE) and a branch or worktree name of another form (BRANCH_FORM,WORKTREE_FORM,WORKTREE) with exit 24, and the message names the compliant name. The integration branch staysagent/<set>/integration; the set name and the requirement ids are not subject to the ordinal rule. - The changes summary and the supplemented list. When a lane is recorded
integrated, the guard computes from git a summary of what the lane changed, against the local target branch of that moment, and stores it in the lane record aschanges(commits,subjects(at most 8, oldest first),more,files,insertions,deletions,paths(at most 12) andpaths_more); it is null before, a repeatedintegratedupdate keeps it, andset-show --jsoncarries it per lane. After the merge the original list is supplemented, not replaced: the converge apply report,--statusand--releaseprint the same two tables with every row and column kept, aChangescolumn on the Lanes table (<commits> commits, <files> files, +<insertions>/-<deletions>), aResultcolumn on the Requirements table (the first commit subject of each integrated lane that serves the requirement, andpending: <lane>for the others), the Changes summary (one line per lane with its commit subjects and paths) and aTotalline, followed by Remaining TODO. - Optimistic lock. Nobody holds a lock while the lanes work. The record carries a
revisionthat every change compares and increments and the target tip the plan was made against (base), and a lane records the head it was markedreadyat. A stale plan is detected and refused, never overwritten:--amendand, optionally,--converge --applytake--expect-revision <n>, a target that moved so that the files changed by its commits outside the set's own work (what the integration branch and the recorded lane heads hold) intersect a lane manifest makes the findingSTALE_PLAN, and an amendment movesbaseto the live target tip. - Convergence.
--convergepreviews, and--converge --applymerges, theREADYlanes in dependency order into one integration branchagent/<set>/integration(created with a plaingit switch -cfrom the current target tip in the invoking worktree): each recorded head is merged withgit merge --no-ffand recordedintegratedwithset-update, and the repository's checks run on the result. A conflict runsgit merge --abortand stops the run, never resolved with ours, theirs or by hand; the completed merges stay on the integration branch only, and the report names the lane, the files, the error text and the integration start SHA.--include-activetakes anactivelane that holds changes of its own against the current target asreadyat its current tip, which the preview shows as its Head; in an apply that is the user's acceptance of that tip, and a tip that moved since the preview stops the apply with a new preview.--landadds onegit merge --ff-onlyof the integration branch into<branch>, only while<branch>still sits where the integration branch was cut from (otherwiseLAND_REFUSED).--releaseprints the final checklist, then removes the claims and the record; no branch, worktree or integration branch is touched. The command never pushes, never deletes a branch or a worktree, never touchesmain, never usesoverride, and merges nothing but a recorded lane head into the integration branch. - Lane findings and remedies. The preview of a convergence evaluates every lane:
INTEGRATED,READY, the pendingBLOCKED,NOT_READYandWAITING(the lane sits this run out), the failingMISSING_BRANCH,DIRTY,IN_PROGRESS,NO_MERGE_BASE,OUT_OF_LANE,SHARED_CHANGE,MOVED,CLAIM_DRIFTandSTALE_PLAN(the whole command stops, so a ready lane that is inconsistent is never merged around) and the hintPREDICTED_CONFLICT. The readiness isREADY,PARTIALorBLOCKED. Every failed gate, failing finding, guard exit code and stop of an apply is followed by the action that lifts it (references/commands.mdsection 8, Remedies), which the command never performs. - Guard subcommands.
set-plan --set <name> --target <branch> --spec <file>|- [--dry-run] [--amend --expect-revision <n>]validates the spec (1 to 12 requirements each served by a lane, at most 12 lanes with topic-slug ids that each serve existing requirements and state an outcome, 200 manifest entries per lane, branches exactlyagent/<set>/<id>and distinct worktree paths whose directory names end with-<set>-<id>, pairwise disjoint manifests by exact glob intersection,depends_onids that form a DAG, every shared file inside its owner's manifest,baseequal to the live target tip, each lane judged against the other claimants) and then writes every lane claim, the claim of the integration branch and the record in one atomic operation, or nothing;set-show --set <name> [--drift]reads the record and the view of every lane (the requirements with the lanes that serve them, branch, tip, commits ahead ofbase, worktree state, the storedchanges, files outside the manifest, files changed by two lanes, target moved, merge order);set-update --set <name> --expect-revision <n> --lane <id> --state active|ready|integrated|blocked [--head <sha>] [--note <text>] [--integration <branch>]records the progress of a lane (readyneeds--headequal to the branch tip and every changed file inside the manifest,integratedneeds the recorded head to be in the target or the integration branch and stores thechangessummary of the lane);set-release --set <name> [--reason <r>] [--abandon]removes the claims and the record once every lane is integrated. None of them is user-only: they run through the host hook likeplan,releaseandlist, options are never abbreviated, and with--jsonevery outcome is one object withdecision,code,messageandexit_code. - The set record.
<git-common-dir>/magos/sets/<set>.json, written only by the guard (the tamper filter denies agent writes under the store): therevision, the target, thebase, the title, the requirements, the sheet, the notes, the shared files, the integration branch once the first lane is integrated, and per lane its branch, worktree, manifest, dependencies, the requirements it serves, its outcome, acceptance, state, head, the commit its lastreadywas measured against (ready_target), note andchanges. A record of a greater format version is never misread or overwritten: every set command that names it refuses with exit 23. - The integration claim.
set-planregisters a claim foragent/<set>/integration(the single marker entry.magos/integration/<set>/, the extra keysset=<name>androle=integration), which is why a plaingit switch -c agent/<set>/integration <target tip>is allowed in a guarded repository. The claim holds no files and is exempt from overlap judgement in both directions: it restricts no lane's manifest and is never a claimant, and the creation of that branch is judged for its name and the existence of the claim only. - Exit codes 19 to 24.
19STALE(thekindof a denial isbaseorrevision, withexpectedandcurrent),20SET_EXISTS,21SET_UNKNOWN,22OUT_OF_LANE,23SET_NEWER_FORMATand24INVALID_SPEC(a spec or option value that is invalid in itself; the message names the field). The codes10,11,13,14,15and16keep their meaning,12also reports a branch name or worktree path that clashes with the repository, and a failure that the repository or the record causes keeps its existing code. listanddoctor.listshows thesetand thelane(orrole) of a claim. Whensets/holds a file or a claim carriesset=,doctorprintssets: <n>, unreadable: <n>, newer-format: <n>and a line for each problem: a lane claim that is missing or differs from the record, anactiveorreadylane whose branch vanished, a set whose target branch is gone, claims of a set without a record (an interrupted registration), and an unreadable or newer-format record. A repository without sets prints what 1.0.3 printed, the version aside.- Documentation. The three READMEs describe
/GitPlan, the eight commands, the command names per host and the install steps;references/pressure-tests.mdhas the GitPlan pressure tests (v1.0.4), among them ordinal lane ids, a requirement that nobody serves, a branch or worktree that does not carry the topic and the supplemented list after the merge; the source-contract casesgit-plan/forms-and-help,git-plan/exclusive-lanes-and-optimistic-lock,git-plan/converge-and-hard-stopsandgit-plan/package-wiringpin the command.
Changed
- Plain
planandreleaserefuse the claims of an open set. While the record of a set exists, a plainplanthat would write the claim of a branch of the set (a lane branch or the integration branch, also when that claim is missing or lacks itsset=line: an amend, other entries, the re-plan after an override) is refused with exit 14 (lane_in_set) andreleaseof any claim of the set with exit 16 (blocked_set): a set is changed only through/GitPlan, with--amend(which writes a missing or set-less claim of the set again) and--release; of a record the guard cannot read or that a newer MAGOS wrote only the integration branchagent/<set>/integrationis known, so a lane counts only through theset=line of its claim. plankeeps the registered worktree path. Aplanwithout--worktree(an amend, the re-plan after an override) keeps the worktree path the claim registers, which the host hooks enforce at the creation, and its success message prints the creation command with that path (<path>when the claim registers none).- Open lane claims of a set block cleanup. The claim of a lane of a set is an open claim, active-owner evidence like any other, so
/GitCleanup,/GitConvergeand/GitSweepreport its branch asBLOCKED_ACTIVE_OWNERwhile the set is open;--releaselifts it. - Paths from the top of the work tree. Every git call of the guard carries
-c diff.relative=false, so adiff.relative=trueconfiguration does not cut the files of a branch down to the directory the call starts in: the hook in a session whose directory lies below the top of the work tree, andplan,checkand the set subcommands with a--repobelow the top, read every committed path from the top of the work tree and judge it against the manifests. - Submodule pointers are evidence. Every
diff,logandstatuscall of the guard carries--ignore-submodules=none, so neitherdiff.ignoreSubmodules, norsubmodule.<name>.ignore, nor theignoreof.gitmoduleshides a changed submodule pointer (a gitlink) or a submodule checkout that differs from it:plan,checkand the hook count such a path as committed or uncommitted evidence and judge it against the manifests, plainreleaserefuses a branch whose worktree holds such a change, the pinned-c diff.ignoreSubmodules=nonecarries the same into thestatusGit runs inside each submodule checkout, and the set subcommands count it among the files of a lane, the drift of the target, the changes summary and the test of a clean worktree. - Guard version.
GUARD_VERSIONis 1.0.4, and/GitPlanchecksmagos_guard.py versionfirst and stops below 1.0.4. - Eight commands. Every text that enumerates the commands says eight:
SKILL.md,references/commands.md(all eight commands accept--helpand--lang), the plugin manifests,COMMAND_NAMESofscripts/sync_hosts.py,INDEX_DESCRIPTIONSof__init__.py,references/installation.mdand the three READMEs. Five adapters write to a repository and setdisable-model-invocation: truein Claude Code (git-integrate,git-cleanup,git-converge,git-sweepandgit-plan); the Codex adapters all disable implicit invocation, andgit-planrefuses to write on Hermes unless it is invoked explicitly.
Known limits
- Sets live in one clone. The set record and the claims of its lanes are in the git directory of the clone that registered them. Fetch and push do not share them, so another clone of the same repository does not see the plan or its claims.
- Topic names are checked for form, not for meaning. The guard checks that a lane id is a topic slug and refuses the ordinal and generic ids, but it neither counts the words nor judges whether the name fits the change: naming the topic after the requirement and the owned paths is the duty of the executor.
- Semantic coupling is not detected. The guard proves that the file lists of the lanes are disjoint, not that the code of two lanes is independent. Files that import each other belong in one lane, which the partition rules of
/GitPlanask for and the guard cannot check. - A guard of 1.0.3 cannot see the set record. It has no
set-*subcommand (a usage error), does not show sets inlistordoctor, reads the claims of a set as ordinary claims, judges the marker entry of the integration claim as the declared manifest of a lane and cannot refusereleaseorplan --amendof a claim of a set, or its re-plan after an override, so a set whose claims an older guard changed (an emptied worktree and a stored override fingerprint included) showsmismatchormissinginset-showand indoctor. Refresh the guard copy (Upgrade). - The limits of the lane guard (the classes of command text the hooks do not read, listed under 1.0.3 and in
references/lane-split.mdsection 12) are unchanged.
Upgrade
- Upgrade the plugin on each host (
references/installation.md, "升级"). Restart every running Claude Code session: a session started before the update keeps running the previous guard. A Hermes install pinned with--refmoves its pin withhermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.4> --force --enable;hermes plugins updateand a reinstall without--refkeep the old commit. - Refresh the guard copy: run
doctorfrom the new version (with--home <dir>for a copy installed withinstall --home <dir>) and, in your own terminal, theinstall --host <host>commands it prints. Compare each printed snippet with the entry in your host configuration and replace the entry when they differ. - Nothing else changes for scripts.
Compatibility: claim files of 1.0.0 to 1.0.3 are read unchanged. A claim of a set carries the extra keys set= and lane= (the integration claim set= and role=integration), which older guards ignore.
1.0.3
Tag v1.0.3. A hardening release of the lane guard (scripts/magos_guard.py, hooks/run-guard.cmd) and an improvement of /GitSweep. Every install of an earlier version should upgrade, including the guard copies under ~/.magos/guard that the Codex and Hermes hooks run.
Security
git update-ref --stdinrecords. The instructions are read only from the sources of that invocation that the hook can see, as the words the shell hands over (quotes removed): a here-string, the here-documents of the line, and a directly pipedecho,printf,Write-Output,Write-Hostor acatof here-documents. The record is dynamic, and denied as unparseable where creations are guarded, unless everycreateandupdateis a plainly read name:\0,\n,\tand\rseparate the fields as printf writes them, and any other escape (\x62), a quote or an expansion in a name, aprintfformat, an empty name, a name git refuses and an unreadable source (a file, another command, a substitution, no input) make it dynamic. A command that only mentionsupdate-ref --stdinis not read. A plain record creates its branch only with a manifest.- Escaped program words in a shell the hook cannot name. In a tool whose shell is unknown (the Hermes
terminaltool,shell, MCP command tools), a program word written with a backslash, a backtick or a caret (g\it,g`it,g^it, also afterenv) is read as the program it spells without the escape; the creations and possible changes of that line are dynamic and denied as unparseable. - Abbreviated
git rebase --exec.--exand--exe, with the value attached by=or separate, are read like--exec, and the commands they run are judged.--eis ambiguous for git and runs nothing. git --shallow-file. The global option takes a separate value, so the subcommand after it is read:git --shallow-file <value> branch <name>creates<name>and is judged.- Alias check. The check for aliases reads the subcommand of every
gitword of a line after the values of the global options (-C <dir>,-c <key=value>,--git-dir=<dir>, a path-qualifiedgit), in one pass, so a line of any length is read within the time budget. refs/headsin any case.refsandheadsunder it in any letter case (ASCII letters) are read as a branch on every platform (it is one on the case-insensitive file systems of Windows and macOS:refs/HEADS/x,REFS/heads/x). One pattern is shared by the host hook, which reads it ingit update-ref, ingit pushandgit fetchrefspecs, inupdate-ref --stdinrecords and ingit symbolic-ref, and by thereference-transactionhook of an armed repository, which vetoes a creation under such a spelling without a claim.git update-refoptions. Options are read as git reads them:-m <message>and-mMESSAGEtake a value,--stdand--sare--stdin, and the bundled and separate forms of-d,-zand-mare read, so a creation written with them is judged. Deleting a ref and a--no-derefupdate ofHEADcreate nothing.Start-Processworking directory.Start-Process gitruns git in its-WorkingDirectory(also-Wo,-woand the colon form-WorkingDirectory:<dir>), and a creation in its-ArgumentList(-a, colon forms) is judged in the repository of that directory; without-WorkingDirectoryit is judged where the shell is.- PowerShell option spellings. Every spelling of
-Command,-CommandWithArgsand-EncodedCommandthatpowershellandpwshaccept (-e,-ec,-EncodedC,-Co,-Comm,-cwa) is read in the command walk, in the tamper filter and in a Codex argv, where the words after a PowerShell or cmd command option are joined into the text that runs.-ex Bypassis the execution policy option, andbash -ecis bash. - PowerShell backtick. In PowerShell text the backtick is the escape character with its special sequences:
g`itisgit,git sw`itchisgit switch, andgi`tisgifollowed by a tab, which runs no git. - Word gate. The gate that decides whether a line is read sees the line and its inner texts without escapes and quotes (
g''it,"g"it), and a word that runs a script or a shell (.,source,bash <script>,sh <script>, also in a command substitution or a here-document fed to a shell) opens it, so the creation that a small script file makes is read and judged. A line with neither is not read. - Missing directories. Records and inner-text states that differ only in the prior directory, or the followed chain, of a
cdto a missing directory stay apart, so each creation is judged in the directory the shell is in at that point. A line whose later creation runs in another engaged repository is denied as unparseable. - Launcher. In both halves the launcher passes on to the next interpreter when
pyexits 103 or 112 (pywithout a Python runtime), and the verdict of the guard that runs comes through with exit 0. Any other exit ofpyis a guard failure (exit code <n>, exit 2 with--strict) and starts no further interpreter. - Claims under a refused name. A claim file stored under a name that the Windows alias rule refuses (for example a name ending in
.claim, as 1.0.1 stored it) allows the creation of its branch.plan --amendfor that name is refused with exit 12 and names the rule,listshows the claim with the rule (refused_namein--json), anddoctornames it. A name without a claim is denied. - Redirections. The redirections of the shell are words of their own and are skipped, with their target, before the program word (also after prefix assignments and wrappers), between a program and its subcommand and among the words of a git invocation, so
>/dev/null git switch -c x,git -C . >/dev/null switch -c x,git branch -m old new >/dev/null,git update-ref >/dev/null refs/heads/x HEADandbash -c >/dev/null '..'are judged like their plain forms;2>&1,>&2,&>fand>|fare one word. The word gate, the alias check and the tamper filter skip them too. A quoted or escaped word ('>x') is no redirection. git branchbundled short options. The letters of a short-option word are read as git reads them, up to the first letter that takes a value:-df,-dr,-rdand-vddelete or list and create nothing, and-mr,-m -r,-m -aand-c -rrename or copy, so the new name is judged (git branch -m -r a bcreatesb).git symbolic-refand dynamic ref words.git symbolic-refreads-m <reason>(also-qm) and--, sogit symbolic-ref -m why HEAD refs/heads/zcreatesz. A first positional word ofgit update-refthat is dynamic ($ref), and a dynamic name or target ofgit symbolic-ref, is a dynamic creation when it may name a branch (also behindxargs); only a literalrefs/namespace other thanheadsnames none.- Refspec destinations. The destination of a fetch, pull or push refspec is read on its raw text:
refs/heads/refs/xcreates the branchrefs/x, another destination that begins withrefs/creates no branch, and a push refspec with an empty source (:refs/heads/x) deletes and creates nothing. - Names git accepts. Whitespace and letters outside ASCII (U+00A0, U+2003, U+3000) belong to a branch name, and a leading dash is a name for
update-ref,symbolic-ref,fetch,pullandpush, whose operand is a full ref (refs/heads/-x); only a name that git certainly refuses is dropped. - Time bounds. A chain of relative
-Cvalues and the nesting of groups and brace blocks (98,000 deep, in bash and in PowerShell) are walked in time linear in the length of the command, so a line of 200,000 characters is read within the time budget.
Added
/GitSweep --push. With--apply, after the local converge and before the remote deletions, one fast-forward push publishes<branch>:git push --recurse-submodules=no --no-follow-tags <remote> refs/heads/<branch>:refs/heads/<branch>, never forced and never--no-verify, so remote branches merged only into the local<branch>are deleted in the same run. The push is skipped (PUSH_SKIPPED, with the failed condition) when the live remote<branch>is not an ancestor of the local one, when<branch>ismainor the remote default, when the converge phase stopped or its validation failed, or when the remote sweep isUNKNOWN. When the live remote tip equals the local tip nothing is pushed and the report saysPUBLISH_NOT_NEEDED; otherwise the push runs even when no remote branch depends on it. A failing push is reported asPUSH_FAILEDand never retried; a push after which the remote tip differs from the local tip isPUSH_UNCONFIRMEDand counts as failed. A push never reaches a repository other than<remote>and never recurses into submodules: both push commands carry--recurse-submodules=no. The preview predicts the push from the local refs, with or without--push, and does not contact the network; it counts the commits that norefs/remotes/<remote>/*ref holds yet (git rev-list <converged tips> --not --remotes=<remote>), and phase 1 adds at most one merge commit per merged source. The report gives the remote tip before and after and the exact range and commit count; undoing a publish takes a force push, which the command never makes.- Readiness block. The preview of
/GitSweepends with a verdict (ONE_SHOT,PARTIALorBLOCKED), a recommended command (/GitSweep <branch> --applywith--remoteand--langas given, carrying exactly the flags that lift something:--discard-ignoredwith the ignored files it deletes listed,--push, whether or not it was typed, when a remote branch isPUSH_THEN_DELETE, and a typed--pushwhose publish prediction says the push will run, with the commits it publishes) and the remaining items with their evidence and remedies. The verdict judges the recommended command, not the command as typed: a preview computes everything that depends on--discard-ignoredas if the recommended command had been typed, so the remote classification shows the state that command reaches, and an apply uses the flags it was given. The end state is onlymainand<branch>as local branches, the worktrees of the deleted branches removed, and every remote branch deleted orNOT_TOUCHED; a worktree the command never touches (a detached one, or one that holdsmainor another kept branch) is listed in the report. Apart from a typed--pushthat will run, a flag that lifts nothing is never recommended, and a flag that discards files or publishes commits is never added silently; a typed--pushwhose publish will not run is dropped from the line, and the report says why. - Remedies. Every failed gate, delete blocker,
UNKNOWNstatus andPREDICTED_CONFLICTin a/GitConvergeor/GitSweepreport is followed by the action that lifts it (references/commands.mdsection 6, Remedies; section 7 adds the remedies for remote findings, among them the one for a--remotethatgit remotedoes not list, and separate remedies forPUSH_THEN_DELETEwithout--pushand forPENDING_PUSH). The command never performs these actions. A target that matches an existing branch only in letter case is answered with the exact existing name, never with a branch that differs only by case; a repository whose trunk has another name thanmainis told to createmaindeliberately or not to use the command. - Run state. The
/GitSweepapply report ends withCOMPLETEorPARTIAL. APARTIALreport lists the remaining items with their remedies and ends with two lines, in this order. A remedy changes the repository, and an apply whose plan is older than the repository stops with a new preview, soNext preview:is the same line without--apply, to run once the remedies are done so that the preview becomes the earlier plan, andNext command:is the line to run after that preview (when that preview recommends another line, run the recommended one). Both lines carry their flags in the order--apply,--discard-ignored,--push,--remote,--lang, with--remoteand--langas given. TheNext command:line carries--pushwhen some remote branch endedPUSH_THEN_DELETEorPENDING_PUSHfor a reason that a rerun with--pushcan clear, or when--pushwas typed and the publish prediction says the push would still run; it never carries--pushwhen the only reason is that<branch>is the remote default; with phase 2UNKNOWNit carries--pushonly when it was typed. Both lines are left out when no rerun would change anything. - Documentation.
README.ja.md, a Japanese edition that follows the Chinese README section for section; all three READMEs share one language switcher and describe the 1.0.3 commands, the command names per host and the install steps.
Changed
- Remote classification against the converged target. A remote branch is classified against the converged target (the local
<branch>after the converge phase; in a preview, its tip together with the tips of the sources that will be merged), so a preview and the apply after it agree.PUSH_THEN_DELETEmarks a branch whose deletion depends on the publish step, which is predicted to run (in a preview with or without--push; an apply without--pushleaves it and reports "kept:--pushnot typed");PENDING_PUSHmarks a branch that no push of this run clears: the publish is not predicted to run (for example<branch>is the remote default), or the push was skipped, failed or unconfirmed. The remedy of the first is to rerun with--pushor, once local<branch>holds its tip, to push<branch>by hand; the remedy of the second is to clear the condition the report names. - All gates at once.
/GitConvergeand/GitSweepevaluate every gate and report every failed one together with its remedy./GitSweepadds the gate--remote <name>not listed bygit remote, with its remedy, and a failed gate makes its verdictBLOCKED. TheDefaultline of the/GitConvergehelp says that every failed gate and blocker is followed by the action that lifts it. - Hard stops. The
/GitSweephard stop on pushing commits and tags reads: except the one fast-forward push of<branch>that--pushmakes. The lease-guarded deletion of one named remote branch at a time is the other push./GitConvergepushes nothing. - Option hints. The one-line hints of
git-sweep(the Hermes description and the Codex short description) list[--apply] [--push] [--help]; the full usage lists every option,--remoteincluded. - Argument safety and names. Every git command of
/GitConvergeand/GitSweepruns as an argument list, never as a shell string or a PowerShell expandable string, and each ref name, remote name, path and SHA is one argument; a command printed in a report quotes each of them in POSIX single quotes. The name of a source branch, or of a remote branch that is notNOT_TOUCHED, that holds a character outside ASCII letters, ASCII digits and._/+-, or starts with-or+, is never passed to a command: a local source with such a name isUNKNOWN(neither merged nor deleted; the remedy is to rename it), and a remote branch with such a name isBLOCKED_BAD_NAME, which keeps the readiness verdict atPARTIAL. The typed<branch>, the remote default andmainare covered by the argument rule alone. - One URL. The remote sweep and the publish step are
UNKNOWNunlessgit remote get-url --all <remote>andgit remote get-url --all --push <remote>each print exactly one URL and the two are identical, because a push goes to every URL; the remedy isgit remote set-url --delete <remote> <extra-url>for each extra URL, andgit config --unset-all remote.<remote>.pushurlfor a separate push URL. - Live remote
HEAD. Phase 2 isUNKNOWNunless theref:line ofgit ls-remote --symrefforHEADnames exactly the remote default; a liveHEADthat is detached, unborn or missing makes the whole sweepUNKNOWN, and the remedy is to set the default branch on the remote or its host (git remote set-head <remote> --autocannot fix it). - Worktrees with submodules.
BLOCKED_SUBMODULEis decided the way git decides: the git directory of the worktree contains amodulesdirectory, or a submodule path of the worktree is populated; deinitializing does not lift it. The command cannot remove such a worktree; after confirming that it holds nothing unique, remove it yourself withgit worktree remove --force <path>, or keep it. The branch stays as long as the worktree does. - Ignored-file overlap. The preview runs the ignored-file overlap test of the apply for every source to merge and marks a hit
PREDICTED_IGNORED_OVERLAP, with the source, the changed path and the ignored entry; it counts againstONE_SHOT, and the remedy is to move or delete the ignored entries that the report names. - Long-lived roles. A remote branch has a long-lived role only with recorded or observed evidence: a policy file, CI trigger filters, matching release tags, or at least two merge commits between the branch and a survivor, counted in both directions on the
--first-parentchains of the two recorded SHAs. One merge is a lane merge, merges inherited from before the branch was cut do not count, and a role inferred from the name alone does not count. - Plan and report. An apply records the converge plan first and, after the converge phase and before the first remote write, every remote candidate with its SHA, classified against the actual
<branch>tip. The preview and the inline help say that each remote deletion closes the open pull requests that use the branch as their head, and on some hosts closes or retargets those that use it as their base; the preview cannot see them. The local deletion never includesmain. update-ref --stdinfrom a file or another command. Anupdate-ref --stdinwhose input is a file, another command or text with an expansion is denied as a dynamic creation even when it only deletes, because the hook cannot read it; it reads the instructions only from a here-document, a here-string or a pipedecho,printf,Write-OutputorWrite-Host.- Long directory spellings. A directory spelling longer than 4,096 characters is an unknown directory: a creation in the same invocation as a chain of
-Cvalues orcdtargets that long is judged against an unknown directory and denied as unparseable where creations are guarded.
Known limits
The lane guard is a best-effort detector of the text of one command line, and the git-layer backstop (arm) is the enforcement that does not depend on parsing: in a repository the user has armed it vetoes a branch created without a claim whatever tool ran the git binary, within the backstop limits of references/lane-split.md section 12. The hooks do not read the classes below; for each, keep the repositories where lanes live armed, run the commands that matter through a script you have reviewed, and stay on the lane discipline of the skill (plan before creating, never work around a denial) unless the class names another remedy. Section 12 gives every class with its examples.
- Aliases from places the hook does not read.
--config-env,GIT_CONFIG_COUNT,GIT_CONFIG_PARAMETERS,GIT_CONFIG_GLOBAL,-c include.path, an alias defined on the same line, the aliases of another repository or of a session outside any repository,-c alias.*in another case or shadowing a built-in, chains over three aliases and git spelledgit.exe,Gitor as a variable are not read; keep the repository the line reaches armed. - Command text from configuration or environment.
core.fsmonitor,core.editor,sequence.editor,diff.external,GIT_EDITOR,GIT_SEQUENCE_EDITOR,GIT_EXTERNAL_DIFFand arebase --execorbisect runtext with a dynamic program are not inspected; keep the repository armed. - Wrappers and program spellings outside the walker's lists.
ionice,flock,taskset,coprocand similar wrappers, a path-qualifiedenv,nohup,xargsorsudo, ANSI-C quoting ($'g\x69t'), a backslash-newline inside the program word, an empty expansion or a substitution as the program, a program held in a variable or computed, and shells such asfishandtcshhide the program; run what matters through a reviewed script and keep the repository armed. - Escapes in git words in a tool whose shell is not known. In a tool whose shell is unknown, a backslash inside a git option word (
-\C,--git\-dir=), a sub-subcommand (worktree a\dd) or the ref ofupdate-refis compared as written; keep the repository armed. - Text fed to a shell, and scripts. A creation inside a process substitution, quoted text that names no git fed to a shell (
printf '. ../mk\n' | sh), a script run directly without a.sh,.bashor.ps1name (./mk) and a script another command feeds (cat ../mk | bash) are not read; read the script first and keep the repository armed. - A directory an earlier command of the line creates. A
cdinto a directory thatmkdircreates earlier on the line is followed only in a&&chain (mkdir L/nd; cd L/nd; git switch -c x); create the directory in a call of its own or chain with&&, and keep the repository armed. - Pushes and fetches without a readable destination.
fetch --refmapand-c remote.<name>.fetch, a push into another local repository without a colon refspec (git push ../R newb,--all,--mirror,HEAD) and a push whose repository a bundled option value displaces (-fo x) are not read; arm the receiving repository too. - The symbolic-ref alias two-step. A symbolic ref outside
refs/heads/that points into it, then written throughgit update-ref, creates the branch unseen; keep the repository armed. - Nested substitution. A substituted text with another group inside it (
$(git switch -c x $(git rev-parse HEAD)),(git switch -c x (git rev-parse HEAD))) is not read; keep the repository armed. - PowerShell tokenising. A
\"or doubled backtick before a quote in a double-quoted string, a trailing backslash that joins the next line, a here-string with an apostrophe and a block comment<# .. #>are tokenised approximately, so the creation after them can go unjudged and a command-shaped line inside them is denied; keep the repository armed. - PowerShell code from strings. PowerShell code built from a string and run through a script block (
[scriptblock]::Create) and a program called by a dot (. git switch -c x) are not read; keep the repository armed. - The switches of
cmdand itsstart.cmdswitches other than a lone/cor/k(/r,/d/c,/cgit) andcmd /c startare not read; keep the repository armed. Start-Processof shells and splatting. A shell thatStart-Processstarts, a call through splatting and an-ArgumentListcut at commas and read with shell quoting are not read as written; keep the repository armed.- Options of child shells.
pwsh -WorkingDirectory, apowershell -Filescript behind four option values andenv -Swith bundled options (-vS) or the\_separator are not read; keep the repository armed. - The tamper filter. The tamper filter does not follow
Start-Processlists,cmd /r,env -S,iexandScriptBlock::Create, so the git layer itself can be removed; rundoctorto see that it is still installed and re-runarmwhen it is not. - MCP tools without a string
command. MCP command tools whose command is a list or sits under another key (cmd,script,argv,commandLine,input) are allowed without parsing; keep the repository armed. - Over-denials by text or name. A prompt that mentions
isolation: worktree, quoted git text beside a here-string, an MCP tool namedget_branch, the help forms ofgh pr checkout,git config magos.<key>as a read and git options that print and exit are denied although they create nothing; run them in your own terminal. - Unreadable
update-ref --stdin. Anupdate-ref --stdinfed from a file, another command or text with an expansion is denied as dynamic even when it only deletes; the hook reads it only when a here-document, a here-string or a pipedechoorprintffeeds it. - Launcher input cost. The sh half of the launcher costs quadratic time for a payload of tens of thousands of raw lines; no agent can cause it, and a host that pretty-prints its payload should send one line.
Upgrade
- Upgrade the plugin on each host (
references/installation.md, "升级"). Restart every running Claude Code session: a session started before the update keeps running the previous guard. A Hermes install pinned with--refmoves its pin withhermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.3> --force --enable;hermes plugins updateand a reinstall without--refkeep the old commit. - Refresh the guard copy: run
doctorfrom the new version (with--home <dir>for a copy installed withinstall --home <dir>) and, in your own terminal, theinstall --host <host>commands it prints. Compare each printed snippet with the entry in your host configuration and replace the entry when they differ. - In armed repositories, run
doctorand re-runarm: the git-layer hook readsrefsandheadsin any case, sodoctorreports the installed hook as different from this version untilarmruns again. - Nothing else changes for scripts.
Compatibility: claim files of 1.0.0 to 1.0.2 are read unchanged. /GitSweep without --push pushes nothing but the lease-guarded remote deletions.
1.0.2
Tag v1.0.2. A security release of the lane guard (scripts/magos_guard.py, hooks/run-guard.cmd, hooks/hooks.json). Every 1.0.0 and 1.0.1 install should upgrade, including the guard copies under ~/.magos/guard that the Codex and Hermes hooks run.
Security
- Repository redirects. A creation redirected into another repository with
git --git-dir,GIT_DIRorGIT_COMMON_DIR(prefix,env,export, PowerShell$env:, cmdset) was allowed without a manifest: the hook judged the session's repository, or none when the session was outside any repository, so a claim there or a session repository with no other lane let an unplanned lane be created in the other repository. Each creation is judged in the repository it acts on, with that repository's mode, engagement and claims; underGIT_COMMON_DIR, which makes Git use two repositories at once, it is judged in both; a redirect the hook cannot resolve is denied in every mode, and so is a creation after aGIT_DIRorGIT_COMMON_DIRchange the hook does not follow (read,printf -v,+=,builtin export,Set-Content Env:).--work-treeandGIT_WORK_TREEalone leave the judged repository unchanged. - Directory changes the shell may not make. A
cd,pushd,Set-LocationorGIT_DIRchange that the shell might never make before the creation moved the hook's judgement into another repository: one after&&or||followed by;(false && cd other; git branch x), insideif,caseor a loop, in a function body or a PowerShell script block, in a background job (&), in a subshell( ), a command substitution$( ), a pipeline,eval,source, a PowerShell( ), or written asenv cd(which changes nothing). The creation is judged in every directory the shell may be in, and the stricter verdict applies; in bash a subshell's change is known not to reach the commands after it.cd dir && git switch -c xandcd dir; git switch -c xare still judged indironly. - Directories handed to wrappers.
env -C <dir>(--chdir) andsudo -D <dir>(--chdir) run git in<dir>, but the hook judged the directory the shell was in. They are judged likegit -C <dir>. A session directory written with~(~/repo,~user/repo) is expanded, and a relative tool directory is joined to the payload's directory. cdto a missing directory.cdorSet-Locationto a directory that does not exist, followed by;or a newline, let the following branch or worktree creation through, although the shell runs it in the prior directory. Forcd,pushd,chdir,Set-Locationandsl, the creation is judged in that prior directory and denied as unparseable when it is guarded, on every platform; the same holds for acdthe shell refuses (cd /d dirin bash,cd dir extra), while cmd'scd /d diris followed intodir.- Shells and wrappers that hid a creation. Text piped into a shell was read only when the shell stood right after the pipe, so
| FOO=1 sh,| env bash,| sudo -E sh,| command shand| doas shlet a creation through;doas git branch x, PowerShell$out = git switch -c x,(git switch -c x)and@(git switch -c x),env -S 'git switch -c x', and the commandsgit rebase --execandgit bisect runrun were not recognised. All of these are read as the creation they run. - Escaped words. In text a POSIX shell runs, a backslash escape hid a creation or a user-only command (
git swi\tch -c feat\ure,g\it,bash -\c), and a cmd caret (feat^ure) did the same in cmd text. Words are read the way the shell that runs them reads them; in a shell the hook cannot name, a backslash in a git subcommand or branch name makes the creation dynamic. A bash backslash-newline joins the words around it (main\<newline>2ismain2), and a#comment ends at the line's end, so a quote in a comment (# Let's ...) hides none of the following commands. - Git command spellings. A branch name attached to its option (
git switch -cNAME,git checkout -qbNAME,git worktree add -bNAME <dir>,--orphan=NAME), a global option whose value hid the subcommand (--attr-source <v>,--config-env,--namespace,--exec-path), a rename or copy written with bundled or abbreviated options (git branch -mf,-qm,--mo,--cop), the creating options ofgit switchandgit checkoutabbreviated to two letters (--cr,--or), a branch name aftergit branch --sort <key>or--format <format>, a push or fetch whose option value stood before the repository (git push --exec <v> . HEAD:refs/heads/x,-o <v>), a refspec that creates branches by a glob (refs/heads/x-*), agit pushinto a local repository (git push . HEAD:refs/heads/x,git push ../other HEAD:x), and an alias on a line that also held a recognised command created a branch without a manifest. Each is recognised; a push into a local repository is judged in that repository. - Unhooked shell tools in Claude Code. The
Monitortool and MCP tools that run commands (run_in_terminal,terminal,shell,exec_command,execute_command,start_process, and names holdingcommand,exec,execute,process,bash,powershellorcmd) were not inspected. They are hooked, the Claude matcher is generated from the guard's tool list, and thecommandstring of every hooked tool and every MCP tool is read as a command line in addition to the judgement the tool's name calls for.tool_input.cwdis read as the session directory. - Payloads the hook could not decode. A payload whose decoding raised (deep nesting gives
RecursionErrororMemoryError) was allowed. It is denied when its bytes hold a lane word (git,worktree,isolation,EnterWorktree,magosand the like), and an internal error on a call recognised as a lane creation or a protected command denies that call. - Programs in the working directory (Windows). The launcher and the guard could run a
py,pythonorgitplaced in the hook's working directory. Both setNoDefaultCurrentDirectoryInExePath=1before starting any program, and the launcher's cmd half finds its interpreter on PATH only. - User-only commands.
override,arm,disarmandinstallpassed the host hook when a global option was written as--repo=.,--lang=enor abbreviated (--rep .), when--stood before the subcommand, when they were run through the launcherrun-guard.cmd, and when a wrapper started them in a new console (start,cmd /c start,Start-Process). They are recognised in all of these forms, options are never abbreviated, the launcher runs only thehooksubcommand (exit 2 for any other), andinstallneeds a real console likearm(exit 17). - AUTO engagement. When the check for other lanes failed (for example on the time budget), an auto-named worktree (agent isolation,
gh pr checkout) was allowed, and more than 120 unmerged local branches made AUTO allow branch-only and auto-named creations without a warning. A snapshot that hides lanes counts as another lane; when the check fails, an auto-named creation is denied if an open claim, another local branch or a second worktree exists, a branch-only creation is judged when the repository holds a claim, and every undecided call writes a warning on stderr. - Overrides. The host hook honoured an override record without consuming it. Only
planreads override records; after the user's override, a re-plan registers it in the claim, and the hook honours only the claim. - Claim store.
releasewith another spelling of the branch (./x, a different case) skipped the refusal for unmerged work and could delete a file outside the claim store; branch names that alias on Windows (foo./barandfoo/bar, names ending in.claim) overwrote another lane's claim; a newline in--worktreeoruser.nameadded lines to a claim file; two planners could register clashing names at once; and on Linuxreleasewith a spelling that holds..,., an empty segment or a backslash (zz/../FEAT) found no claim.releasereads the branch as a ref spelling (a backslash as/, empty and.segments dropped,..resolved), resolves the stored claim and deletes only its file inside the store; aliasing names are refused (exit 12); control characters are refused or replaced and claim keys are whitelisted; the name check runs again under the claim lock. - Tamper filter. Writes aimed at the claim store, the guard home or the Hermes plugin directory by their absolute path are denied in armed or claimed repositories, as
.git/...spellings are;unlink,truncate,shred,ln,rmdir,rd,mklink,find -delete,Rename-Item,Move-Item, cmd'smoveandcopy, PowerShell'scpi,sc,ac,niandclcand their aliases count as writers, also inside the text of a child shell (cmd /c,bash -c,pwsh -Command); a word escaped with a backslash, a backtick or a caret matches like its plain spelling. A copy is tested on every destination spelling (-Destination:<path>, operands before an option value such as-ErrorAction Stop); copying from the guard home is allowed. - Launcher on Windows. An interpreter that is a
.bator.cmdshim did not return to the launcher, so its exit code was lost; a guard home whose path held&,(,),^,%,;,,or=broke the generated entries or ran text from the path as a command; a guard home with an apostrophe broke the Codex entry. The launcher runs its interpreter throughcall,installrefuses such a guard home on Windows (exit 2) and quotes the launcher path for each shell, and the launcher passes the guard's stderr to the host. - Chained git hooks.
armkeeps a repository's ownreference-transactionhook asreference-transaction.magos-prevand runs it from the backstop. On POSIX a previous hook without the executable bit, which git itself never runs, failed with exit 126 in thepreparedphase and so aborted every ref update in the armed repository. The backstop runs the previous hook only when it is executable, as git does. - Write adapters in Claude Code.
git-integrate,git-cleanup,git-convergeandgit-sweepsetdisable-model-invocation: true: only the user's slash command runs them.
Added
version [--json]: the running guard's version, the sha256 of its file, its path and the Python version. Read-only; agents may run it.installis version-aware and atomic: it printsguard copy <old> -> <new>orguard copy unchanged (<version>), writes both files to temporary files and replaces both or neither (the launcher stays executable on POSIX), rewritesguard/VERSION.json(version, sha256, source, time) and appends to<guard home>/audit.logon every run that is not a dry run, and refuses to replace a newer copy with exit 18 (DOWNGRADE_REFUSED) unless--allow-downgradeis given.doctor [--home DIR]prints the running guard's version, compares the guard copy (under--home,MAGOS_HOMEor~/.magos; from the copy itself, against the source itsVERSION.jsonnames) with it and prints the exactinstall --host <host>refresh command (also outside a repository), prints the copy's provenance fromVERSION.json, checks the launcher of the generated Hermes entry, reports a Git older than 2.36, runs its self-test on a Git budget of its own and counts only the backstop's veto line as a pass, and reports a recorded backstop command whose script no longer exists or is older than the running guard, with thearmcommand to re-run.armrecords, as the guard command of the backstop's deny message, the copy under~/.magos(orMAGOS_HOME) when that copy runs the same version, so a plugin upgrade does not leave the message pointing at a removed version; it records the previousgc.packRefsandmaintenance.pack-refs.enabledvalues inarm-config.json, anddisarmrestores them.armanddisarmappend to the repository's audit log.- Claim format gate: every claim carries
v=(any integer spelling,v=01included, reads as that integer); a claim written by a newer MAGOS is never misread (creations are denied withCLAIM_NEWER_FORMATand a message that says to upgrade the guard,releaserefuses it,plannever overwrites it), andlistshows unreadable and newer-format claim files. - The Hermes entry that
install --host hermeswrites runs the Hermes plugin's own launcher, which follows the Hermes plugin's updates, when the plugin's guard is the installing guard's version and (on Windows) its path holds none of the characters above; otherwise it runs the guard copy, andinstallsays why. The entry is valid YAML on every platform. - With
--json, a Git failure or an internal error prints a deny object on stdout; a Git call that fails without a message names its exit code. scripts/sync_hosts.pyrecognises a MAGOS plugin installed from a Claude Code marketplace and leaves the Claude command copies out of a default run, as it does for a clone in~/.claude/skills.- A CI workflow runs the guard suite, the package contract suite and both source-contract runners (
--check) on Windows and Linux with Python 3.9 and 3.14, runs the coverage commands of.quality/qguard.jsonon Windows with Python 3.14 and fails when a source file or the project has 90 percent line coverage or less, and checks that a release tag names the package version. CodeQL analyses the Python sources and the workflows. - A security workflow (
.github/workflows/security.yml) runs on pushes and pull requests tomain,develop_claudeanddevelop_codex, onv*tags, and weekly. On Windows and Linux with Python 3.14 it replays the confirmed findings of the 1.0.2 audit against the hook entry (tests/codex/guard/data/security_regressions.jsonl, 33 cases, each with the verdict and, for a deny, the reason it must get), runs the hardening and review suites, and checks the supply chain: every workflow pins its actions by commit SHA, gives every job read-only permissions (CodeQL's upload of its results is the one write), reads no secret, sets only listed environment variables (noPIP_*option but the version check), uses only listed actions with listed inputs and no container, service or reusable workflow, puts no expression into a script, and runs only listed command lines in bash, so nothing is fetched or installed but by hash-pinned, wheels-only pip; no tracked file holds a credential; the guard, the launcher andsync_hosts.pyimport no network module, the guard starts no program but git, and the git-layer hook runs onlygit rev-parseand the chained hook. In a partial clone, git itself fetches objects missing from the local store from the promisor remote when the guard reads a diff. zizmor audits the workflows and the Dependabot configuration with its pedantic persona and its online audits of the pinned actions, with inline ignores and configuration files disabled and every input collected, and fails on any finding or any file it cannot parse. - Every CI install takes wheels only from a requirement file that pins each package by version and sha256:
.github/requirementsfor Python 3.14 (pytest and PyYAML, coverage, zizmor) and.github/requirements-py39for the Python 3.9 legs, frozen at the last releases that support 3.9. Dependabot moves the SHA-pinned actions and the.github/requirementspackages to new releases once a release is at least seven days old.
Changed
- The guard's git runner starts only the local subcommands the guard uses (
--version,branch,check-ref-format,config,diff,for-each-ref,merge-base,rev-parse,status,worktree) and refuses any other first argument withGIT_FAILEDbefore git starts; none of these subcommands talks to a remote (in a partial clone, git itself fetches the objects a diff needs from the promisor remote). - The deny for an auto-named worktree tells the agent to plan
worktree-<name>and then callEnterWorktree name=<name>; a refusedreleasenames uncommitted changes in the lane's worktree as the reason. - The launcher's failure warning names the absolute guard path and a stop instruction for every host; its POSIX part reads the payload once, starts Python once, and gives a Windows Python the Windows spelling of the guard path.
- The test line that made the Hermes plugin scanner refuse
hermes plugins update magosfor 1.0.1 (text echoed into a shell) moved into a data file the scanner does not read, and a contract test keeps that shape out of every shipped file. When the scan still asks for confirmation, an unpinned install updates withhermes plugins install UlyssesLeoLee/MAGOS --force --enable. - The Claude Code plugin description no longer tells marketplace users to clone the repository as well.
- The skill's
compatibilityline states Git 2.36+ for the lane guard beside Git 2.30+ for the commands.
Upgrade
- Upgrade the plugin on each host (
references/installation.md, "升级"). Restart every running Claude Code session: a session started before the update keeps running the previous guard. A Hermes install pinned with--refmoves its pin withhermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.2> --force --enable;hermes plugins updateand a reinstall without--refkeep the old commit. - Refresh the guard copy: run
doctorfrom the new version (with--home <dir>for a copy installed withinstall --home <dir>) and, in your own terminal, theinstall --host <host>commands it prints. Compare each printed snippet with the entry in your host configuration and replace the entry when they differ: the Claude entry of a user-level snippet differs from 1.0.1 in every case (its matcher and its quoting); the Hermes command differs when the Hermes plugin is installed and, on macOS and Linux, in every case (1.0.1 generated invalid YAML there); the Codex command differs when the guard home's path holds an apostrophe. - In armed repositories, run
doctorand re-runarm: the git-layer hook changed, sodoctorreports the installed hook as different from this version untilarmruns again, and it also reports a recorded guard command that is missing or older than this guard. A repository armed by 1.0.0 or 1.0.1 has no record of its previous pack-refs settings, sodisarmleavesgc.packRefsandmaintenance.pack-refs.enabledatfalse; restore Git's defaults withgit config --local --unset gc.packRefsandgit config --local --unset maintenance.pack-refs.enabled. - Scripts that abbreviate guard options (
--rep) must spell them out, and scripts that run user-only commands throughrun-guard.cmdmust run the guard script itself.
Compatibility: claim files of 1.0.0 and 1.0.1 are read unchanged. Exit code 18 is new.
Known issues
- Every host receives the whole repository,
tests/,.quality/and.github/included (more than 1 MB that the skills and hooks never run), because the marketplace source is the repository root. The Hermes plugin scanner reads these files as well; its verdict for 1.0.2 is safe, and contract tests keep the shapes it rates high out of every shipped file. A slim runtime payload is not part of 1.0.2. - Nothing checks that a change to shipped files raises the version, and Claude Code updates an installed plugin only when the version changes.
- When the Hermes plugin holds another guard version,
install --host hermesnameshermes plugins update magosand the unpinned--forcereinstall; a pinned Hermes install moves its pin instead (step 1 above). - The source-contract runners keep tracked evidence for 8 of the 23 Codex cases and 5 of the 20 Claude cases; a run without
--checkwrites the evidence of the other cases as untracked files. references/lane-split.mdsection 12 lists the limits of the lane guard itself.
1.0.1
Tag v1.0.1 (commit bab8606).
Security
- On Windows with Python 3.13 or later, a
cdto a POSIX-rooted directory that cannot be mapped to a drive (/does/not/exist) beforegit worktree add -borgit switch -cwas judged against a repository that does not exist, and the creation was allowed without a manifest. Python 3.13 changedos.path.isabson Windows, and the hooks run under thepython3found on the machine. The guard maps such a path to no directory and judges the creation in the session's repository.
Fixed
- The package contract suite runs again (
tests/codex/contracts/skill_frontmatter.pyrestored).
Upgrade
Upgrade the plugin, restart every Claude Code session, and re-run install --host codex|hermes for the guard copy under ~/.magos/guard.
1.0.0
Commit 74bf82f; no tag. Do not install or pin it: its guard has the Windows Python 3.13+ bypass fixed in 1.0.1.
- The package is renumbered from 3.4.0 to 1.0.0 and installs as the plugin
magosfrom the Claude Code, Codex and Hermes plugin marketplaces (.claude-plugin/, the rootplugin.json,plugin.yamland__init__.py), with the entry skillskills/git-orchestrator; Claude Code also loads a clone in~/.claude/skills/magosas the plugin. /GitSweep:/GitConverge, then the lease-guarded deletion of merged remote branches.- The lane guard: a branch or worktree needs a registered file manifest before it is created, and a creation that overlaps another lane is denied (Claude Code plugin hooks, generated Codex and Hermes entries, and the opt-in
reference-transactionbackstop).