hooks-authoring

$hooks-authoring - Hook Authoring Workflow

Purpose: create or review AgentOps runtime hooks with portable behavior,

clear matchers, deterministic tests, and CI-compatible validation.

Execute this workflow. Do not only describe it.

Route

Use this skill when work touches hooks/hooks.json, hooks/*.sh, lib/hook-helpers.sh, hook schemas, or tests that exercise runtime hooks.

Workflow

1. Locate (or create) your hook surface.
2. Runtime manifest: your own hooks/hooks.json (the AgentOps default ships none)
3. Hook scripts: your own *.sh
4. Schema to validate against: schemas/hooks-manifest.v1.schema.json
5. Select the lifecycle event and matcher.
6. For event behavior, read [references/event-taxonomy.md](references/event-taxonomy.md).
7. For matcher shape, read [references/matcher-patterns.md](references/matcher-patterns.md).
8. Define the contract before editing.
9. Inputs consumed from hook JSON.
10. Output schema and exit-code behavior.
11. Fail-open vs fail-closed decision.
12. Kill switch, timeout, and portability constraints.
13. Implement narrowly.
14. Use set -euo pipefail in shell hooks.
15. Resolve paths from the manifest/plugin root rather than the caller CWD.
16. Avoid eval, backticks, unquoted variables, and implicit globbing.
17. Keep hook output to the portable subset both Claude and Codex accept

(avoid hookSpecificOutput.updatedInput, which Codex silently drops).

1. Wire the manifest.
2. Use the narrowest matcher that covers the target tool or lifecycle.
3. Add explicit timeout values.
4. Preserve existing ordering unless the behavior depends on ordering.
5. Test directly with your own fixtures.
6. For fixture patterns, read [references/test-harness.md](references/test-harness.md).
7. Run the hook with representative JSON fixtures and assert the output shape

and exit codes yourself.

• Run ShellCheck for touched shell files.
• Record evidence.
• Note touched files, fixture commands, gate output, and any intentional

fail-open/fail-closed choices.

Guardrails

• Do not broaden a matcher to hide a missing case; add a second hook entry.
• Do not rely on hook output fields that Codex ignores.
• Do not store session secrets, transcripts, or local runtime state in tracked

hook fixtures.

• Keep hook authoring documentation separate from active guard behavior. For

edit-scope enforcement, use $scope.

References

• [references/event-taxonomy.md](references/event-taxonomy.md)
• [references/matcher-patterns.md](references/matcher-patterns.md)
• [references/test-harness.md](references/test-harness.md)