custodex 1.0.0

package/hooks/hook.sh

@@ -0,0 +1,724 @@
+#!/usr/bin/env bash
+# ============================================================
+# Custodex Universal Governance Hook
+# Version: 1.0.0
+#
+# Supported IDEs (detected in priority order):
+#   1. Gemini CLI   — GEMINI_SESSION_ID env var is set
+#   2. Cursor       — input JSON has `conversation_id` but no `session_id`
+#   3. Claude Code  — input JSON has `session_id` (default fallback)
+#
+# Configuration (in priority order):
+#   ~/.custodex/config.json  →  { apiKey, baseUrl }
+#   Env vars                 →  CUSTODEX_API_KEY, CUSTODEX_BASE_URL
+#
+# Deny response formats per IDE:
+#   Claude Code  — {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Custodex: <reason>"}}
+#   Cursor       — {"permission":"deny","user_message":"Custodex: <reason>"}
+#   Gemini CLI   — exit 2 (no JSON required)
+# ============================================================
+
+set -euo pipefail
+
+# ─── 1. LOAD CONFIG ────────────────────────────────────────────────────────────
+# Read from ~/.custodex/config.json first, then fall back to env vars.
+
+CUSTODEX_API_KEY="${CUSTODEX_API_KEY:-}"
+CUSTODEX_BASE_URL="${CUSTODEX_BASE_URL:-}"
+CUSTODEX_PROJECT_FILTER="${CUSTODEX_PROJECT_FILTER:-}"
+
+_config_file="${HOME}/.custodex/config.json"
+if [[ -f "$_config_file" ]]; then
+  _cfg_key=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    d = json.load(open('${_config_file}'))
+    print(d.get('apiKey', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+  _cfg_url=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    d = json.load(open('${_config_file}'))
+    print(d.get('baseUrl', '').rstrip('/'))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+  [[ -z "$CUSTODEX_API_KEY"  && -n "$_cfg_key" ]] && CUSTODEX_API_KEY="$_cfg_key"
+  [[ -z "$CUSTODEX_BASE_URL" && -n "$_cfg_url" ]] && CUSTODEX_BASE_URL="$_cfg_url"
+fi
+
+# Bail out silently if not configured — don't break the IDE.
+[[ -z "$CUSTODEX_API_KEY" || -z "$CUSTODEX_BASE_URL" ]] && exit 0
+
+# Normalize trailing slash
+CUSTODEX_BASE_URL="${CUSTODEX_BASE_URL%/}"
+
+# ─── 2. STATE DIRECTORY ────────────────────────────────────────────────────────
+CUSTODEX_STATE_DIR="${TMPDIR:-/tmp}/custodex-hooks"
+mkdir -p "$CUSTODEX_STATE_DIR"
+
+# ─── 3. READ STDIN ─────────────────────────────────────────────────────────────
+INPUT=$(cat)
+
+# ─── 4. IDE DETECTION & FIELD NORMALISATION ────────────────────────────────────
+# All fields are normalised into a flat set of shell variables so the rest of
+# the script can be IDE-agnostic.  IDE-specific response formatting is handled
+# only at the output layer.
+#
+# Normalised variables (guaranteed non-empty defaults):
+#   IDE                — "gemini" | "cursor" | "claude"
+#   EVENT              — canonical event name (see routing table below)
+#   SESSION_ID         — unified session/conversation identifier
+#   TOOL_NAME          — tool being used (may be empty for non-tool events)
+#   CWD                — working directory
+#   SUBAGENT_ID        — subagent identifier (may be empty)
+#   SUBAGENT_TYPE      — subagent type string (may be empty)
+#   USER_PROMPT        — user prompt text (may be empty)
+#   TOOL_OUTPUT        — tool output text, truncated (may be empty)
+#   RAW_EVENT          — original hook_event_name from input
+
+eval "$(/usr/bin/python3 -c "
+import sys, json, os
+
+raw = '''${INPUT}'''
+try:
+    d = json.loads(raw)
+except Exception:
+    d = {}
+
+# ── IDE Detection ──────────────────────────────────────────────────────────────
+gemini_session = os.environ.get('GEMINI_SESSION_ID', '')
+if gemini_session:
+    ide = 'gemini'
+elif 'conversation_id' in d and 'session_id' not in d:
+    ide = 'cursor'
+else:
+    ide = 'claude'
+
+# ── Raw event name ─────────────────────────────────────────────────────────────
+raw_event = d.get('hook_event_name', '')
+
+# ── Canonical event mapping ────────────────────────────────────────────────────
+# Normalise IDE-specific event name variants to a shared canonical name so the
+# routing case statement below does not need IDE awareness.
+event_map = {
+    # Session start
+    'SessionStart':          'SessionStart',
+    'sessionStart':          'SessionStart',
+    # Subagent start
+    'SubagentStart':         'SubagentStart',
+    'subagentStart':         'SubagentStart',
+    # Pre-tool use
+    'PreToolUse':            'PreToolUse',
+    'preToolUse':            'PreToolUse',
+    'beforeShellExecution':  'PreToolUse',   # Cursor shell variant
+    'beforeMCPExecution':    'PreToolUse',   # Cursor MCP variant
+    'BeforeTool':            'PreToolUse',   # Gemini
+    # Post-tool use
+    'PostToolUse':           'PostToolUse',
+    'postToolUse':           'PostToolUse',
+    'afterShellExecution':   'PostToolUse',  # Cursor shell variant
+    'afterFileEdit':         'PostToolUse',  # Cursor file-edit variant
+    'AfterTool':             'PostToolUse',  # Gemini
+    # User prompt
+    'UserPromptSubmit':      'UserPromptSubmit',
+    'beforeSubmitPrompt':    'UserPromptSubmit',  # Cursor
+    'BeforeAgent':           'UserPromptSubmit',  # Gemini
+}
+event = event_map.get(raw_event, raw_event)
+
+# ── Session ID ────────────────────────────────────────────────────────────────
+if ide == 'gemini':
+    session_id = gemini_session
+elif ide == 'cursor':
+    session_id = d.get('conversation_id', d.get('session_id', ''))
+else:
+    session_id = d.get('session_id', '')
+
+# ── Tool name ─────────────────────────────────────────────────────────────────
+# For Cursor shell/MCP events the tool name is embedded differently.
+if raw_event == 'beforeShellExecution':
+    tool_name = 'Bash'
+elif raw_event == 'afterShellExecution':
+    tool_name = 'Bash'
+elif raw_event == 'afterFileEdit':
+    tool_name = 'Edit'
+else:
+    tool_name = d.get('tool_name', '')
+
+# ── CWD ───────────────────────────────────────────────────────────────────────
+cwd = d.get('cwd', os.environ.get('PWD', ''))
+
+# ── Subagent fields ───────────────────────────────────────────────────────────
+if ide == 'cursor':
+    subagent_id   = d.get('subagent_id',   d.get('agent_id', ''))
+    subagent_type = d.get('subagent_type', d.get('agent_type', ''))
+else:
+    subagent_id   = d.get('agent_id', '')
+    subagent_type = d.get('agent_type', '')
+
+# ── User prompt ───────────────────────────────────────────────────────────────
+user_prompt = (
+    d.get('user_prompt')
+    or d.get('prompt')
+    or ''
+)[:4096]
+
+# ── Tool output (truncated) ───────────────────────────────────────────────────
+raw_output = d.get('tool_output', d.get('output', ''))
+if isinstance(raw_output, dict):
+    raw_output = json.dumps(raw_output)[:2048]
+elif raw_output:
+    raw_output = str(raw_output)[:2048]
+else:
+    raw_output = ''
+
+# ── Cursor-specific extra fields ──────────────────────────────────────────────
+# composer_mode / is_background_agent for SessionStart metadata
+composer_mode        = str(d.get('composer_mode', '')).lower()
+is_background_agent  = str(d.get('is_background_agent', '')).lower()
+# tool_use_id for Cursor PreToolUse
+tool_use_id          = d.get('tool_use_id', '')
+
+def esc(v):
+    return str(v).replace(\"'\", '').replace('\"', '').replace('\n', ' ').replace('\\\$', '')
+
+fields = {
+    'IDE':                  ide,
+    'EVENT':                event,
+    'RAW_EVENT':            raw_event,
+    'SESSION_ID':           esc(session_id),
+    'TOOL_NAME':            esc(tool_name),
+    'CWD':                  esc(cwd),
+    'SUBAGENT_ID':          esc(subagent_id),
+    'SUBAGENT_TYPE':        esc(subagent_type),
+    'USER_PROMPT':          esc(user_prompt),
+    'TOOL_OUTPUT':          esc(raw_output),
+    'COMPOSER_MODE':        esc(composer_mode),
+    'IS_BACKGROUND_AGENT':  esc(is_background_agent),
+    'TOOL_USE_ID':          esc(tool_use_id),
+}
+for k, v in fields.items():
+    print(f\"{k}='{v}'\")
+" <<< "$INPUT" 2>/dev/null)" || exit 0
+
+# ─── 5. PROJECT FILTER ─────────────────────────────────────────────────────────
+if [[ -n "$CUSTODEX_PROJECT_FILTER" && "$CWD" != *"$CUSTODEX_PROJECT_FILTER"* ]]; then
+  exit 0
+fi
+
+# ─── 6. UTILITY FUNCTIONS ──────────────────────────────────────────────────────
+
+# Return the stored Custodex agent ID for the current session / subagent.
+get_agent_id() {
+  if [[ -n "$SUBAGENT_ID" ]]; then
+    cat "$CUSTODEX_STATE_DIR/subagent-${SESSION_ID}-${SUBAGENT_ID}" 2>/dev/null || echo ""
+  else
+    cat "$CUSTODEX_STATE_DIR/agent-${SESSION_ID}" 2>/dev/null || echo ""
+  fi
+}
+
+# Save a Custodex agent ID to state.
+save_agent_id() {
+  local id="$1"
+  if [[ -n "$SUBAGENT_ID" ]]; then
+    printf '%s' "$id" > "$CUSTODEX_STATE_DIR/subagent-${SESSION_ID}-${SUBAGENT_ID}"
+  else
+    printf '%s' "$id" > "$CUSTODEX_STATE_DIR/agent-${SESSION_ID}"
+  fi
+}
+
+# Register an agent with the Custodex API and persist its returned ID.
+# Usage: register_agent <name> [extra_json_fragment]
+# Returns: the new agentId string (printed to stdout), or empty on failure.
+register_agent() {
+  local name="$1"
+  local extra_meta="${2:-}"
+  local response agent_id
+  response=$(curl -sf --max-time 4 -X POST "${CUSTODEX_BASE_URL}/api/agents/register" \
+    -H "Authorization: Bearer ${CUSTODEX_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"name\": \"${name}\",
+      \"scopes\": [\"read\", \"write\", \"execute\"],
+      \"metadata\": {
+        \"project\": \"$(basename "${CWD:-unknown}")\",
+        \"source\": \"universal-hook\",
+        \"ide\": \"${IDE}\",
+        \"sessionId\": \"${SESSION_ID}\"
+        ${extra_meta}
+      },
+      \"protocol\": \"mcp\"
+    }" 2>/dev/null) || true
+
+  if [[ -n "$response" ]]; then
+    agent_id=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    print(json.loads('''${response}''').get('agentId',''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+    if [[ -n "$agent_id" ]]; then
+      save_agent_id "$agent_id"
+      echo "$agent_id"
+      return 0
+    fi
+  fi
+  echo ""
+}
+
+# Map a tool name to a Custodex action string.
+tool_to_action() {
+  local t="$1"
+  case "$t" in
+    Write|Edit)         echo "file:write" ;;
+    Bash|shell)         echo "shell:execute" ;;
+    Read)               echo "file:read" ;;
+    Agent|Task)         echo "agent:spawn" ;;
+    Glob|Grep)          echo "file:search" ;;
+    WebFetch|WebSearch) echo "web:access" ;;
+    mcp__*)             echo "mcp:call" ;;
+    *)                  echo "tool:use" ;;
+  esac
+}
+
+# Emit a deny response in the format required by the current IDE, then exit.
+# Usage: deny_response <reason_string>
+deny_response() {
+  local reason="$1"
+  case "$IDE" in
+    claude)
+      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Custodex: %s"}}\n' "$reason"
+      ;;
+    cursor)
+      printf '{"permission":"deny","user_message":"Custodex: %s"}\n' "$reason"
+      ;;
+    gemini)
+      # Gemini reads exit code 2 as a system-level block; no JSON required.
+      exit 2
+      ;;
+  esac
+  exit 0
+}
+
+# ─── 7. EVENT HANDLERS ─────────────────────────────────────────────────────────
+
+# ── SESSION START ──────────────────────────────────────────────────────────────
+handle_session_start() {
+  local proj agent_name agent_id extra_meta
+
+  proj=$(basename "${CWD:-unknown}")
+  agent_name="${proj}-orchestrator"
+
+  # Cursor exposes composer_mode and is_background_agent on session start.
+  extra_meta=", \"role\": \"orchestrator\", \"autoDiscovered\": true"
+  if [[ "$IDE" == "cursor" ]]; then
+    extra_meta="${extra_meta}, \"composerMode\": \"${COMPOSER_MODE}\", \"isBackgroundAgent\": \"${IS_BACKGROUND_AGENT}\""
+  fi
+  if [[ "$IDE" == "gemini" ]]; then
+    extra_meta="${extra_meta}, \"geminiSessionId\": \"${SESSION_ID}\""
+  fi
+
+  agent_id=$(register_agent "$agent_name" "$extra_meta")
+  if [[ -n "$agent_id" ]]; then
+    printf '0' > "$CUSTODEX_STATE_DIR/gen-${SESSION_ID}"
+    # Only Claude Code reads hookSpecificOutput on SessionStart; other IDEs
+    # silently ignore JSON printed here, so it is safe to emit for all.
+    printf '{"hookSpecificOutput":{"additionalContext":"[Custodex] Orchestrator registered: %s (ID: %s). Running on %s."}}\n' \
+      "$agent_name" "$agent_id" "$IDE"
+  fi
+  exit 0
+}
+
+# ── SUBAGENT START ─────────────────────────────────────────────────────────────
+handle_subagent_start() {
+  # Gemini CLI has no subagent concept — skip silently.
+  [[ "$IDE" == "gemini" ]] && exit 0
+
+  local proj agent_name parent_agent_id parent_gen child_gen extra_meta response new_id
+
+  proj=$(basename "${CWD:-unknown}")
+
+  if [[ -n "$SUBAGENT_TYPE" ]]; then
+    agent_name="${proj}-${SUBAGENT_TYPE}"
+  else
+    agent_name="${proj}-subagent-$(date +%s)"
+  fi
+
+  parent_agent_id=$(cat "$CUSTODEX_STATE_DIR/agent-${SESSION_ID}" 2>/dev/null || echo "")
+  parent_gen=$(cat "$CUSTODEX_STATE_DIR/gen-${SESSION_ID}" 2>/dev/null || echo "0")
+  child_gen=$((parent_gen + 1))
+
+  extra_meta=", \"role\": \"subagent\", \"subagentType\": \"${SUBAGENT_TYPE}\", \"subagentId\": \"${SUBAGENT_ID}\""
+
+  # Cursor provides task description and parent conversation ID.
+  if [[ "$IDE" == "cursor" ]]; then
+    local cursor_task
+    cursor_task=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    t = d.get('task','')
+    print(str(t)[:200].replace('\"',''))
+except Exception:
+    print('')
+" <<< "$INPUT" 2>/dev/null || echo "")
+    [[ -n "$cursor_task" ]] && extra_meta="${extra_meta}, \"task\": \"${cursor_task}\""
+  fi
+
+  response=$(curl -sf --max-time 4 -X POST "${CUSTODEX_BASE_URL}/api/agents/register" \
+    -H "Authorization: Bearer ${CUSTODEX_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"name\": \"${agent_name}\",
+      \"scopes\": [\"read\", \"write\", \"execute\"],
+      \"metadata\": {
+        \"project\": \"$(basename "${CWD:-unknown}")\",
+        \"source\": \"universal-hook\",
+        \"ide\": \"${IDE}\",
+        \"sessionId\": \"${SESSION_ID}\"
+        ${extra_meta}
+      },
+      \"protocol\": \"mcp\",
+      \"parentAgentId\": \"${parent_agent_id}\",
+      \"generation\": ${child_gen}
+    }" 2>/dev/null) || true
+
+  if [[ -n "$response" ]]; then
+    new_id=$(/usr/bin/python3 -c "
+import json
+try:
+    print(json.loads('''${response}''').get('agentId',''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+    if [[ -n "$new_id" ]]; then
+      save_agent_id "$new_id"
+      printf '%s' "$child_gen" > "$CUSTODEX_STATE_DIR/gen-${SESSION_ID}-${SUBAGENT_ID}"
+    fi
+  fi
+  exit 0
+}
+
+# ── USER PROMPT ────────────────────────────────────────────────────────────────
+handle_user_prompt() {
+  local custodex_agent_id safe_prompt caller_type caller_id on_behalf
+
+  custodex_agent_id=$(get_agent_id)
+  [[ -z "$custodex_agent_id" ]] && exit 0
+
+  # Persist the prompt so subsequent PreToolUse can reference it.
+  printf '%s' "$USER_PROMPT" > "$CUSTODEX_STATE_DIR/prompt-${SESSION_ID}"
+
+  safe_prompt=$(printf '%s' "$USER_PROMPT" | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()[:4096]))
+" 2>/dev/null || echo '""')
+
+  caller_type="user"
+  caller_id=""
+  if [[ -n "$SUBAGENT_ID" ]]; then
+    caller_type="agent"
+    caller_id=$(cat "$CUSTODEX_STATE_DIR/agent-${SESSION_ID}" 2>/dev/null || echo "")
+  fi
+
+  on_behalf=""
+  if [[ -n "$SUBAGENT_TYPE" ]]; then
+    on_behalf=", \"onBehalfOf\": \"$(basename "${CWD:-unknown}")-${SUBAGENT_TYPE}\""
+  fi
+
+  curl -sf --max-time 4 -X POST "${CUSTODEX_BASE_URL}/api/telemetry" \
+    -H "Authorization: Bearer ${CUSTODEX_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"action\": \"user.prompt\",
+      \"scope\": \"session:input\",
+      \"decision\": \"allowed\",
+      \"latencyMs\": 0,
+      \"metadata\": {
+        \"agentId\": \"${custodex_agent_id}\",
+        \"hookEvent\": \"UserPromptSubmit\",
+        \"ide\": \"${IDE}\",
+        \"sessionId\": \"${SESSION_ID}\",
+        \"userPrompt\": ${safe_prompt},
+        \"caller\": {
+          \"type\": \"${caller_type}\",
+          \"id\": \"${caller_id}\"
+        },
+        \"environment\": {
+          \"os\": \"$(uname -s)\",
+          \"shell\": \"${SHELL:-unknown}\",
+          \"cwd\": \"${CWD:-unknown}\"
+        }
+      }
+      ${on_behalf}
+    }" >/dev/null 2>&1 &
+
+  exit 0
+}
+
+# ── PRE TOOL USE (synchronous — can deny) ─────────────────────────────────────
+# Skip read-only tools to reduce latency for operations that carry no risk.
+_READONLY_TOOLS="|Read|Glob|Grep|WebSearch|"
+
+handle_pre_tool_use() {
+  # Skip read-only tools — no governance action needed.
+  if [[ "$_READONLY_TOOLS" == *"|${TOOL_NAME}|"* ]]; then
+    exit 0
+  fi
+
+  local custodex_agent_id action scope safe_scope response decision reason
+
+  custodex_agent_id=$(get_agent_id)
+
+  # Late-register if no agent ID recorded yet.
+  if [[ -z "$custodex_agent_id" ]]; then
+    local proj late_name
+    proj=$(basename "${CWD:-unknown}")
+    if [[ -n "$SUBAGENT_ID" ]]; then
+      late_name="${proj}-${SUBAGENT_TYPE:-subagent}-late"
+      custodex_agent_id=$(register_agent "$late_name" ", \"role\": \"subagent\", \"subagentType\": \"${SUBAGENT_TYPE}\", \"lateRegistration\": true")
+    else
+      custodex_agent_id=$(register_agent "${proj}-orchestrator-late" ", \"role\": \"orchestrator\", \"lateRegistration\": true")
+    fi
+  fi
+
+  action=$(tool_to_action "$TOOL_NAME")
+
+  # Extract the primary scope value from tool_input.
+  scope=$(/usr/bin/python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read())
+    ti = d.get('tool_input', {})
+    if not isinstance(ti, dict): ti = {}
+    for k in ['file_path','command','pattern','description','prompt','url','query','skill']:
+        if k in ti:
+            print(str(ti[k])[:150])
+            break
+    else:
+        print('${TOOL_NAME}')
+except Exception:
+    print('${TOOL_NAME}')
+" <<< "$INPUT" 2>/dev/null || echo "$TOOL_NAME")
+
+  safe_scope=$(printf '%s' "$scope" | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()))
+" 2>/dev/null || echo "\"unknown\"")
+
+  # Read last persisted prompt for context.
+  local safe_last_prompt='""'
+  if [[ -f "$CUSTODEX_STATE_DIR/prompt-${SESSION_ID}" ]]; then
+    safe_last_prompt=$(cat "$CUSTODEX_STATE_DIR/prompt-${SESSION_ID}" 2>/dev/null | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()[:2048]))
+" 2>/dev/null || echo '""')
+  fi
+
+  # Call verify endpoint synchronously.
+  response=$(curl -sf --max-time 4 -X POST "${CUSTODEX_BASE_URL}/api/verify" \
+    -H "Authorization: Bearer ${CUSTODEX_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"agentId\": \"${custodex_agent_id}\",
+      \"action\": \"${action}\",
+      \"scope\": ${safe_scope},
+      \"metadata\": {
+        \"toolName\": \"${TOOL_NAME}\",
+        \"ide\": \"${IDE}\",
+        \"sessionId\": \"${SESSION_ID}\",
+        \"userPrompt\": ${safe_last_prompt},
+        \"environment\": {
+          \"os\": \"$(uname -s)\",
+          \"cwd\": \"${CWD:-unknown}\"
+        }
+      }
+    }" 2>/dev/null) || true
+
+  if [[ -n "$response" ]]; then
+    decision=$(/usr/bin/python3 -c "
+import json
+try:
+    print(json.loads('''${response}''').get('decision','allowed'))
+except Exception:
+    print('allowed')
+" 2>/dev/null || echo "allowed")
+
+    if [[ "$decision" == "denied" ]]; then
+      reason=$(/usr/bin/python3 -c "
+import json
+try:
+    d = json.loads('''${response}''')
+    print(d.get('reason', d.get('message', 'Policy violation')))
+except Exception:
+    print('Policy violation')
+" 2>/dev/null || echo "Policy violation")
+      deny_response "$reason"
+      # deny_response calls exit — execution never reaches here.
+    fi
+  fi
+
+  exit 0
+}
+
+# ── POST TOOL USE (fire-and-forget telemetry) ──────────────────────────────────
+handle_post_tool_use() {
+  local custodex_agent_id action scope safe_scope actor_name on_behalf
+  local safe_tool_output safe_last_prompt caller_type caller_id caller_name
+
+  custodex_agent_id=$(get_agent_id)
+  [[ -z "$custodex_agent_id" ]] && exit 0
+
+  action=$(tool_to_action "$TOOL_NAME")
+
+  # Cursor afterFileEdit — override action and extract file path from edits field.
+  if [[ "$RAW_EVENT" == "afterFileEdit" ]]; then
+    action="file:write"
+    local file_path
+    file_path=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    print(d.get('file_path', ''))
+except Exception:
+    print('')
+" <<< "$INPUT" 2>/dev/null || echo "")
+    [[ -n "$file_path" ]] && TOOL_NAME="Edit($file_path)"
+  fi
+
+  # Cursor afterShellExecution — capture duration.
+  local duration_ms="0"
+  if [[ "$RAW_EVENT" == "afterShellExecution" ]]; then
+    duration_ms=$(/usr/bin/python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    print(int(d.get('duration', 0) * 1000))
+except Exception:
+    print(0)
+" <<< "$INPUT" 2>/dev/null || echo "0")
+  fi
+
+  scope=$(/usr/bin/python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read())
+    ti = d.get('tool_input', {})
+    if not isinstance(ti, dict): ti = {}
+    for k in ['file_path','command','pattern','description','prompt','url','query','skill']:
+        if k in ti:
+            print(str(ti[k])[:150])
+            break
+    else:
+        print('${TOOL_NAME}')
+except Exception:
+    print('${TOOL_NAME}')
+" <<< "$INPUT" 2>/dev/null || echo "$TOOL_NAME")
+
+  safe_scope=$(printf '%s' "$scope" | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()))
+" 2>/dev/null || echo "\"unknown\"")
+
+  safe_tool_output='""'
+  if [[ -n "$TOOL_OUTPUT" ]]; then
+    safe_tool_output=$(printf '%s' "$TOOL_OUTPUT" | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()[:2048]))
+" 2>/dev/null || echo '""')
+  fi
+
+  safe_last_prompt='""'
+  if [[ -f "$CUSTODEX_STATE_DIR/prompt-${SESSION_ID}" ]]; then
+    safe_last_prompt=$(cat "$CUSTODEX_STATE_DIR/prompt-${SESSION_ID}" 2>/dev/null | /usr/bin/python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read().strip()[:2048]))
+" 2>/dev/null || echo '""')
+  fi
+
+  actor_name="orchestrator"
+  [[ -n "$SUBAGENT_TYPE" ]] && actor_name="$SUBAGENT_TYPE"
+
+  on_behalf=""
+  [[ -n "$SUBAGENT_TYPE" ]] && on_behalf=", \"onBehalfOf\": \"$(basename "${CWD:-unknown}")-${SUBAGENT_TYPE}\""
+
+  caller_type="user"
+  caller_id=""
+  caller_name=""
+  if [[ -n "$SUBAGENT_ID" ]]; then
+    caller_type="agent"
+    caller_id=$(cat "$CUSTODEX_STATE_DIR/agent-${SESSION_ID}" 2>/dev/null || echo "")
+    caller_name="orchestrator"
+  fi
+
+  # Tool input summary (key fields only, safe for JSON embedding).
+  local tool_summary
+  tool_summary=$(/usr/bin/python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read()).get('tool_input', {})
+    if not isinstance(d, dict): d = {}
+    s = {}
+    for k in ['command','file_path','pattern','description','prompt','url','query','skill','name']:
+        if k in d: s[k] = str(d[k])[:200]
+    print(json.dumps(s))
+except Exception:
+    print('{}')
+" <<< "$INPUT" 2>/dev/null || echo "{}")
+
+  # Fire telemetry in the background — must not block the IDE.
+  curl -sf --max-time 4 -X POST "${CUSTODEX_BASE_URL}/api/telemetry" \
+    -H "Authorization: Bearer ${CUSTODEX_API_KEY}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"action\": \"${action}\",
+      \"scope\": ${safe_scope},
+      \"decision\": \"allowed\",
+      \"latencyMs\": ${duration_ms},
+      \"metadata\": {
+        \"agentId\": \"${custodex_agent_id}\",
+        \"toolName\": \"${TOOL_NAME}\",
+        \"hookEvent\": \"PostToolUse\",
+        \"rawEvent\": \"${RAW_EVENT}\",
+        \"ide\": \"${IDE}\",
+        \"sessionId\": \"${SESSION_ID}\",
+        \"actor\": \"${actor_name}\",
+        \"subagentType\": \"${SUBAGENT_TYPE}\",
+        \"subagentId\": \"${SUBAGENT_ID}\",
+        \"project\": \"$(basename "${CWD:-unknown}")\",
+        \"toolInput\": ${tool_summary},
+        \"toolOutput\": ${safe_tool_output},
+        \"userPrompt\": ${safe_last_prompt},
+        \"caller\": {
+          \"type\": \"${caller_type}\",
+          \"id\": \"${caller_id}\",
+          \"name\": \"${caller_name}\",
+          \"directive\": ${safe_last_prompt}
+        },
+        \"environment\": {
+          \"os\": \"$(uname -s)\",
+          \"shell\": \"${SHELL:-unknown}\",
+          \"cwd\": \"${CWD:-unknown}\"
+        }
+      }
+      ${on_behalf}
+    }" >/dev/null 2>&1 &
+
+  exit 0
+}
+
+# ─── 8. ROUTE ──────────────────────────────────────────────────────────────────
+# EVENT is the normalised canonical event name set during field extraction.
+case "$EVENT" in
+  SessionStart)       handle_session_start ;;
+  SubagentStart)      handle_subagent_start ;;
+  PreToolUse)         handle_pre_tool_use ;;
+  PostToolUse)        handle_post_tool_use ;;
+  UserPromptSubmit)   handle_user_prompt ;;
+  *)                  exit 0 ;;
+esac