​

Hooks and automation

​

What hooks are

• rejecting unsafe tool inputs before execution;
• running local checks after selected tool calls;
• adding bounded context when a session or prompt starts;
• recording local audit signals without exposing secrets;
• notifying another local process when a lifecycle event occurs.

​

Supported events

​

Hook locations

• .compass/hooks/ in the project;
• ~/.compass/hooks/ for personal hooks.

.compass/hooks/PreToolUse.yaml
.compass/hooks/PreToolUse/protect-env.yaml
.compass/hooks/UserPromptSubmit/context.md

​

Frontmatter

---
description: Run a local policy check before file-writing tools
enabled: true
tools:
  - write_file
  - edit_file
timeout: 10000
---
node .compass\hook-scripts\check-write-policy.mjs

• description — human-readable purpose;
• enabled — set to false to skip the hook;
• tools — tool-name glob patterns for PreToolUse and PostToolUse;
• timeout — process timeout in milliseconds.

​

A portable PreToolUse example

#!/usr/bin/env node

let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => { input += chunk; });
process.stdin.on('end', () => {
  let event;
  try {
    event = JSON.parse(input);
  } catch {
    console.error('Invalid hook input; blocking by project policy.');
    process.exit(1);
  }

  if (!event || typeof event !== 'object' || Array.isArray(event)) {
    console.error('Invalid hook event; blocking by project policy.');
    process.exit(1);
  }

  const path = String(event.tool_input?.path ?? '');
  if ((event.tool_name === 'write_file' || event.tool_name === 'edit_file') && /(^|[\\/])\.env$/i.test(path)) {
    console.error('Writing .env files is blocked by project policy.');
    process.exit(1);
  }

  process.exit(0);
});

​

Hook input

• session_id;
• transcript_path;
• cwd;
• hook_event_name.

​

Exit status and output

• exit code 0 allows processing to continue;
• a non-zero exit blocks the tool call;
• standard error, then standard output, is used as the block explanation when available.

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Apply the repository's checked-in release policy."
  }
}

​

Enable or disable hooks

nova config set hooks.enabled true
nova config set hooks.enabled false

​

Design guidance

1. Use NOVA.md for guidance and hooks for enforcement. A hook is appropriate only when a deterministic lifecycle check is needed.
2. Fail closed only for high-confidence checks. A noisy PreToolUse hook can block legitimate work.
3. Keep hooks quick. Long network operations make every affected tool call slower and less reliable.
4. Do not print secrets. Hook output can become visible in diagnostics or injected context.
5. Do not duplicate Nova approvals. Hooks can add organisation-specific constraints, but they should not weaken or work around the approval manager.
6. Test scripts outside Nova first. Feed representative JSON through standard input and verify exit codes on the target operating system.
7. Review project hooks after pulling changes. They are executable policy, not passive documentation.

​

Troubleshooting

• Confirm the directory and exact event spelling.
• Confirm the extension is supported, or that an extensionless file starts with a shebang.
• Check that the configured interpreter exists on the current machine.
• Keep paths valid for the target shell; .yaml, .yml, and .md bodies use the platform shell.
• Verify the hook’s tools pattern matches the runtime tool name.
• Reproduce the script with captured test JSON and inspect its exit code.
• Shorten slow work or raise timeout only within Nova’s cap.
• Run nova doctor to check whether hooks are disabled by configuration.

​

What you learned

​

Try it yourself

​

Continue the course

• Previous lesson
• Next lesson