Permissions & hooks

Permission gate

Every mutating tool (write_file, edit_file, run_command) passes a gate before it runs.

Level	Behavior
`ask` (default)	Show the change (with a full diff preview) and ask — y / n / allow for session / always allow / deny with feedback.
`auto`	Run without asking. Catastrophic commands and sensitive paths stay protected.
`readonly`	No mutations at all.

Every write is checkpointed — /undo rewinds it.

Hooks

Run your own commands at the same lifecycle points as Claude Code, configured in ~/.buildwithnexus/settings.json (user) or .buildwithnexus/settings.json (project). Project hooks activate only after you trust the folder, and can deny a tool but never grant one — a hostile repo can't unlock anything.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "run_command",
        "hooks": [{ "type": "command",
                    "command": "echo 'no shell on main' >&2; exit 2" }] }
    ]
  }
}

Events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd. A PreToolUse hook exiting 2 (or returning permissionDecision: "deny") blocks the tool — even under auto.