Setup Local Guards

Set up local guard packs

Inspect the installed configuration, explain the relevant packs, ask for approval, then configure and test only the user's choices. For a question about existing behavior, stop after explaining it; do not change settings.

Safety rules

• Ask before enabling or disabling guards, changing packs, editing rules, or changing the session destination.
• Preserve custom rules, credentials, capture settings, and the user's Cloud forwarding choice.
• Never execute a dangerous command to test a guard. Pass quoted command text only to agento11y guards test.
• Never test with real secrets or print config.env; it can contain credentials.
• Explain that guards cover only tool calls submitted through the integration. They are not an operating-system sandbox.
• Do not claim live protection from an offline dry run. A matching rule and a working host hook are separate checks.

1. Inspect the installation

Run:

agento11y --version
agento11y guards test --help
agento11y local status

If the binary or local guard commands are missing, explain what is missing. Offer agento11y skills show setup-coding-agent for installation or host integration setup. Do not assume an older binary includes this skill or every pack. Local mode requires macOS or Linux.

Identify the target coding agent, its installed agento11y integration, and whether its sessions use the local daemon or go directly to Cloud. Opening the local app does not route a running agent through it. For Codex, ask the user to open /hooks and trust the agento11y hooks after installation.

Use the running app's Security > Guards to inspect the saved enablement, rules path, pack selections, and compilation errors. If the app is stopped, ask before running agento11y local open to start it. Use the displayed rules path rather than assuming ~/.config/agento11y/guards.toml. Read an existing rules file before proposing edits; do not replace it with a template.

Use agento11y doctor --json if installation or routing needs further diagnosis. Explain that doctor probes configured endpoints and obtain approval before those requests.

2. Help the user choose

Use the installed app's pack descriptions and view previews to explain available packs. For blocked and allowed examples, refer to the local guard pack guide. The online guide can describe a different binary version; prefer the installed catalog and dry-run results when they differ. Do not require a network lookup to proceed with the installed catalog.

Before recommending Secret redaction, check whether the target host applies argument rewrites. Copilot CLI applies them; Copilot Chat in VS Code and unidentified Copilot surfaces drop them and run the original arguments. Do not present an offline redaction result as tool-argument protection on those surfaces.

Explain the trade-offs relevant to the user's request:

• Secret redaction rewrites recognized secrets in tool arguments. It can change what the tool receives and break commands that need those values.
• File safety matches .env and .env.*, including .env.example. It does not protect every secret file.
• Git safety allows --force-with-lease; it does not block every history rewrite.
• Destructive commands blocks recursive force deletion even for temporary build output, but does not block every deletion.
• Permissions targets selected root and home spellings, not every directory.
• Disk wipe uses broad command-name patterns that can also block read-only inspection.
• High-risk prompt triage blocks explicit high-impact decisions about people in specified domains. It cannot judge discrimination, explanation quality, legality, or real human oversight, and it only works where the host submits prompt preflight checks.
• PHI-like data egress blocks a narrow set of recognizable outbound tools and shell network commands carrying high-confidence health identifiers. It cannot identify every egress path or determine authorization, permitted purpose, or minimum necessary scope.

State that text matching can miss indirect operations and can block harmless mentions. Unknown tools, unsupported hooks, and scripts that perform dangerous operations internally can escape these checks.

Explain any destination change before asking for approval. Local mode stores full session content locally. With Cloud forwarding, guard payloads can leave the machine even when generation capture is metadata_only. Never enable forwarding just to make local guards work.

Ask which packs to enable or disable, then confirm the exact changes. Do not select every pack by default. Before changing packs in a hand-edited file, offer a backup: pack updates remove TOML comments and formatting.

3. Apply approved changes

Configure bundled packs in the app or custom rules in guards.toml.

Bundled packs

Use Security > Guards to enable guards and toggle only the approved packs. If you cannot operate the app, give the user those steps and wait for confirmation. There is no agento11y guards enable or agento11y guards install command; do not invent one or reconstruct shipped pack regexes.

The switches save immediately: enablement goes in config.env, and pack rules go in the adjacent guards.toml. Turning off the main switch removes all known pack rules when the file can be parsed. Turning it back on does not restore the selection; custom rules remain. Those custom rules still apply to requests from agents that have not picked up the disabled setting. A broken file stays unchanged when the main switch is disabled.

Disabling a pack removes edits to that pack; re-enabling creates the shipped definition. Stop on save or compilation errors rather than claiming the pack is active.

For launcher-based sessions, use agento11y <agent> --local after approval, replacing <agent> with the target launcher name. For hook-based setup, follow setup-coding-agent rather than guessing host configuration. Restart the coding agent after changing enablement or destination, and inspect explicit environment overrides if saved settings do not take effect. Pack-rule edits apply on the next daemon check without a daemon restart.