What We Tried & Why Each Failed
Attempt 1 — Global deny in settings.json:
json{
  "permissions": {
    "deny": ["Write", "Edit", "Bash"]
  }
}
Result: Blocked main agent AND all subagents equally. No agent could write anything. Project completely broken.

Attempt 2 — Path-specific deny in settings.json:
json{
  "permissions": {
    "deny": ["Write(src/**)","Edit(src/**)"]
  }
}
Result: Blocked subagents too. Project-level deny overrides subagent tools: declarations. All 5 subagents failed — gas-script-coder, gas-sheets-builder, gas-code-review, git-agent, cmd-skills-hooks-builder.

Attempt 3 — Subagent tools: field in .md file:
yaml---
name: gas-script-coder
tools: Read, Write, Glob
---
Result: tools: field is overridden by project-level settings.json deny. Subagent declared Write but still could not write. Confirmed by testing all 5 subagents.

Attempt 4 — Separate settings.json per subagent folder:
agents/gas-script-coder/.claude/settings.json → allow Write
Result: These folder-level settings apply only to standalone Claude Code processes — NOT to subagents invoked via Agent() tool inside the main session. Completely ignored.

Attempt 5 — PreToolUse hooks:
Tried to intercept tool calls and check caller identity.
Result: Hook cannot identify whether the caller is main agent or subagent. No caller identity is exposed in hook context. Cannot differentiate.

Root Cause
<br>
Claude Code's permission system is session-wide, not agent-wide.
When a subagent is invoked via Agent() tool:

It loads its .md definition from .claude/agents/
It runs inside the SAME session
It INHERITS the parent session's permission rules
Project-level deny rules CANNOT be overridden by subagent tools: declarations
There is NO way to say "deny main agent only, allow subagent only" for the same path
---
---
# Hook System — src-write-guard Investigation Report

**Last Updated:** 2026-04-30
**Status:** 🔴 ALL APPROACHES FAILED — Debug logging needed to find actual PreToolUse stdin structure

---

## CORE OBJECTIVE

| Actor | src/ Access |
|-------|------------|
| Main agent (the AI talking to you) | BLOCKED — cannot write to src/ directly |
| Any sub-agent (gas-script-coder, gas-sheets-builder, git-flow-expert, etc.) | ALLOWED — can write to src/ |

**Rule:** Main agent must delegate all src/ writes to sub-agents. Cannot bypass via retry or Bash.

---

## SUMMARY — All Approaches (Quick View)

| | Approach 1 | Approach 2 | Approach 3 | Approach 4 |
|---|---|---|---|---|
| Recorder event | `UserPromptSubmit` | `SubagentStart/Stop` | `SubagentStart/Stop` + `SessionEnd` | NONE — no state file |
| Guard event | `Edit\|Write` | `Edit\|Write` | `Edit\|Write` + `Bash` | `Edit\|Write\|Bash` |
| State file logic | exact type match | exact type match | empty = block, non-empty = allow | **NO STATE FILE — tried agent_type from stdin** |
| Bash bypass fixed? | No | No | YES | YES |
| Stale state fixed? | No | No | YES | YES |
| Works for approved agents? | No | No | YES | NO — tested, FAILED |
| **Status** | 🔴 FAILED | 🔴 FAILED | 🟡 READY (not tested) | 🔴 **TESTED — FAILED** |

### Why Each Failed

- **Approach 1:** UserPromptSubmit fires for user messages, not agent messages — state always says "main-agent"
- **Approach 2:** SubagentStop fires BEFORE sub-agent completes its actual write (after user confirmation) — state cleared too early, even approved agents blocked
- **Approach 3:** Uses state file approach with improved logic — still needs testing but more complex than Approach 4

### Approach 4 — TESTED AND FAILED

**Web research claimed:**
- PreToolUse stdin includes `agent_type` for sub-agents
- PreToolUse stdin does NOT have `agent_type` for main agent (field is absent)

**Actual test result: 🔴 FAILED**

**TEST RESULT: 🔴 FAILED — agent_type is NOT present in PreToolUse stdin for sub-agents**

### Lessons from Approach 4 Failure

1. Web research was incorrect — `agent_type` does NOT appear in PreToolUse stdin for sub-agents
2. The PreToolUse JSON structure must be different from what was researched
3. Need to investigate actual PreToolUse stdin structure with debugging

### Next Steps Needed

