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.

Guardrails, not a sandbox. Permission gates, protected paths, and checkpoints reduce mistakes — they are not OS-level isolation. An approved command runs with your user's full permissions, and checkpoints can rewind file edits in your working tree but not network calls, pushed commits, published packages, or other external effects. Run untrusted work in a container or VM.

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.