Auto-configure agent hooks during init

[Mr-Lucky]

Summary

• Add agentguard init --agent auto guidance as the required post-install next step.
• Auto-configure supported agent integrations during init/setup:
  • Hermes hook merge into ~/.hermes/config.yaml
  • QClaw plugin install/enablement
  • Codex concrete .codex/agentguard-hook.json
  • OpenClaw/QClaw shared plugin installer path
• Update docs, skill guidance, README, changelog, and postinstall next-step output.
• Fix OpenClaw runtime approvals to use native requireApproval hook responses instead of legacy ask/askReason.

Testing

• npm run build
• npm test -- --test-name-pattern="OpenClaw|runtime policy|approval"
• Manual probe: simulated OpenClaw exec for cat ~/.ssh/id_rsa returns requireApproval with deny-on-timeout.

Type

• Bug fix
• New feature / detection rule
• Refactoring
• Documentation

Testing

• npm run build passes
• npm test passes (32 tests)
• Manually tested the change

Related Issues

Closes #

[github-actions]

AgentGuard PR Review

I found a few concrete issues in the patch that can break installs or weaken the intended security behavior.

1. severity: high — src/installers.ts / setup.sh Hermes hook merge can duplicate or corrupt YAML and miss unrelated top-level hooks

   • The new mergeHermesHooks / inline setup.sh YAML merge logic only removes managed on_session_start, pre_tool_call, and post_tool_call blocks immediately under hooks:. It does not robustly parse YAML indentation or nested structures, so existing user config with comments, additional nested content, or differently indented managed blocks can be duplicated or partially removed. That can break Hermes startup or silently alter hook behavior.
   • Fix: Use a real YAML parser/serializer to update only the managed hook keys, or write a stricter merge routine that preserves the full hooks: mapping and validates the resulting YAML before writing.

2. severity: medium — src/installers.ts / setup.sh hooks_auto_accept is set to false unconditionally

   • The Hermes installer now appends hooks_auto_accept: false even if the user already configured a different value. This can disable an existing explicit approval policy and change runtime security behavior without consent.
   • Fix: Preserve an existing hooks_auto_accept value when present; only set a default when the key is absent.

3. severity: medium — setup.sh and src/installers.ts treat qclaw as an OpenClaw plugin without validating the runtime API

   • The new QClaw install path writes an OpenClaw-style plugin package and config (openclaw.plugin.json, registerOpenClawPlugin(api, ...)) based on the assumption that QClaw exposes the same API. If QClaw’s plugin interface differs, the generated plugin will fail to load and the install will appear successful while protection is broken.
   • Fix: Add an explicit QClaw capability check or use a QClaw-specific plugin entrypoint/manifest if the API differs; fail installation if the runtime does not support the generated format.

4. severity: medium — src/installers.ts installHermes now writes directly to ~/.hermes/config.yaml during init without confirmation/backup

   • The previous flow only generated a template; this patch now mutates the user’s live Hermes config. If the merge logic hits malformed YAML or an unexpected existing config structure, the installer can overwrite the config and disable Hermes hooks entirely.
   • Fix: Validate the merged YAML before writing, and write a backup or temporary file first so failures do not destroy the existing config.

5. severity: low — src/adapters/openclaw-plugin.ts approval mapping may over-block lower-risk approvals

   • Mapping both critical and high risk to severity: 'critical' can cause the host to treat high-risk requests as the most severe class, which may change approval UX or policy routing unexpectedly.
   • Fix: Preserve a distinct severity for high risk if the host supports it, or document/validate that critical is the intended unified classification.