---
name: native-hook-authoring
description: Create, revise, validate, or troubleshoot trusted personal pi-native-hooks diagnostic and verification policies and ast-grep fixtures. Use when adding focused post-mutation policies without duplicating lifecycle, process execution, state, or delivery logic.
compatibility: pi-native-hooks on Node >=22.19
---

# Native hook authoring

1. Read [contracts](references/contracts.md). Import policy contracts with `import type` only.
2. Keep evaluators pure. Request analyzer keys and consume immutable snapshots; never spawn analyzers, linters, LSPs, or shell processes from a policy.
3. Add or revise a fixture under the package's `tests/fixtures/personal-config`, not the live personal root.
4. For syntax steering, create warning/info/hint ast-grep rules with language-specific IDs and a rationale-bearing `ast-grep-ignore` example.
5. Run the focused fixture, `npm run typecheck`, and `npm test` as described in [testing](references/testing.md).
6. Preview personal installation with `/hooks-init --dry-run`. Never write `~/.config/pi-native-hooks` without explicit interactive authorization. Existing files must not be overwritten.

Personal modules are trusted arbitrary code with Pi's authority. Validation is not sandboxing. Use Node's erasable TypeScript subset only.