Skip to content
v1.1.3Apache-2.0

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 *.cmd to cmd.exe, so every hooked tool call used to start cmd.exe on the batch-and-shell launcher hooks/run-guard.cmd in the plugin cache, which some security products block. hooks/hooks.json now runs sh "${CLAUDE_PLUGIN_ROOT}/hooks/run-guard" ..., a plain shell script, on every platform. On Windows it tries py -3 first, as the cmd launcher does.
  • The entries install prints. The Claude snippet, the Codex command and the Hermes entry outside Windows run sh '<guard home>/guard/hooks/run-guard'; the Codex commandWindows and the Hermes entry on Windows still run run-guard.cmd. install copies both launchers.
  • doctor compares both copied launchers (a missing copy is named as missing), and names a generated entry an earlier install wrote that still runs run-guard.cmd, with the install command that writes the new one: a Codex or Hermes entry that runs it through sh (it keeps working), and a Claude entry, which under Git Bash on Windows still starts cmd.exe.
  • install --host hermes names 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 nounset or errexit that the host's SHELLOPTS exports, and reads MAGOS_GUARD=off in any case, as the cmd launcher does.

Known limits

  • Codex and Hermes on Windows still start cmd.exe on run-guard.cmd for each hooked call, so a security product that reacts to batch files may still react there.
  • hooks/run-guard.cmd is unchanged, so the Codex and Hermes entries you merged before 1.1.3 keep working; they move to run-guard only when you merge the new entry.
  • If you merged the Claude entry that install --host claude printed into ~/.claude/settings.json (instead of using the plugin), it keeps running run-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

  1. Upgrade the plugin on each host and restart it: Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos; Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos.
  2. Copies under ~/.magos/guard (Codex and Hermes entries) are refreshed by running install --host <host> again; doctor names a stale copy and a generated entry that still runs run-guard.cmd; doctor reads the entries install generated under ~/.magos/guard/generated/, not ~/.claude/settings.json or the Codex and Hermes configuration: after install has written the new entry, replace the old one there yourself. On Linux and macOS, merge the entry install prints into the Codex or Hermes configuration to move it to run-guard; on Windows, if you use the install --host claude entry 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_approve without a fingerprint. For override the tool's fingerprint argument 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 --fingerprint in 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 override without --fingerprint (their approval binds the words of the command, so the denial has to be named in it); a repository at magos.approval terminal reports 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, release and set-release remove the records of the lanes they register, change or release, and an allowed creation removes those of the lane's registered manifest (a denied plan --amend keeps 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 plan for 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 never Codex 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

  1. Upgrade the plugin on each host and restart it: Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos; Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos.
  2. Copies under ~/.magos/guard (Codex and Hermes entries) are refreshed by running install --host <host> again; doctor names 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-latest names 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 on ubuntu-24.04, and the minimum Python (3.9) is tested on Linux again as well as on Windows.

Upgrade

  1. Upgrade the plugin on each host and restart it: Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos; Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos.
  2. Copies under ~/.magos/guard (Codex and Hermes entries) are refreshed by running install --host <host> again; doctor names 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 subcommands protect (user-only: approved by your click in the host's prompt or run in your own terminal, at every approval level, --release included) and protect-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 through magos_approve (subcommand protect, 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 of branch, 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 configured remote.<name>.fetch), a push or send-pack into 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 x on a protected main writes feat and is allowed; git switch main; git commit is 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, a cd anywhere 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 off does not silence a protection: only MAGOS_GUARD=off in the host process and /GitProtect <branch> --release do. doctor lists 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 commit and Set-Location C:\...\repo; ... name that repository for the creation check and the protection.
  • cmd. cd/d <dir>, cd.., cd\ and cd;<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 workdir is judged in the directory the session's terminal is in (the directory an earlier cd left, else TERMINAL_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 .git directory 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 and gh pr merge are 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.md section 12).

Upgrade

  1. Upgrade the plugin on each host and restart it: Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos; Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos.
  2. Copies under ~/.magos/guard (Codex and Hermes entries) are refreshed by running install --host <host> again; doctor names 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, hook or 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 after echo "<<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, so git -c "alias.c=!git config magos.guard off" c is denied in every repository and !rm .git/magos/ARMED where 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_approve arguments a denial names are offered only for exactly one plain invocation of this guard; after a cd, an environment assignment such as MAGOS_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 workdir that is no existing absolute directory (a drive-less /x on 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 name magos_guard (plan, version, git add scripts/magos_guard.py) are no longer blocked as unprepared.
  • doctor reads a Hermes flow list with a ] in its comment (enabled: [magos] # see [docs]) correctly.
  • Documents. SKILL.md and references/lane-split.md name 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 workdir is judged in the directory of the Hermes process, not in the directory an earlier cd of the session left (as in 1.0.7 and 1.0.8).

Upgrade

  1. Upgrade the plugin on each host and restart it: Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos; Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos.
  2. Copies under ~/.magos/guard (Codex and Hermes entries) are refreshed by running install --host <host> again; doctor names a stale copy. Armed repositories keep working; doctor says when arm should 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 policy never (and danger-full-access) Codex declines the form by itself, then the terminal remains. There is no click-free path in this route: auto-safe asks here. The plugin brings the server in the new root mcp.json (Codex starts it through git); install --host codex prints the same server as a config.toml entry for installs without the plugin.
  • One click in Hermes. The plugin entry registers two pre_tool_call callbacks 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 lives min(max(approvals.timeout, 120), 900) + 30 seconds, 330 by default.
  • doctor and install know both routes. doctor reports the Codex server file, the Hermes plugin route, a hooks: entry that Hermes has not approved (Hermes skips it without a word) and the double route (a hooks: entry next to the plugin denies before Hermes asks); install --host codex|hermes prints the entries and what to do next.
  • A route field in records and audit. Approved runs through the Codex server carry route mcp and the client name; Hermes runs carry route hermes.

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 xargs or find -exec feed, hook, an empty slot or an unknown word in the subcommand position is denied on every host (a plain command such as py -3 magos_guard.py plan --branch x --paths a b is unaffected). The user-only subcommands and mcp keep their own handling: a tool command may never start mcp.
  • The Hermes plugin turns the guard on. After hermes plugins update magos and a restart, every Hermes terminal call goes through the guard, as the Claude Code plugin does for Bash. Turn it off with MAGOS_GUARD=off, git config --local magos.guard off or hermes 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 and doctor name the click in each host and the terminal fallback; SKILL.md, references/lane-split.md, references/installation.md, references/pressure-tests.md and 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 --home path 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 \b was 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 /yolo and -z cannot 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

  1. Upgrade the plugin on each host and restart it: Codex codex plugin marketplace upgrade magos, then codex plugin add magos@magos; Hermes hermes plugins update magos; Claude Code claude plugin marketplace update magos, then claude plugin update magos@magos. After the Hermes update the guard is on for every terminal call.
  2. Codex: merge the hook entry that py -3 scripts/magos_guard.py install --host codex prints into your Codex hook file and review it once in /hooks (the plugin does not carry the hook). Hermes: remove any MAGOS hooks: entry from the Hermes config (the plugin replaces it; doctor reports the double route).
  3. Nothing needs configuring: prompt is the default level; git config --local magos.approval terminal keeps 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) and auto-safe (a plain arm and an install into the default guard home run without a click; override, disarm and every other form still ask). Any other value counts as terminal, and doctor reports 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 --approval is denied. install is approved only when the running guard itself is the script.
  • Audit of the route. Every approved run records via (terminal, prompt or auto-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>.json so 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.md and 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 sets magos.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_tty and doctor texts 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 override or disarm unattended: an agent that approved its own bypass would be no guard. The opt-out is git 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; via and reason_by are provenance, not proof.
  • Codex and Hermes keep the terminal route whatever magos.approval says; the approval route exists in Claude Code only, for the Bash and PowerShell tools.
  • The route relies on Claude Code holding a hook's ask until you click and applying the rewritten command. On Claude Code 2.1.310, headless runs showed an ask held in each of the five permission modes, a permissions.allow rule 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 --approval stops with a usage error.

Upgrade

  1. Upgrade the plugin on each host (references/installation.md) and restart every running Claude Code session: claude plugin marketplace update magos, then claude plugin update magos@magos.
  2. Nothing needs configuring: prompt is the default. To keep typing every user-only command in a terminal, run git config --local magos.approval terminal in each repository. To refresh a guard copy, run doctor from the new version and the install --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.md and README.ja.md lists what the hooks run, what the guard reads and writes (inside <git-common-dir>/magos/, plus the two steps you run yourself, install and arm), 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-orchestrator sets user-invocable: false: the / menu lists the eight /magos:GitXxx commands 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__.py no 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: false and no disable-model-invocation on the entry skill and drops the unused WRITE_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: false and disable-model-invocation: true combine: 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

  1. Upgrade the plugin on each host (references/installation.md, "升级"): claude plugin marketplace update magos, then claude plugin update magos@magos, and restart every running Claude Code session. A Hermes install pinned with --ref moves its pin with hermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.6> --force --enable.
  2. The guard changes only in its version number. To refresh the guard copy under ~/.magos/guard, run doctor from the new version and the install --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 --strict passes 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) set user-invocable: false and disable-model-invocation: true. Claude Code lists only the eight commands of commands/ (/magos:GitRecon ... /magos:GitPlan) and the entry skill git-orchestrator in 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-recon and /git-recon work 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 (true for disable-model-invocation, false for user-invocable).
  • Installation notes. references/installation.md states the one set and names the usual sources of a second one: command copies in ~/.claude/commands/ (the place scripts/sync_hosts.py --host claude writes) and a clone below ~/.claude/skills/ (its root SKILL.md is 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

  1. Upgrade the plugin on each host (references/installation.md, "升级"): claude plugin marketplace update magos, then claude plugin update magos@magos, and restart every running Claude Code session. A Hermes install pinned with --ref moves its pin with hermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.5> --force --enable.
  2. Delete command copies in ~/.claude/commands/ (Git*.md): the plugin provides the commands.
  3. The guard changes only in its version number. To refresh the guard copy under ~/.magos/guard, run doctor from the new version and the install --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 (/GitPlan in Claude Code, /git-plan in Hermes, $git-plan in Codex), with the adapters commands/GitPlan.md and skills/git-plan/ (SKILL.md, agents/openai.yaml) and the contract references/commands.md section 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 --into is a local branch that is not main. 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 with magos_guard.py set-plan --dry-run and ends with a readiness verdict (READY or BLOCKED), 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. --apply registers 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 its base differs from the live target tip, or, for an amendment, when it was built from another record revision than the current one; --create also creates the registered lane branches and worktrees from the recorded base, and without it the report prints the git worktree add lines.
  • Requirements, lanes and outcomes in tables. The plan states the requirements of the task (1 to 12, each an id such as R1 and 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; --status and --converge add State and Head), 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. --status and --converge print the tables again from the record, with [x] for the lanes that are ready or integrated and 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 in serves are 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 as claim-store, sweep-readiness, launcher-exit-codes), the lane branch is exactly agent/<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>), so git branch and git worktree list read as a list of topics. The guard refuses an ordinal or generic id (only digits, one letter, l1, lane-2, task3, worker-1 and the like, and the reserved integration: 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 stays agent/<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 as changes (commits, subjects (at most 8, oldest first), more, files, insertions, deletions, paths (at most 12) and paths_more); it is null before, a repeated integrated update keeps it, and set-show --json carries it per lane. After the merge the original list is supplemented, not replaced: the converge apply report, --status and --release print the same two tables with every row and column kept, a Changes column on the Lanes table (<commits> commits, <files> files, +<insertions>/-<deletions>), a Result column on the Requirements table (the first commit subject of each integrated lane that serves the requirement, and pending: <lane> for the others), the Changes summary (one line per lane with its commit subjects and paths) and a Total line, followed by Remaining TODO.
  • Optimistic lock. Nobody holds a lock while the lanes work. The record carries a revision that every change compares and increments and the target tip the plan was made against (base), and a lane records the head it was marked ready at. A stale plan is detected and refused, never overwritten: --amend and, optionally, --converge --apply take --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 finding STALE_PLAN, and an amendment moves base to the live target tip.
  • Convergence. --converge previews, and --converge --apply merges, the READY lanes in dependency order into one integration branch agent/<set>/integration (created with a plain git switch -c from the current target tip in the invoking worktree): each recorded head is merged with git merge --no-ff and recorded integrated with set-update, and the repository's checks run on the result. A conflict runs git merge --abort and 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-active takes an active lane that holds changes of its own against the current target as ready at 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. --land adds one git merge --ff-only of the integration branch into <branch>, only while <branch> still sits where the integration branch was cut from (otherwise LAND_REFUSED). --release prints 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 touches main, never uses override, 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 pending BLOCKED, NOT_READY and WAITING (the lane sits this run out), the failing MISSING_BRANCH, DIRTY, IN_PROGRESS, NO_MERGE_BASE, OUT_OF_LANE, SHARED_CHANGE, MOVED, CLAIM_DRIFT and STALE_PLAN (the whole command stops, so a ready lane that is inconsistent is never merged around) and the hint PREDICTED_CONFLICT. The readiness is READY, PARTIAL or BLOCKED. Every failed gate, failing finding, guard exit code and stop of an apply is followed by the action that lifts it (references/commands.md section 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 exactly agent/<set>/<id> and distinct worktree paths whose directory names end with -<set>-<id>, pairwise disjoint manifests by exact glob intersection, depends_on ids that form a DAG, every shared file inside its owner's manifest, base equal 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 of base, worktree state, the stored changes, 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 (ready needs --head equal to the branch tip and every changed file inside the manifest, integrated needs the recorded head to be in the target or the integration branch and stores the changes summary 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 like plan, release and list, options are never abbreviated, and with --json every outcome is one object with decision, code, message and exit_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): the revision, the target, the base, 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 last ready was measured against (ready_target), note and changes. 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-plan registers a claim for agent/<set>/integration (the single marker entry .magos/integration/<set>/, the extra keys set=<name> and role=integration), which is why a plain git 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. 19 STALE (the kind of a denial is base or revision, with expected and current), 20 SET_EXISTS, 21 SET_UNKNOWN, 22 OUT_OF_LANE, 23 SET_NEWER_FORMAT and 24 INVALID_SPEC (a spec or option value that is invalid in itself; the message names the field). The codes 10, 11, 13, 14, 15 and 16 keep their meaning, 12 also 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.
  • list and doctor. list shows the set and the lane (or role) of a claim. When sets/ holds a file or a claim carries set=, doctor prints sets: <n>, unreadable: <n>, newer-format: <n> and a line for each problem: a lane claim that is missing or differs from the record, an active or ready lane 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.md has 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 cases git-plan/forms-and-help, git-plan/exclusive-lanes-and-optimistic-lock, git-plan/converge-and-hard-stops and git-plan/package-wiring pin the command.

Changed

  • Plain plan and release refuse the claims of an open set. While the record of a set exists, a plain plan that 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 its set= line: an amend, other entries, the re-plan after an override) is refused with exit 14 (lane_in_set) and release of 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 branch agent/<set>/integration is known, so a lane counts only through the set= line of its claim.
  • plan keeps the registered worktree path. A plan without --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, /GitConverge and /GitSweep report its branch as BLOCKED_ACTIVE_OWNER while the set is open; --release lifts it.
  • Paths from the top of the work tree. Every git call of the guard carries -c diff.relative=false, so a diff.relative=true configuration 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, and plan, check and the set subcommands with a --repo below 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, log and status call of the guard carries --ignore-submodules=none, so neither diff.ignoreSubmodules, nor submodule.<name>.ignore, nor the ignore of .gitmodules hides a changed submodule pointer (a gitlink) or a submodule checkout that differs from it: plan, check and the hook count such a path as committed or uncommitted evidence and judge it against the manifests, plain release refuses a branch whose worktree holds such a change, the pinned -c diff.ignoreSubmodules=none carries the same into the status Git 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_VERSION is 1.0.4, and /GitPlan checks magos_guard.py version first 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 --help and --lang), the plugin manifests, COMMAND_NAMES of scripts/sync_hosts.py, INDEX_DESCRIPTIONS of __init__.py, references/installation.md and the three READMEs. Five adapters write to a repository and set disable-model-invocation: true in Claude Code (git-integrate, git-cleanup, git-converge, git-sweep and git-plan); the Codex adapters all disable implicit invocation, and git-plan refuses 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 /GitPlan ask 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 in list or doctor, 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 refuse release or plan --amend of 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) shows mismatch or missing in set-show and in doctor. 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.md section 12) are unchanged.

