Guide 18 of 61 · Writing policy
Catch poisoned agent configs before launch
Scan the instruction, settings, hook, plugin and MCP files your agents read for hidden text and auto-approval switches, and gate CI on the result.
Steps marked preview rely on a package that has not passed its release gate.
Scan the instruction, settings, hook, plugin and MCP files your agents read for hidden text, auto-approval switches, commands a repository makes the agent run and unpinned sources; decide in policy which findings only alert and which deny; and gate CI on the result. In preview, the launcher applies the same posture at every launch and holds new hooks, plugins and MCP servers until you approve them.
1. Scan a project
agentgarm scan inventories the files agents read in the current directory and in your home: CLAUDE.md, .claude/settings.json, .mcp.json, .cursor/rules/, AGENTS.md and the other locations each agent loads. It reads files only: nothing is executed, fetched or changed. --project names another directory, --no-home leaves your home out, and --json prints the inventory with each file's hash. Without --policy every finding alerts and the scan exits 0.
agentgarm scanagentgarm scan --no-home --jsonChecked by the walk: these commands ran as written on a no-root Linux install.
2. Read the findings
Each line starts with ALERT, WOULD-DENY or DENY, then the class and code, the file (relative to the project, or under ~/) with its line, and a detail; the last line counts the artifacts and findings. The classes are injection (text a reviewer cannot see, and imperatives aimed at the agent), auto_approval (settings that let the agent act without asking), executable_config (hooks, helper commands and MCP servers a repository makes the agent run), unpinned_source (plugins and packages taken by branch, tag or range), secret, credential_path and integrity (a file the scan could not check in full).
A secret is reported by rule, never its value, and hidden characters are escaped, so the report cannot rewrite your terminal. The imperative list and the credential paths are heuristics: a finding is a prompt for review, not proof.
3. Set the agent_config posture
security_boundaries.agent_config in your policy sets allow, alert (the default) or deny for each class. When on_integrity is unset it denies whenever another class denies, so a repository cannot slip a file past a deny by making it uncheckable. Scan with --policy to apply it: in enforce mode a denied finding exits 1, and in audit mode it is listed as WOULD-DENY. The default packs set no posture, so every class alerts until you add one.
agent_config: # agent-configuration supply chain (`agentgarm scan`)
on_injection: deny # hidden text or agent-directed imperatives in rules files
on_auto_approval: alert # bypassPermissions and equivalents
on_executable_config: alert # project hooks, helpers, MCP servers
on_unpinned_source: deny # plugins and packages by branch or tag
on_secret: deny
on_credential_path: alert
on_integrity: deny # files the scan could not check (default: deny when any class denies)agentgarm scan --policy ~/.config/agentgarm/agents.d/claude-code.yamlagentgarm scan --policy ~/Library/Application\ Support/AgentGarm/agents.d/claude-code.yamlChecked by the walk: this command ran as written on a no-root Linux install.
4. Gate CI or a pre-commit hook on the scan
On its own the scan stops nothing: agents read these files themselves, so it is observed, C. It enforces where its exit code is a gate. Keep a copy of your policy in the repository and run the scan over the project alone in CI or a pre-commit hook; a denied finding under an enforce-mode policy exits 1 and fails the job.
agentgarm scan --no-home --policy claude-code.yaml5. Let agentgarm run refuse a poisoned launch
previewagentgarm run scans the configuration the launched agent would load (the workspace up to its repository root, your home and the system's managed files) under the same posture before anything runs. In enforce mode a denied finding refuses the launch with exit 1, lists each finding on stderr as DENY with its class, code and path, and records the refusal with agentgarmd; no checkpoint, sandbox or agent is started. In audit mode the findings are listed as WOULD-DENY and the launch goes ahead. On macOS the sandbox then keeps the agent from adding a hook, plugin or Codex skill (~/.codex/skills) during the session; on Linux, Landlock cannot protect those files inside the workspace or the agent's own directory, so the next launch's scan is what catches one.
agentgarm run -- claudeSee also
Watch your agent for a week, then enforceStart a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.
6. Approve new hooks, plugins and MCP servers
previewThe launcher also checks the hooks, plugins and MCP servers it would load against agentgarmd's registry of approved artifacts. Under on_unapproved: alert, the default, a new or changed one is listed with a pending id and the launch goes ahead; deny refuses the launch; approve waits for your presence approval, and refuses as under deny without a key or when the approval lapses. approve_classes adds skills and subagents.
agentgarm approve lists what is pending; review it, then approve by id, or all of it with --all on a first run. On a root install with a presence key you confirm in agentgarm presence watch (B); without a key an administrator approves with sudo agentgarm approve (C); on a no-root install your own approval counts, C. Pending ids live in agentgarmd's memory, so after a restart launch again to list them.
agent_config:
on_unapproved: approve
approve_classes: [skill]agentgarm approveagentgarm approve <pending id>
agentgarm approve --allChecked by the walk: this command ran as written on a no-root Linux install.
See also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.