1. Add debug logging to capture actual PreToolUse stdin structure
2. Find which field(s) actually distinguish main agent from sub-agents
3. Design Approach 5 based on actual observed behavior

---

## FILES TO CHANGE FOR APPROACH 4 (Quick Reference)

| File | Change |
|------|--------|
| `D:\...\src-write-guard.sh` | Replace with APPROACH 4 CANDIDATE script (read agent_type directly from stdin — no state file) |
| `D:\...\settings.json` | Add `src-write-guard.sh` to Bash block + REMOVE `src-agent-recorder.sh` from SubagentStart/SubagentStop (no longer needed) |
| `D:\...\src-agent-recorder.sh` | No longer needed for this purpose — can delete or repurpose |

---

## ONBOARDING FOR NEXT SESSION

If you are continuing this work in a new session, **start here**:

1. Read this report: `.IDE_Plans/hook-src-write-guard-investigation-report.md`
2. Check current state of `settings.json` and `src-write-guard.sh`
3. **Goal:** Main agent blocked from src/, all sub-agents allowed
4. **Do NOT repeat Approach 1** — proven wrong
5. **Do NOT repeat Approach 2** — proven broken
6. **Do NOT repeat Approach 3** — more complex than needed, Approach 4 is simpler but FAILED
7. **Do NOT rely on web research for PreToolUse stdin fields** — research was incorrect
8. **NEXT STEP:** Add debug logging to capture actual PreToolUse stdin structure and find which field distinguishes main vs sub-agent
9. **Design Approach 5** based on actual observed behavior

---

## REMAINING OPEN QUESTIONS

| # | Question | Why it matters | Status |
|---|----------|---------------|--------|
| Q1 | Does PreToolUse stdin have `agent_type`? | **ANSWERED: NO** — Web research was incorrect | 🔴 CONFIRMED ABSENT |
| Q2 | What field(s) in PreToolUse distinguish main vs sub-agent? | **UNKNOWN** — Need debug logging | 🟡 PENDING INVESTIGATION |
| Q3 | Can we identify sub-agents via some other field? | Possibly via `tool`, `prompt`, or other fields | 🟡 PENDING INVESTIGATION |
| Q4 | Debug approach needed | Need to capture actual PreToolUse stdin | 🟡 PENDING — add debug logging |

---

## HISTORY

| Date/Time | Event | Outcome |
|-----------|-------|---------|
| 2026-04-27 AM | Approach 1 (UserPromptSubmit) attempted | 🔴 FAILED — wrong event type |
| 2026-04-27 PM | Approach 2 (SubagentStart/Stop) applied | 🔴 FAILED — SubagentStop clears state before sub-agent writes |
| 2026-04-27 PM | gas-script-coder delegated and blocked | Confirmed approach 2 is fully broken |
| 2026-04-27 PM | Objective changed — allow all sub-agents | New approach needed |
| 2026-04-27 PM | Web research: PreToolUse stdin structure | ✅ FOUND: agent_type is in stdin for sub-agents, absent for main agent |
| 2026-04-27 PM | Approach 4 (direct stdin read) designed | 🟢 SIMPLEST — no state file needed |
| 2026-04-30 | Approach 4 tested | 🔴 FAILED — agent_type NOT in PreToolUse stdin (web research was incorrect) |

---

---

## DETAILED APPROACHES

---

## APPROACH 1 — UserPromptSubmit Recorder 🔴 FAILED

**Intent:** When user types message, record agent_type to state file. PreToolUse reads state file to know who is calling.

**Files changed:** settings.json (UserPromptSubmit hook), src-agent-recorder.sh

**Result:** FAILED — Completely broken

### Why It Failed
- `UserPromptSubmit` fires when USER types a message — not when an agent runs
- The stdin for UserPromptSubmit does NOT contain the running agent's type
- `agent_type` was always null or "main-agent" even when a sub-agent like `gas-script-coder` was running
- State file always said "main-agent" regardless of which agent actually called Write/Edit
- ALL agents (including approved ones) got blocked

### Exact Error Observed

src-write-guard.sh: [HOOK BLOCKED] Only gas-script-coder and gas-script-coder agents can write to src/ folder. Your agent: 'main-agent' is not authorized.


**Lesson learned:** UserPromptSubmit is for user input events, NOT agent execution events. Never use it to track which agent is running.

---

## APPROACH 2 — SubagentStart/SubagentStop Recorder 🔴 FAILED

