Skip to content

fix(setup): wire the agent-guard hook into settings.local.json, not settings.json - #1115

Open
AmirF194 wants to merge 2 commits into
apache:mainfrom
AmirF194:fix/824-agent-guard-settings-local-json
Open

fix(setup): wire the agent-guard hook into settings.local.json, not settings.json#1115
AmirF194 wants to merge 2 commits into
apache:mainfrom
AmirF194:fix/824-agent-guard-settings-local-json

Conversation

@AmirF194

Copy link
Copy Markdown

Summary

Type of change

  • Skill change (.claude/skills/<name>/): eval fixtures updated below
  • 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)
  • Other:

Test plan

  • prek run --all-files passes
  • For Python packages touched: uv run pytest / ruff check / mypy passes
  • For Groovy bridges touched: command-line invocation tested end-to-end
  • For skill changes: eval suite passes for the affected skill
  • For skill behaviour changes: a new or updated eval fixture is included in this PR
  • Other: ran the individual hooks by hand rather than prek run --all-files (installing prek's full tool set was not practical here): markdownlint-cli2 and typos on all 6 changed files (clean); skill-and-tool-validate run directly with PYTHONPATH against the stdlib-only validator package (0 hard failures, same 29 pre-existing soft warnings on unrelated skills, none on the touched files). Could not run the lychee link-check hook (its cargo install build ran the local disk near empty and was aborted); checked by hand instead that every link this diff adds or edits is an in-repo anchor (worktree-init.md#step-1d-..., adopt.md#step-10-..., adopt.md#step-12-..., ../../tools/agent-guard/README.md) and confirmed each target heading/file exists on this branch. Also extracted the diff's own idempotent-merge Python and ran it standalone against five fixtures (missing file, unrelated existing keys, already-wired no-op, hand-corrupted JSON, a second pre-existing Bash matcher) to confirm the merge behaves as described in each case. Checked docs/vendor-neutrality.md's inputs (**Vendor:** / **Harness:** fields in tools/agent-guard/README.md) are untouched by this diff, so the vendor-neutrality-score hook has nothing to regenerate.

RFC-AI-0004 compliance

  • HITL: any new mutation is gated on explicit user confirmation
  • Sandbox: no new unrestricted host access; network reach declared in the adapter
  • Vendor neutrality: placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose (the check-placeholders prek hook is the mechanical gate)
  • Conversational + correctable: agentic-override path documented if behaviour is adopter-tunable
  • Write-access discipline: no autonomous outbound messages; drafts only, sent on confirmation
  • Privacy LLM: private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Fixes #824

Notes for reviewers

.gitignore already lists /.claude/settings.local.json as a base entry (Step 7), so nothing there needed to change; only the destination the docs point /magpie-setup at moved.

@AmirF194

Copy link
Copy Markdown
Author

Flagging for whoever reviews this: #913 also touches the same "Hook wired in settings.json" bullet in verify.md (and a nearby line in worktree-init.md), as part of its broader adopt/install rename. Its edit there is a link-text rename only, not a fix for the issue this PR addresses, so I do not think it is a competing claim, but the two will conflict on merge and whichever lands second will need a rebase.

@AmirF194

Copy link
Copy Markdown
Author

Thanks for the review. The red ruff format (workspace) check flags three files this PR does not touch (contributor-nomination/fetch.md, contributor-sentiment/SKILL.md, issue-reproducer/verification.md), so it looks like pre-existing drift rather than something introduced here. Happy to rebase once #1092 settles if that clears it.

…ettings.json

The adopt flow committed the agent-guard PreToolUse wiring into the
tracked .claude/settings.json while the script it invokes
(.claude/hooks/agent-guard.py) stayed gitignored, synced in only by
/magpie-setup. That split forced two prior workarounds for the same
root cause: apache#786 guarded the command against a fresh clone that has
the wiring but not yet the script, and apache#823 rewrote that guard for
Windows, where the POSIX conditional does not run.

Move the wiring itself into the gitignored, per-machine
settings.local.json, written by Step 12 pass 1 at the same moment
the script is deposited. Once wiring and script exist together on
the same schedule, the fresh-clone race is gone and the command
collapses to a plain `python3 "..."` call that runs the same on
POSIX and Windows, so both the apache#786 guard and the apache#823 rewrite
become unnecessary. This supersedes apache#823 and retro-justifies
removing the apache#786 guard.

Updates the merge/read/clean side for the same wiring across
adopt.md (Step 12 pass 1, Step 2), worktree-init.md (Step 1d),
unadopt.md, and verify.md, plus tools/agent-guard/README.md's
documented snippet. The idempotent-merge Python (skip if already
wired, preserve every other settings.local.json key and
hooks.PreToolUse matcher, leave a hand-edited/corrupt file alone) is
unchanged from the existing Step 12 pass 3 pattern for the
sandbox-allowlist entry.

Fixes apache#824

Generated-by: Claude Code (Sonnet 5)
@AmirF194
AmirF194 force-pushed the fix/824-agent-guard-settings-local-json branch from e62c5c1 to 662cd63 Compare August 26, 2026 14:38
@AmirF194

Copy link
Copy Markdown
Author

Rebased onto main to resolve the conflict with #913 flagged above. Both bullets now point at install.md (the renamed file) while keeping the settings.local.json content from this PR. No other changes.

…tall.md

The apache#913 rebase repointed two of the three adopt.md links in this file
but missed the one inside the settings.local.json wiring bullet this PR
adds, which is what the CI link validator (prek, validate skills and
tool contracts) has been failing on.
@AmirF194

Copy link
Copy Markdown
Author

Found and fixed a leftover: the #913 rebase repointed two of the three adopt.md links in worktree-init.md to install.md, but missed the one inside the settings.local.json wiring bullet this PR adds. That was the actual cause of the prek and validate skills and tool contracts CI failures, not the pre-existing skill-line-limit warnings. Pushed 8b71010.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

setup: write the agent-guard hook to gitignored settings.local.json instead of committing it to settings.json

2 participants