PreToolUse Gate Workflows

Runtime enforcement hooks wired in .claude/settings.json under hooks.PreToolUse. Each fires before the tool executes; exit 2 = block, exit 0 = allow.

Hook Registry

Matcher	Script	Effect
Read	path-blacklist-gate.sh (CLAUDE_TOOL_NAME=Read)	Whitelist-only file access — exit 2 blocks
Bash	path-blacklist-gate.sh (CLAUDE_TOOL_NAME=Bash)	Blocks home-root scans (find/grep/ls) — exit 2 blocks
Write|Edit	delegation-gate.sh	Warns on direct federation/ writes — advisory only (exit 0)

---

Blacklist Gate — Read Path

flowchart TD
    A[PreToolUse: Read] --> B[Extract file_path from stdin JSON]
    B --> C{file_path empty?}
    C -->|yes| D[exit 0 — allow]
    C -->|no| E[Expand ~ to /Users/nnamdi]
    E --> F{Path in whitelist?}

    F -->|hinata-v2/*| D
    F -->|Sandpit/hinata/*| D
    F -->|Sandpit/hinata-sandpit/*| D
    F -->|Library/LaunchAgents/*| D
    F -->|.claude/*| D
    F -->|.cursor/*| D
    F -->|hinata-inbox/ iCloud| D
    F -->|hinata-onedrive/| D
    F -->|/tmp/ or /private/tmp/| D
    F -->|/opt/*| D
    F -->|/etc/*| D
    F -->|no match| G[exit 2 — BLOCK]

    G --> H[stderr: BLACKLIST BLOCK + approved paths list]

    style G fill:#ff4444,color:#fff
    style D fill:#44bb44,color:#fff

---

Blacklist Gate — Bash Command

flowchart TD
    A[PreToolUse: Bash] --> B[Extract command from stdin JSON via python3]
    B --> C{command empty?}
    C -->|yes| D[exit 0 — allow]
    C -->|no| E{find targeting home root?}

    E -->|"find /Users/nnamdi/ ..."| F[exit 2 — BLOCK home root scan]
    E -->|no| G{grep targeting home root?}

    G -->|"grep ... /Users/nnamdi/"| H[exit 2 — BLOCK home root grep]
    G -->|no| I{cat/head/tail/ls on home root?}

    I -->|"ls /Users/nnamdi/"| J[exit 2 — BLOCK home root listing]
    I -->|no| D[exit 0 — allow]

    F --> K[stderr: scope find to permitted path]
    H --> L[stderr: scope grep to permitted path]
    J --> M[stderr: scope to permitted path]

    style F fill:#ff4444,color:#fff
    style H fill:#ff4444,color:#fff
    style J fill:#ff4444,color:#fff
    style D fill:#44bb44,color:#fff

Permitted search paths for subagent prompts:

• /Users/nnamdi/hinata-v2/
• /Users/nnamdi/Sandpit/hinata/
• /Users/nnamdi/Sandpit/hinata-sandpit/
• ~/Library/CloudStorage/OneDrive-Personal/hinata/hinata-inbox/

---

Delegation Gate — Write/Edit

flowchart TD
    A[PreToolUse: Write or Edit] --> B[Extract file_path from stdin JSON]
    B --> C{Path contains /federation/?}
    C -->|no| D[exit 0 — allow silently]
    C -->|yes| E[stderr: DELEGATION WARNING]
    E --> F[exit 0 — allow with warning]

    style D fill:#44bb44,color:#fff
    style F fill:#ffaa00,color:#000

The delegation gate is advisory — it never blocks. It reminds that direct writes to federation/ should be delegated to the owning commander when touching >3 files or >2 doctrines.

---

Autonomy Posture (replaces dont-halt)

flowchart TD
    A[acceptEdits permanent posture] --> B{Work in queue?}
    B -->|yes| C[Fan immediately — parallel-max]
    C --> D{Hit a blocker?}
    D -->|no| E[Continue fanning]
    D -->|yes| F{Canonical bottleneck?}

    F -->|source-of-truth unparseable| G[HALT — surface to Michael]
    F -->|filesystem unwriteable| G
    F -->|context exhausted| G
    F -->|unauthorised outward action| G
    F -->|none of the above| H[Not a true bottleneck — keep going]

    B -->|no| I[Clean stop]

    H --> E

    style G fill:#ff4444,color:#fff
    style E fill:#44bb44,color:#fff
    style I fill:#888888,color:#fff

---

Input Format

All PreToolUse hooks receive JSON on stdin:

{
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/Users/nnamdi/some/path.md"
  }
}

For Bash, the command field is inside tool_input:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "find /Users/nnamdi/hinata-v2/ -name '*.md'"
  }
}

---

Scripts: Sandpit/hinata/scripts/path-blacklist-gate.sh · Sandpit/hinata/scripts/delegation-gate.shConfig: .claude/settings.json → hooks.PreToolUseRelated: reference_approved-file-paths · naming-conventions § Access Control Propagation