**Intent:** When a sub-agent starts, record its type to state file. When it stops, clear state. PreToolUse reads state to know who is calling.

**Files changed:** settings.json (SubagentStart/SubagentStop hooks), src-agent-recorder.sh (updated)

**Result:** FAILED — Completely broken — even approved agents cannot write

### What Happened

1. User asked main agent to create src/02_Triggers/readme.md
2. Main agent was blocked (as expected)

3. User delegated to gas-script-coder sub-agent
4. gas-script-coder tried to write src/02_Triggers/readme.md
5. gas-script-coder was ALSO BLOCKED ← NEW FINDING


### The Timing Issue (Root Cause)

Main agent spawns gas-script-coder
  → SubagentStart fires → state = "gas-script-coder" ✓

gas-script-coder asks user: "Should I create readme.md?"
  → User says "yes"

  → SubagentStop fires at this point (gas-script-coder finished its "turn")
  → state file cleared ✗

gas-script-coder actually writes the file
  → PreToolUse fires → reads state file → EMPTY → BLOCKED ✗


**SubagentStop fires BEFORE the sub-agent completes its actual work** — because asking for confirmation is treated as the end of that turn.

**Lesson learned:** SubagentStop fires when the sub-agent asks for confirmation, NOT when it completes its task after confirmation.

---

## APPROACH 3 — New Logic: Empty State = Block, Non-Empty = Allow 🟡 READY FOR TESTING (BUT APPROACH 4 IS SIMPLER)

**Intent:** Remove exact-type checking. Use simple logic: state file has content = sub-agent running = ALLOW. State file is empty = main agent = BLOCK.

**Files to change:** settings.json, src-write-guard.sh

**Result:** NOT YET TESTED — More complex than Approach 4

### What Needs to Change

1. **Add `src-write-guard.sh` to Bash block** — closes the retry bypass gap
2. **Add `SessionEnd` hook** — clears state file so no stale state across sessions
3. **Simplify `src-write-guard.sh` logic** — empty state = block, non-empty = allow

### Why Approach 3 is now OBSOLETE

Approach 4 (below) achieves the same goal without ANY state file — just read `agent_type` directly from PreToolUse stdin. Simpler, fewer failure points.

---

## APPROACH 4 — Direct agent_type Read from PreToolUse stdin 🔴 TESTED — FAILED

**Intent:** No state file needed. PreToolUse stdin already has `agent_type` for sub-agents but NOT for main agent. Use this directly to distinguish main agent from sub-agents.

**Files to change:** settings.json, src-write-guard.sh

**Result:** 🔴 TESTED AND FAILED — `agent_type` does NOT exist in PreToolUse stdin for any agent type

### What Was Tested

1. Deployed Approach 4 script to `.claude/hooks/enforcement/src-write-guard.sh`
2. Tested with gas-script-coder sub-agent
3. **Sub-agent was BLOCKED** — `agent_type` field was absent (empty) in PreToolUse stdin

### Why It Failed

Web research was incorrect. The `agent_type` field does NOT appear in PreToolUse stdin for any agent type (main or sub-agent). The actual PreToolUse JSON structure is different from what was documented online.

### How It Works


PreToolUse fires (for Write, Edit, or Bash to src/)
  → src-write-guard.sh reads stdin JSON
  → Check if agent_type field is present
  → If ABSENT → main agent → BLOCK
  → If PRESENT → sub-agent → check if in approved list → ALLOW or BLOCK


### Why This Works

From Claude Code hooks documentation (verified via web search):
- Sub-agents: PreToolUse stdin includes `"agent_type": "gas-script-coder"` (or whatever type)
- Main agent: PreToolUse stdin does NOT have agent_type field at all (absent, not "main-agent")
- So: `agent_type` absent = main agent = BLOCK, `agent_type` present = sub-agent = check approval

### Behavior Matrix

| Agent | `agent_type` in PreToolUse stdin | Action |
|-------|--------------------------------|--------|
| Main agent | **ABSENT** | BLOCK |
| gas-script-coder | YES — "gas-script-coder" | ALLOW |
| gas-sheets-builder | YES — "gas-sheets-builder" | ALLOW |
| git-flow-expert | YES — "git-flow-expert" | BLOCK (not in approved list) |
| gas-error-handler | YES — "gas-error-handler" | BLOCK (not in approved list) |

---

### CODE CANDIDATE — Approach 4 (BEST)

**File: src-write-guard.sh (APPROACH 4 — NO STATE FILE NEEDED)**

