Harness hooks

What hooks do

Guard adds its own entries to each harness's hook configuration. The harness then asks Guard about prompts, tool calls and tool output. We monitor agents, not developers.

• Tool calls. Reads of credential files and directories, credential commands (such as security find-generic-password) and MCP tool arguments that name credential paths are denied.
• Risky actions. Persistence writes, guardrail lowering, destructive commands, droppers, risky package installs, encoded secrets and credential writes are blocked, confirmed with the user or reported. See risky actions.
• Tool output. Critical and high secrets in output are replaced or reported, where the harness allows it.
• Prompts. Checked only when your organization turns on human-to-AI sharing detection (privacy.human_ai_sharing) in its signed catalog. Without it, a prompt goes through unchanged and Guard records only that a prompt was submitted. See the privacy statement.
• MCP tool access. When the signed catalog has tool access rules, MCP calls are checked against them. See MCP tools.
• Sessions. Calls are linked into agent sessions, so chains such as untrusted input, then a credential read, then an upload can be caught. Output from one MCP server followed by a sending, writing or deleting call on another is recorded too (cross_server_mcp_flow, in detect mode by default). A call without a session ID gets no session rules.

Messages name secret types and rules, never secret values. Hooks also deny any tool call that reads or writes the Guard home, so an agent can't grant itself an exception.

Warning: Hooks are voluntary checks, not endpoint-wide enforcement. A user can edit or remove them, and in several harnesses a hook that fails or times out lets the action proceed. Guard's endpoint sensor reports the file opens and process launches that hooks miss, including agent CLIs started with a bypass flag or a variable that moves their configuration directory, only after the fact, and the native macOS sensor can't yet run on customer Macs (see Install).

Install

guard hooks install all
guard hooks status

• all selects known harness configuration locations and supported official extension manifests. Incomplete discovery can skip automatic setup. Name a supported harness to choose explicitly: guard hooks install claude_code cursor.
• Entries run the guard binary you ran install with, by absolute path. Use --binary PATH for another one.
• Catalog flags given before hooks are added to every entry: guard --catalog PATH --catalog-key KEYS hooks install all.
• Your other hooks are kept. The first time Guard changes a file, it saves the original with a .before-runeward-guard suffix.
• Codex asks you to trust new hooks: run /hooks in Codex after installing.
• guard hooks uninstall all removes Guard's entries only.

status reports each harness as one of:

guard doctor and the Guard Cloud health report show the same states, without paths.

Repair

Harness updates and settings editors sometimes drop Guard's entries. Repair puts them back:

guard hooks repair all

Repair only touches harnesses in the partial or broken state. A harness with no Guard entries is left alone, because removing them all is how you turn Guard off for it. The last 20 repairs show in guard doctor as hook_repairs.

Scheduled repair is opt-in:

• macOS: guard setup-launch-agent --binary /path/to/guard --repair-hooks writes the com.runeward.guard.hooks-repair launch agent. It runs at login and hourly; --repair-interval SECONDS sets 300 to 86400. Load it with launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.runeward.guard.hooks-repair.plist.
• Linux: the packages ship a user timer, off by default. Each user enables it with systemctl --user enable --now runeward-guard-hooks-repair.timer.
• Windows: install.ps1 -RepairHooks or the MSI's REPAIRHOOKS=1 registers a scheduled task that runs guard.exe hooks repair all as each user, two minutes after logon and then hourly. Administrators can also run guard hooks repair-task register, remove or status. It restores entries a user removed on purpose (to opt a harness out, remove the task) and can overwrite an edit saved while it runs. Windows hook install and repair aren't yet qualified.

A signed catalog can also repair JSON hooks automatically with a hooks_repair remediation playbook. Kimi TOML needs explicit repair; it is excluded from JSON-snapshot remediation.

Exceptions

Exceptions let named paths, MCP servers or commands through specific checks, such as test fixtures with fake keys. They come from:

• hook_exceptions in the signed catalog, which Guard Cloud can send to every enrolled device;
• policy.json in the Guard home (~/.runeward-guard by default), for one user. A catalog can turn these off with "local_hook_exceptions": false.

{
  "version": 1,
  "exceptions": [
    {
      "paths": ["~/src/payments/tests/fixtures/"],
      "secrets": ["stripe_key", "jwt"],
      "reason": "Fake keys used by the payments test suite"
    },
    {
      "mcp_servers": ["sentry"],
      "commands": [["npm", "test"], ["cargo", "test"]],
      "secrets": ["github_token"],
      "reason": "Test suites and error reports print fake tokens",
      "expires": "2026-12-31T00:00:00Z"
    }
  ]
}

Each exception needs at least one of paths, mcp_servers and commands. Exceptions never apply to prompts.

Validate the file with guard policy check. If it's invalid, hooks ignore it and every check still applies. It must be owned by you or root and not writable by others.

Risky actions

Each rule in the catalog has a decision:

• block denies the call.
• ask asks the user to confirm, where the harness can. Elsewhere Guard warns instead.
• warn lets the call run and tells the user, and in some harnesses the agent.

A rule in detect mode is recorded but not applied, so a new rule can be measured before it enforces.

Look-alike and not-on-registry findings send package names to Guard Cloud only when they match public data: a look-alike of a name on the built-in public reference list, or a name a public registry snapshot or lookup showed missing. A name your policy added to the reference list, or one another registry or a private registry may serve, stays on the device.

Destructive and persistence command rules can be limited to agents in a given state: agents with a named MCP server, skill or plugin, agents using a component nobody has reviewed, or agents whose owner is unknown or inactive. When Guard can't establish that state, the rule's on_unknown decision applies, and the finding says why.

Hooks don't see commands that programs run on their own, such as a package's install script.

What each harness supports

Prompt checks in this table apply with the human-to-AI sharing opt-in on.

Where entries go

• Claude Code: to cover one project only, add the same entries to its .claude/settings.json by hand.
• Cline: Guard won't replace a script it didn't write. On Linux, if xdg-user-dir DOCUMENTS isn't ~/Documents, copy the scripts there. For one project, use .clinerules/hooks/.
• Windsurf: organizations can put the same entries in the system-level file (/Library/Application Support/Windsurf/hooks.json on macOS, /etc/windsurf/hooks.json on Linux), which users can't edit. guard hooks manages only the user-level file.
• VS Code: check the session target and the host that executes the agent. An extension manifest or a default-path status is not proof that hooks ran. Remote SSH, WSL, containers, custom profiles and extension directories need their own setup and qualification. Continue remains observe-only; other extensions do not inherit Copilot's adapter.
• Kimi and Qwen: a custom KIMI_CODE_HOME or QWEN_HOME that disagrees with the catalog's paths is refused rather than silently installing into the default home. These native adapters do not supply Guard's exact-call Cloud approval, quarantine or Linux managed-endpoint routing. Status checks configuration, not delivery; neither vendor provides a fail-closed guarantee.

Hook checks inspect delivered tool actions outside model inference. Selecting DeepSeek, Kimi, Qwen, a local runtime or another hosted backend does not by itself qualify a client, model or extension. The new native-client tests use synthetic payloads and contact no model provider.

Test with synthetic secrets only, never real credentials.