Detect the actual provider and installed version. Do not infer it from a similarly named configuration file. Select project or user scope explicitly before editing.
Read the matching current provider reference below and open its official lifecycle/schema documentation. Preserve its exact event names, matcher syntax, input/output, ordering, blocking, timeout, trust, and reload rules.
Review every invoked executable and argument. Check shell quoting, paths with spaces, inherited secrets, network and filesystem effects, destructive operations, untrusted input, recursion, concurrency, ordering, and timeout. Prefer direct executable/argument forms when the provider supports them.
Back up the exact existing configuration. Merge only the requested hook; preserve unrelated provider settings and higher-precedence managed policy.
Parse the resulting configuration with the provider's schema or parser. Trigger one harmless matching event in an isolated project. Verify received input, stdout JSON, stderr, exit behavior, timeout, and expected side effect.
Report the provider, version, scope, changed file, event, matcher, command, trust/approval step, observed test, and rollback. Restore the backup if the harmless test fails.

Provider routes

Do not normalize configurations between providers. VS Code can read some Claude-format files but currently differs in matcher behavior; a file accepted by both does not imply identical execution.

RED / GREEN

Deciding condition: install a project-local observer for one documented event without granting it additional authority.

RED — DO NOT: assume one universal hook

Put a post-tool hook with the same event and JSON in every agent.

The event spelling, nesting, command form, scope, trust, and exit semantics are provider-specific.

GREEN — DO: validate the selected provider

Provider/version -> scope -> official event/schema -> command security review
-> merge -> parse -> harmless trigger -> rollback proof

Use the harmless handler, provider fixture payloads, and matching configuration asset for local validation. The handler only parses one JSON object and returns {}; it neither logs secrets nor writes files.

Validation

Run python3 scripts/test_assets.py. A JSON parse and direct handler test do not replace a real harness smoke test. Report unavailable provider binaries, authentication, cloud execution, UI trust review, or preview-host checks rather than claiming them from configuration parsing.

maintain-agent-hooks

Maintain Agent Hooks