#!/bin/bash
# src-write-guard.sh
# PreToolUse hook: restricts src/ folder writes to only approved sub-agents
#
# Logic (NO state file needed):
#   - agent_type IN stdin -> sub-agent is running -> use it directly
#   - agent_type NOT in stdin -> main agent -> BLOCK
#   - Only gas-script-coder and gas-sheets-builder are allowed
#
# Runs on: Edit, Write, AND Bash (catches retry bypass)

INPUT=$(cat)
if [ -z "$INPUT" ]; then
    exit 0
fi

# Extract file_path from PreToolUse JSON
TOOL_INPUT_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ -z "$TOOL_INPUT_PATH" ] || [ "$TOOL_INPUT_PATH" = "empty" ] || [ "$TOOL_INPUT_PATH" = "null" ]; then
    exit 0
fi

# Normalize path: convert Windows backslash to forward slash
NORMALIZED_PATH=$(echo "$TOOL_INPUT_PATH" | sed 's/\\/\//g')

# Check if path contains /src/
if echo "$NORMALIZED_PATH" | grep -q "/src/"; then
    # Extract agent_type from stdin — present ONLY for sub-agents
    AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // empty')

    if [ -z "$AGENT_TYPE" ] || [ "$AGENT_TYPE" = "empty" ] || [ "$AGENT_TYPE" = "null" ]; then
        # No agent_type -> main agent (not a sub-agent) -> BLOCK
        echo "[HOOK BLOCKED] Main agent cannot write to src/ folder." >&2
        echo "Only gas-script-coder and gas-sheets-builder sub-agents are allowed." >&2
        exit 2
    fi

    # agent_type is present — check if approved
    if [ "$AGENT_TYPE" = "gas-sheets-builder" ] || [ "$AGENT_TYPE" = "gas-script-coder" ]; then
        exit 0
    else
        echo "[HOOK BLOCKED] Only gas-script-coder and gas-sheets-builder agents can write to src/ folder." >&2
        echo "Your agent: '$AGENT_TYPE' is not authorized." >&2
        exit 2
    fi
fi

exit 0


**File: settings.json (APPROACH 4 CANDIDATE)**

"UserPromptSubmit": [],
"PreToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "command": "bash \".../gs-file-restriction-enforcer.sh\"" },
      { "command": "bash \".../unit-test-checker.sh\"" },
      { "command": "bash \".../plan-validator.sh\"" },
      { "command": "bash \".../src-write-guard.sh\"" }
    ]
  },
  {
    "matcher": "Agent|Bash|Write|Edit|NotebookEdit|Delete|Move|Copy",
    "hooks": [
      { "command": "bash \".../subagent-delegation-enforcer.sh\"" },
      { "command": "bash \".../global-rules-enforcer.sh\"" },
      { "command": "bash \".../src-write-guard.sh\"" }
      // src-write-guard now runs for Bash too — closes retry bypass
    ]
  }
],
// REMOVE src-agent-recorder.sh from SubagentStart/SubagentStop (no longer needed)
// NO SessionEnd hook needed (no state file to clear)


### What to Remove from settings.json

Remove these from SubagentStart and SubagentStop (no longer needed):

- src-agent-recorder.sh
- src-agent-recorder.sh --clear


---

## SUMMARY TABLE — All Approaches

| | Approach 1 | Approach 2 | Approach 3 | Approach 4 |
|---|---|---|---|---|
| Uses state file | Yes | Yes | Yes | **NO** |
| Needs SubagentStart/Stop | Yes | Yes | Yes | **NO** |
| Reads agent_type from stdin | No | No | No | **YES (but field doesn't exist)** |
| Bash bypass fixed | No | No | Yes | **YES** |
| Stale state issue | Yes | Yes | Yes (SessionEnd fixes) | **NO** |
| Complexity | Medium | High | High | **LOW** |
| Status | 🔴 FAILED | 🔴 FAILED | 🟡 Not tested | 🔴 **TESTED FAILED** |

---

## FILES TO CHANGE FOR APPROACH 4

| File | Action |
|------|--------|
| `src-write-guard.sh` | Replace with Approach 4 candidate script above |
| `settings.json` | 1. Add `src-write-guard.sh` to `Agent\|Bash\|Write\|Edit\|...` block |
| `settings.json` | 2. Remove `src-agent-recorder.sh` from SubagentStart |
| `settings.json` | 3. Remove `src-agent-recorder.sh --clear` from SubagentStop |
| `src-agent-recorder.sh` | Delete or repurpose (no longer needed for this hook) |

---

src-write-guard.sh: [HOOK BLOCKED] Only gas-script-coder and gas-script-coder agents can write to src/ folder. Your agent: 'main-agent' is not authorized.

---

1. User asked main agent to create src/02_Triggers/readme.md
2. Main agent was blocked (as expected)

3. User delegated to gas-script-coder sub-agent
4. gas-script-coder tried to write src/02_Triggers/readme.md
5. gas-script-coder was ALSO BLOCKED ← NEW FINDING

---

Main agent spawns gas-script-coder
  → SubagentStart fires → state = "gas-script-coder" ✓

gas-script-coder asks user: "Should I create readme.md?"
  → User says "yes"

  → SubagentStop fires at this point (gas-script-coder finished its "turn")
  → state file cleared ✗

gas-script-coder actually writes the file
  → PreToolUse fires → reads state file → EMPTY → BLOCKED ✗

---

PreToolUse fires (for Write, Edit, or Bash to src/)
  → src-write-guard.sh reads stdin JSON
  → Check if agent_type field is present
  → If ABSENT → main agent → BLOCK
  → If PRESENT → sub-agent → check if in approved list → ALLOW or BLOCK

---

#!/bin/bash
# src-write-guard.sh
# PreToolUse hook: restricts src/ folder writes to only approved sub-agents
#
# Logic (NO state file needed):
#   - agent_type IN stdin -> sub-agent is running -> use it directly
#   - agent_type NOT in stdin -> main agent -> BLOCK
#   - Only gas-script-coder and gas-sheets-builder are allowed
#
# Runs on: Edit, Write, AND Bash (catches retry bypass)

INPUT=$(cat)
if [ -z "$INPUT" ]; then
    exit 0
fi

# Extract file_path from PreToolUse JSON
TOOL_INPUT_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ -z "$TOOL_INPUT_PATH" ] || [ "$TOOL_INPUT_PATH" = "empty" ] || [ "$TOOL_INPUT_PATH" = "null" ]; then
    exit 0
fi

# Normalize path: convert Windows backslash to forward slash
NORMALIZED_PATH=$(echo "$TOOL_INPUT_PATH" | sed 's/\\/\//g')

# Check if path contains /src/
if echo "$NORMALIZED_PATH" | grep -q "/src/"; then
    # Extract agent_type from stdin — present ONLY for sub-agents
    AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // empty')

    if [ -z "$AGENT_TYPE" ] || [ "$AGENT_TYPE" = "empty" ] || [ "$AGENT_TYPE" = "null" ]; then
        # No agent_type -> main agent (not a sub-agent) -> BLOCK
        echo "[HOOK BLOCKED] Main agent cannot write to src/ folder." >&2
        echo "Only gas-script-coder and gas-sheets-builder sub-agents are allowed." >&2
        exit 2
    fi

    # agent_type is present — check if approved
    if [ "$AGENT_TYPE" = "gas-sheets-builder" ] || [ "$AGENT_TYPE" = "gas-script-coder" ]; then
        exit 0
    else
        echo "[HOOK BLOCKED] Only gas-script-coder and gas-sheets-builder agents can write to src/ folder." >&2
        echo "Your agent: '$AGENT_TYPE' is not authorized." >&2
        exit 2
    fi
fi

exit 0

---

"UserPromptSubmit": [],
"PreToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "command": "bash \".../gs-file-restriction-enforcer.sh\"" },
      { "command": "bash \".../unit-test-checker.sh\"" },
      { "command": "bash \".../plan-validator.sh\"" },
      { "command": "bash \".../src-write-guard.sh\"" }
    ]
  },
  {
    "matcher": "Agent|Bash|Write|Edit|NotebookEdit|Delete|Move|Copy",
    "hooks": [
      { "command": "bash \".../subagent-delegation-enforcer.sh\"" },
      { "command": "bash \".../global-rules-enforcer.sh\"" },
      { "command": "bash \".../src-write-guard.sh\"" }
      // src-write-guard now runs for Bash too — closes retry bypass
    ]
  }
],
// REMOVE src-agent-recorder.sh from SubagentStart/SubagentStop (no longer needed)
// NO SessionEnd hook needed (no state file to clear)

---

- src-agent-recorder.sh
- src-agent-recorder.sh --clear