Upgrade

  1. 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 --ref moves its pin with hermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.4> --force --enable; hermes plugins update and a reinstall without --ref keep the old commit.
  2. Refresh the guard copy: run doctor from the new version (with --home <dir> for a copy installed with install --home <dir>) and, in your own terminal, the install --host <host> commands it prints. Compare each printed snippet with the entry in your host configuration and replace the entry when they differ.
  3. 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 --stdin records. 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 piped echo, printf, Write-Output, Write-Host or a cat of here-documents. The record is dynamic, and denied as unparseable where creations are guarded, unless every create and update is a plainly read name: \0, \n, \t and \r separate the fields as printf writes them, and any other escape (\x62), a quote or an expansion in a name, a printf format, 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 mentions update-ref --stdin is 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 terminal tool, shell, MCP command tools), a program word written with a backslash, a backtick or a caret (g\it, g`it, g^it, also after env) 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. --ex and --exe, with the value attached by = or separate, are read like --exec, and the commands they run are judged. --e is 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 git word of a line after the values of the global options (-C <dir>, -c <key=value>, --git-dir=<dir>, a path-qualified git), in one pass, so a line of any length is read within the time budget.
  • refs/heads in any case. refs and heads under 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 in git update-ref, in git push and git fetch refspecs, in update-ref --stdin records and in git symbolic-ref, and by the reference-transaction hook of an armed repository, which vetoes a creation under such a spelling without a claim.
  • git update-ref options. Options are read as git reads them: -m <message> and -mMESSAGE take a value, --std and --s are --stdin, and the bundled and separate forms of -d, -z and -m are read, so a creation written with them is judged. Deleting a ref and a --no-deref update of HEAD create nothing.
  • Start-Process working directory. Start-Process git runs git in its -WorkingDirectory (also -Wo, -wo and the colon form -WorkingDirectory:<dir>), and a creation in its -ArgumentList (-a, colon forms) is judged in the repository of that directory; without -WorkingDirectory it is judged where the shell is.
  • PowerShell option spellings. Every spelling of -Command, -CommandWithArgs and -EncodedCommand that powershell and pwsh accept (-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 Bypass is the execution policy option, and bash -ec is bash.
  • PowerShell backtick. In PowerShell text the backtick is the escape character with its special sequences: g`it is git, git sw`itch is git switch, and gi`t is gi followed 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 cd to 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 py exits 103 or 112 (py without a Python runtime), and the verdict of the guard that runs comes through with exit 0. Any other exit of py is 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 --amend for that name is refused with exit 12 and names the rule, list shows the claim with the rule (refused_name in --json), and doctor names 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 HEAD and bash -c >/dev/null '..' are judged like their plain forms; 2>&1, >&2, &>f and >|f are 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 branch bundled 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, -rd and -vd delete or list and create nothing, and -mr, -m -r, -m -a and -c -r rename or copy, so the new name is judged (git branch -m -r a b creates b).
  • git symbolic-ref and dynamic ref words. git symbolic-ref reads -m <reason> (also -qm) and --, so git symbolic-ref -m why HEAD refs/heads/z creates z. A first positional word of git update-ref that is dynamic ($ref), and a dynamic name or target of git symbolic-ref, is a dynamic creation when it may name a branch (also behind xargs); only a literal refs/ namespace other than heads names none.
  • Refspec destinations. The destination of a fetch, pull or push refspec is read on its raw text: refs/heads/refs/x creates the branch refs/x, another destination that begins with refs/ 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, pull and push, whose operand is a full ref (refs/heads/-x); only a name that git certainly refuses is dropped.
  • Time bounds. A chain of relative -C values 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> is main or the remote default, when the converge phase stopped or its validation failed, or when the remote sweep is UNKNOWN. When the live remote tip equals the local tip nothing is pushed and the report says PUBLISH_NOT_NEEDED; otherwise the push runs even when no remote branch depends on it. A failing push is reported as PUSH_FAILED and never retried; a push after which the remote tip differs from the local tip is PUSH_UNCONFIRMED and 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 no refs/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 /GitSweep ends with a verdict (ONE_SHOT, PARTIAL or BLOCKED), a recommended command (/GitSweep <branch> --apply with --remote and --lang as given, carrying exactly the flags that lift something: --discard-ignored with the ignored files it deletes listed, --push, whether or not it was typed, when a remote branch is PUSH_THEN_DELETE, and a typed --push whose 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-ignored as 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 only main and <branch> as local branches, the worktrees of the deleted branches removed, and every remote branch deleted or NOT_TOUCHED; a worktree the command never touches (a detached one, or one that holds main or another kept branch) is listed in the report. Apart from a typed --push that 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 --push whose publish will not run is dropped from the line, and the report says why.
  • Remedies. Every failed gate, delete blocker, UNKNOWN status and PREDICTED_CONFLICT in a /GitConverge or /GitSweep report is followed by the action that lifts it (references/commands.md section 6, Remedies; section 7 adds the remedies for remote findings, among them the one for a --remote that git remote does not list, and separate remedies for PUSH_THEN_DELETE without --push and for PENDING_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 than main is told to create main deliberately or not to use the command.
  • Run state. The /GitSweep apply report ends with COMPLETE or PARTIAL. A PARTIAL report 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, so Next preview: is the same line without --apply, to run once the remedies are done so that the preview becomes the earlier plan, and Next 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 --remote and --lang as given. The Next command: line carries --push when some remote branch ended PUSH_THEN_DELETE or PENDING_PUSH for a reason that a rerun with --push can clear, or when --push was typed and the publish prediction says the push would still run; it never carries --push when the only reason is that <branch> is the remote default; with phase 2 UNKNOWN it carries --push only 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_DELETE marks a branch whose deletion depends on the publish step, which is predicted to run (in a preview with or without --push; an apply without --push leaves it and reports "kept: --push not typed"); PENDING_PUSH marks 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 --push or, 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. /GitConverge and /GitSweep evaluate every gate and report every failed one together with its remedy. /GitSweep adds the gate --remote <name> not listed by git remote, with its remedy, and a failed gate makes its verdict BLOCKED. The Default line of the /GitConverge help says that every failed gate and blocker is followed by the action that lifts it.
  • Hard stops. The /GitSweep hard stop on pushing commits and tags reads: except the one fast-forward push of <branch> that --push makes. The lease-guarded deletion of one named remote branch at a time is the other push. /GitConverge pushes 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, --remote included.
  • Argument safety and names. Every git command of /GitConverge and /GitSweep runs 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 not NOT_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 is UNKNOWN (neither merged nor deleted; the remedy is to rename it), and a remote branch with such a name is BLOCKED_BAD_NAME, which keeps the readiness verdict at PARTIAL. The typed <branch>, the remote default and main are covered by the argument rule alone.
  • One URL. The remote sweep and the publish step are UNKNOWN unless git remote get-url --all <remote> and git 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 is git remote set-url --delete <remote> <extra-url> for each extra URL, and git config --unset-all remote.<remote>.pushurl for a separate push URL.
  • Live remote HEAD. Phase 2 is UNKNOWN unless the ref: line of git ls-remote --symref for HEAD names exactly the remote default; a live HEAD that is detached, unborn or missing makes the whole sweep UNKNOWN, and the remedy is to set the default branch on the remote or its host (git remote set-head <remote> --auto cannot fix it).
  • Worktrees with submodules. BLOCKED_SUBMODULE is decided the way git decides: the git directory of the worktree contains a modules directory, 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 with git 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 against ONE_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-parent chains 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 includes main.
  • update-ref --stdin from a file or another command. An update-ref --stdin whose 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 piped echo, printf, Write-Output or Write-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 -C values or cd targets 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 spelled git.exe, Git or 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_DIFF and a rebase --exec or bisect run text with a dynamic program are not inspected; keep the repository armed.
  • Wrappers and program spellings outside the walker's lists. ionice, flock, taskset, coproc and similar wrappers, a path-qualified env, nohup, xargs or sudo, 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 as fish and tcsh hide 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 of update-ref is 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, .bash or .ps1 name (./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 cd into a directory that mkdir creates 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 --refmap and -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 through git 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 cmd and its start. cmd switches other than a lone /c or /k (/r, /d/c, /cgit) and cmd /c start are not read; keep the repository armed.
  • Start-Process of shells and splatting. A shell that Start-Process starts, a call through splatting and an -ArgumentList cut at commas and read with shell quoting are not read as written; keep the repository armed.
  • Options of child shells. pwsh -WorkingDirectory, a powershell -File script behind four option values and env -S with bundled options (-vS) or the \_ separator are not read; keep the repository armed.
  • The tamper filter. The tamper filter does not follow Start-Process lists, cmd /r, env -S, iex and ScriptBlock::Create, so the git layer itself can be removed; run doctor to see that it is still installed and re-run arm when 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 named get_branch, the help forms of gh 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. An update-ref --stdin fed 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 piped echo or printf feeds 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

  1. 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 --ref moves its pin with hermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.3> --force --enable; hermes plugins update and a reinstall without --ref keep the old commit.
  2. Refresh the guard copy: run doctor from the new version (with --home <dir> for a copy installed with install --home <dir>) and, in your own terminal, the install --host <host> commands it prints. Compare each printed snippet with the entry in your host configuration and replace the entry when they differ.
  3. In armed repositories, run doctor and re-run arm: the git-layer hook reads refs and heads in any case, so doctor reports the installed hook as different from this version until arm runs again.
  4. 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_DIR or GIT_COMMON_DIR (prefix, env, export, PowerShell $env:, cmd set) 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; under GIT_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 a GIT_DIR or GIT_COMMON_DIR change the hook does not follow (read, printf -v, +=, builtin export, Set-Content Env:). --work-tree and GIT_WORK_TREE alone leave the judged repository unchanged.
  • Directory changes the shell may not make. A cd, pushd, Set-Location or GIT_DIR change 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), inside if, case or 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 as env 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 x and cd dir; git switch -c x are still judged in dir only.
  • Directories handed to wrappers. env -C <dir> (--chdir) and sudo -D <dir> (--chdir) run git in <dir>, but the hook judged the directory the shell was in. They are judged like git -C <dir>. A session directory written with ~ (~/repo, ~user/repo) is expanded, and a relative tool directory is joined to the payload's directory.
  • cd to a missing directory. cd or Set-Location to 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. For cd, pushd, chdir, Set-Location and sl, the creation is judged in that prior directory and denied as unparseable when it is guarded, on every platform; the same holds for a cd the shell refuses (cd /d dir in bash, cd dir extra), while cmd's cd /d dir is followed into dir.
  • 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 sh and | doas sh let 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 commands git rebase --exec and git bisect run run 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>2 is main2), 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 of git switch and git checkout abbreviated to two letters (--cr, --or), a branch name after git 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-*), a git push into 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 Monitor tool and MCP tools that run commands (run_in_terminal, terminal, shell, exec_command, execute_command, start_process, and names holding command, exec, execute, process, bash, powershell or cmd) were not inspected. They are hooked, the Claude matcher is generated from the guard's tool list, and the command string 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.cwd is read as the session directory.
  • Payloads the hook could not decode. A payload whose decoding raised (deep nesting gives RecursionError or MemoryError) was allowed. It is denied when its bytes hold a lane word (git, worktree, isolation, EnterWorktree, magos and 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, python or git placed in the hook's working directory. Both set NoDefaultCurrentDirectoryInExePath=1 before starting any program, and the launcher's cmd half finds its interpreter on PATH only.
  • User-only commands. override, arm, disarm and install passed the host hook when a global option was written as --repo=., --lang=en or abbreviated (--rep .), when -- stood before the subcommand, when they were run through the launcher run-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 the hook subcommand (exit 2 for any other), and install needs a real console like arm (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 plan reads override records; after the user's override, a re-plan registers it in the claim, and the hook honours only the claim.
  • Claim store. release with 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./bar and foo/bar, names ending in .claim) overwrote another lane's claim; a newline in --worktree or user.name added lines to a claim file; two planners could register clashing names at once; and on Linux release with a spelling that holds .., ., an empty segment or a backslash (zz/../FEAT) found no claim. release reads 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's move and copy, PowerShell's cpi, sc, ac, ni and clc and 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 .bat or .cmd shim 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 through call, install refuses 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. arm keeps a repository's own reference-transaction hook as reference-transaction.magos-prev and runs it from the backstop. On POSIX a previous hook without the executable bit, which git itself never runs, failed with exit 126 in the prepared phase 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-converge and git-sweep set disable-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.
  • install is version-aware and atomic: it prints guard copy <old> -> <new> or guard copy unchanged (<version>), writes both files to temporary files and replaces both or neither (the launcher stays executable on POSIX), rewrites guard/VERSION.json (version, sha256, source, time) and appends to <guard home>/audit.log on every run that is not a dry run, and refuses to replace a newer copy with exit 18 (DOWNGRADE_REFUSED) unless --allow-downgrade is given.
  • doctor [--home DIR] prints the running guard's version, compares the guard copy (under --home, MAGOS_HOME or ~/.magos; from the copy itself, against the source its VERSION.json names) with it and prints the exact install --host <host> refresh command (also outside a repository), prints the copy's provenance from VERSION.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 the arm command to re-run.
  • arm records, as the guard command of the backstop's deny message, the copy under ~/.magos (or MAGOS_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 previous gc.packRefs and maintenance.pack-refs.enabled values in arm-config.json, and disarm restores them. arm and disarm append to the repository's audit log.
  • Claim format gate: every claim carries v= (any integer spelling, v=01 included, reads as that integer); a claim written by a newer MAGOS is never misread (creations are denied with CLAIM_NEWER_FORMAT and a message that says to upgrade the guard, release refuses it, plan never overwrites it), and list shows unreadable and newer-format claim files.
  • The Hermes entry that install --host hermes writes 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, and install says 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.py recognises 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.json on 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 to main, develop_claude and develop_codex, on v* 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 (no PIP_* 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 and sync_hosts.py import no network module, the guard starts no program but git, and the git-layer hook runs only git rev-parse and 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/requirements for Python 3.14 (pytest and PyYAML, coverage, zizmor) and .github/requirements-py39 for the Python 3.9 legs, frozen at the last releases that support 3.9. Dependabot moves the SHA-pinned actions and the .github/requirements packages 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 with GIT_FAILED before 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 call EnterWorktree name=<name>; a refused release names 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 magos for 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 with hermes 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 compatibility line states Git 2.36+ for the lane guard beside Git 2.30+ for the commands.

Upgrade

  1. 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 --ref moves its pin with hermes plugins install UlyssesLeoLee/MAGOS --ref <40-character SHA of v1.0.2> --force --enable; hermes plugins update and a reinstall without --ref keep the old commit.
  2. Refresh the guard copy: run doctor from the new version (with --home <dir> for a copy installed with install --home <dir>) and, in your own terminal, the install --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.
  3. In armed repositories, run doctor and re-run arm: the git-layer hook changed, so doctor reports the installed hook as different from this version until arm runs 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, so disarm leaves gc.packRefs and maintenance.pack-refs.enabled at false; restore Git's defaults with git config --local --unset gc.packRefs and git config --local --unset maintenance.pack-refs.enabled.
  4. Scripts that abbreviate guard options (--rep) must spell them out, and scripts that run user-only commands through run-guard.cmd must 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 hermes names hermes plugins update magos and the unpinned --force reinstall; 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 --check writes the evidence of the other cases as untracked files.
  • references/lane-split.md section 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 cd to a POSIX-rooted directory that cannot be mapped to a drive (/does/not/exist) before git worktree add -b or git switch -c was judged against a repository that does not exist, and the creation was allowed without a manifest. Python 3.13 changed os.path.isabs on Windows, and the hooks run under the python3 found 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.py restored).

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 magos from the Claude Code, Codex and Hermes plugin marketplaces (.claude-plugin/, the root plugin.json, plugin.yaml and __init__.py), with the entry skill skills/git-orchestrator; Claude Code also loads a clone in ~/.claude/skills/magos as 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-transaction backstop).