Skip to content

fix(setup): recognise the agent-guard plugin as a complete install - #1323

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:fix/update-skill-agent-guard-plugin
Sep 21, 2026
Merged

potiuk merged 1 commit into
apache:mainfrom
potiuk:fix/update-skill-agent-guard-plugin

Conversation

@potiuk

@potiuk potiuk commented Sep 21, 2026

Copy link
Copy Markdown
Member

Summary

  • setup-isolated-setup-update only knows the user-scope agent-guard wiring: check 3 diffs ~/.claude/scripts/agent-guard.py and ~/.claude/scripts/guards.d/, check 4 looks for an agent-guard hooks.PreToolUse entry in settings.json. Neither exists on the install path tools/agent-guard/README.md calls "the whole installation" — the magpie-agent-guard plugin registers the hook from its manifest and resolves the engine plus every skill-owned guard under ${CLAUDE_PLUGIN_ROOT}.
  • So a drift run against a working plugin install reports the guard as missing and sends the operator installing a second copy of something already running. Observed here: magpie-agent-guard@apache-magpie enabled, no script copy, and both guards demonstrably firing.
  • The check now establishes which wiring is in use before diffing, and gains a behavioural canary so the verdict rests on the guard denying rather than on files being present.

Type of change

  • Skill change (.claude/skills/<name>/) — see test plan for why no eval fixture
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)

How it works

Check 3 reads enabledPlugins first. With magpie-agent-guard@apache-magpie present, the absent script copy is stated to be the expected shape rather than drift, and what gets surfaced instead is the plugin's version against the framework's (refresh is /plugin) plus any leftover user-scope copy from an earlier hand-wiring. The existing script + guards.d diff is kept verbatim for the non-plugin path. Check 4's agent-guard clause gains the same condition, so a settings.json with no agent-guard hook reads as correct under the plugin.

Both paths then share one canary: a git commit whose message carries a Co-Authored-By: trailer must be denied by the bundled commit-trailer guard. A command that goes through means the hook is not firing, whatever the files say — which is the only claim the check is really trying to make.

Test plan

  • prek run --all-files passes (32 hooks, exit 0).
  • Canaries run against the plugin install this PR is about: git commit with a Co-Authored-By: trailer → denied by commit-trailer; a second commit → denied by the operator's own trailer guard. Under the old text this install reads "agent-guard not installed"; under the new text it reads as correctly wired.
  • No eval fixture added. None of the skill's four eval suites extracts check 3 or 4, and the change is a read-order instruction rather than a classification boundary.

RFC-AI-0004 compliance

  • Conversational + correctable — read-only and proposal-only throughout; only the reported verdict changes.
  • Vendor neutrality — the plugin id and /plugin are named inside the skill's existing Claude Code branch, after the Codex / Gemini routing has already returned. See the note below about the generated score.

Linked issues

None.

Notes for reviewers (optional)

  • The neutrality counter moves, and that is this diff: docs/vendor-neutrality.md shifts one skill from capability-pure (14 → 13) to portable (61 → 62), because the Claude branch now names a Claude plugin id. vendor-coupled stays 0. If you would rather the skill stay capability-pure, the alternative is a generic "the harness may supply the guard from an installed extension" phrasing — less useful, since the operator has to know the exact id to check for.
  • docs/mode-economics.md moves because the skill-token-count hook remeasures the skill.
  • This is the third in a set of independent fixes to the same skill found in one drift run; the other two are the allowedDomains staleness and the dispatcher hook flavour. Each is its own PR and they do not overlap in the file.

🤖 Generated with Claude Code

@potiuk potiuk added family:setup setup-* skills capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) labels Sep 21, 2026
@potiuk
potiuk force-pushed the fix/update-skill-agent-guard-plugin branch from b690ba3 to 0925d3c Compare September 21, 2026 15:53
Check 3 of `setup-isolated-setup-update` diffs
`~/.claude/scripts/agent-guard.py` and `~/.claude/scripts/guards.d/`
against the framework, and check 4 looks for an agent-guard
`hooks.PreToolUse` entry in `settings.json`.  Neither exists on the
install path the tool's own README calls "the whole installation":
the `magpie-agent-guard` plugin registers the hook from its manifest
and resolves the engine and every skill-owned guard under
`${CLAUDE_PLUGIN_ROOT}`.

A drift run against a working plugin install therefore reports the
guard as missing and sends the operator installing a second copy of
something already running.  Observed on an install where the plugin
was enabled and both guards demonstrably fired.

Establish the wiring first: read `enabledPlugins`, and on a plugin
install report the plugin's version against the framework's and any
leftover user-scope copy, rather than the absence of a script that
belongs to the other wiring.  Keep the script/`guards.d` diff for the
user-scope path, and give both a behavioural canary — a `git commit`
carrying a `Co-Authored-By:` trailer must be denied — so the check
rests on the guard denying rather than on files being present.

Generated-by: Claude Opus 5
@potiuk
potiuk force-pushed the fix/update-skill-agent-guard-plugin branch from 0925d3c to 064d772 Compare September 21, 2026 16:36
@potiuk
potiuk merged commit 7593508 into apache:main Sep 21, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) family:setup setup-* skills

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant