@iflow-mcp/jkheadley-instar 0.26.2

package/src/data/http-hook-templates.ts

@@ -0,0 +1,81 @@
+/**
+ * Hook Event Templates — Configuration for Claude Code event reporting hooks.
+ *
+ * These templates are merged into .claude/settings.json during init.
+ * They configure command hooks that POST event payloads to the Instar server
+ * for session telemetry, observability, and session resumption (claudeSessionId).
+ *
+ * IMPORTANT: Uses command hooks (type: "command"), NOT HTTP hooks (type: "http").
+ * HTTP hooks silently fail to fire in Claude Code <=2.1.78 (confirmed 2026-03-24).
+ * Command hooks reliably fire, so we use a small Node script that POSTs to the server.
+ *
+ * Design decisions:
+ * - Safety-critical hooks (dangerous-command-guard, session-start) stay as separate scripts
+ * - Event reporter hooks are for OBSERVABILITY — they cannot reliably block actions
+ * - All hooks POST to /hooks/events on the local Instar server via the reporter script
+ * - Auth via bearer token from INSTAR_AUTH_TOKEN env var
+ */
+
+export interface HookEventTemplate {
+  event: string;
+  matcher?: string;
+  config: {
+    type: 'command';
+    command: string;
+    timeout?: number;
+  };
+}
+
+/**
+ * All hook event templates for observability events.
+ *
+ * These are added alongside (not replacing) existing shell command hooks.
+ * Events covered:
+ * - PostToolUse: what tools sessions are using + session_id for resume
+ * - SubagentStart: when subagents spawn (with agent_id, agent_type)
+ * - SubagentStop: when subagents finish (with last_assistant_message, transcript path)
+ * - Stop: when main agent finishes (with last_assistant_message)
+ * - WorktreeCreate: when worktrees are created (connects to worktree awareness)
+ * - WorktreeRemove: when worktrees are removed
+ * - TaskCompleted: when tasks finish (with task_id, subject, description)
+ * - SessionEnd: when sessions terminate (with exit reason)
+ * - PreCompact: when context compaction is about to occur (with trigger reason)
+ */
+export const HOOK_EVENT_TEMPLATES: HookEventTemplate[] = [
+  { event: 'PostToolUse', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'SubagentStart', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'SubagentStop', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'Stop', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'WorktreeCreate', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'WorktreeRemove', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'TaskCompleted', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'SessionEnd', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+  { event: 'PreCompact', config: { type: 'command', command: 'node .instar/hooks/instar/hook-event-reporter.js', timeout: 3000 } },
+];
+
+// Backwards-compat export — old name, new behavior
+export const HTTP_HOOK_TEMPLATES = HOOK_EVENT_TEMPLATES;
+export type HttpHookTemplate = HookEventTemplate;
+
+/**
+ * Convert templates to the Claude Code settings.json hook format.
+ * @param _serverUrl Ignored (kept for API compat). Command hooks use env vars.
+ */
+export function buildHttpHookSettings(_serverUrl: string): Record<string, Array<{ matcher?: string; hooks: Array<Record<string, unknown>> }>> {
+  const settings: Record<string, Array<{ matcher?: string; hooks: Array<Record<string, unknown>> }>> = {};
+
+  for (const template of HOOK_EVENT_TEMPLATES) {
+    if (!settings[template.event]) {
+      settings[template.event] = [];
+    }
+
+    const entry: { matcher: string; hooks: Array<Record<string, unknown>> } = {
+      matcher: template.matcher ?? '',
+      hooks: [template.config as unknown as Record<string, unknown>],
+    };
+
+    settings[template.event].push(entry);
+  }
+
+  return settings;
+}

package/src/templates/hooks/compaction-recovery.sh

@@ -0,0 +1,371 @@
+#!/bin/bash
+# Compaction recovery — INJECTS identity when Claude's context compresses.
+# Without this, the agent loses its identity every 30-60 minutes.
+#
+# CRITICAL DESIGN: This hook OUTPUTS file content directly, not pointers.
+# After compaction, the agent is confused — asking it to read files is
+# asking the confused agent to help itself. Structure > Willpower:
+# the hook does the work, not the agent.
+#
+# The 164th Lesson (Dawn): Advisory hooks are insufficient.
+# Grounding must be automatic — content injected, not pointed to.
+#
+# Installed by instar during setup. Runs as a Claude Code Notification hook
+# matched on "compaction".
+
+INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+
+echo "=== COMPACTION RECOVERY — IDENTITY RESTORATION ==="
+echo ""
+
+# Phase A: Core Identity (inject AGENT.md content directly)
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  echo "--- YOUR IDENTITY (from .instar/AGENT.md) ---"
+  cat "$INSTAR_DIR/AGENT.md"
+  echo ""
+  echo "--- END IDENTITY ---"
+  echo ""
+fi
+
+# Phase A.5: Soul (inject Personality Seed + Core Values from soul.md)
+# Only inject compact identity sections, not full history.
+# Integrity-verified: if soul.md was tampered with, fall back to init snapshot.
+if [ -f "$INSTAR_DIR/soul.md" ]; then
+  SOUL_LINES=$(wc -l < "$INSTAR_DIR/soul.md" | tr -d ' ')
+  if [ "$SOUL_LINES" -gt "10" ]; then
+    # Check integrity via server if available
+    SOUL_INTEGRITY="valid"
+    if [ -n "$PORT" ] && [ -n "$AUTH_TOKEN" ]; then
+      INTEGRITY_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+        "http://localhost:${PORT}/identity/soul/integrity" 2>/dev/null)
+      SOUL_INTEGRITY=$(echo "$INTEGRITY_CHECK" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print('valid' if d.get('valid') else 'invalid')
+except: print('valid')
+" 2>/dev/null)
+    fi
+
+    if [ "$SOUL_INTEGRITY" = "valid" ]; then
+      # Extract Personality Seed and Core Values sections only
+      echo "--- YOUR SOUL (from .instar/soul.md — Personality Seed + Core Values) ---"
+      python3 -c "
+import sys
+content = open('$INSTAR_DIR/soul.md').read()
+sections = []
+for header in ['## Personality Seed', '## Core Values']:
+    idx = content.find(header)
+    if idx == -1: continue
+    after = content[idx:]
+    # Find next section boundary
+    import re
+    m = re.search(r'\n---\n|\n## ', after[len(header):])
+    section = after[:len(header) + m.start()] if m else after
+    sections.append(section.strip())
+if sections:
+    print('\n\n'.join(sections))
+" 2>/dev/null
+      echo ""
+      echo "--- END SOUL ---"
+      echo ""
+    else
+      # Fall back to init snapshot
+      if [ -f "$INSTAR_DIR/state/soul.init.md" ]; then
+        echo "--- YOUR SOUL (from init snapshot — integrity check failed) ---"
+        python3 -c "
+content = open('$INSTAR_DIR/state/soul.init.md').read()
+idx = content.find('## Personality Seed')
+if idx >= 0:
+    import re
+    after = content[idx:]
+    m = re.search(r'\n---\n|\n## ', after[len('## Personality Seed'):])
+    section = after[:len('## Personality Seed') + m.start()] if m else after
+    print(section.strip())
+" 2>/dev/null
+        echo ""
+        echo "WARNING: soul.md integrity check failed. Only Personality Seed from init snapshot injected."
+        echo "--- END SOUL ---"
+        echo ""
+      fi
+    fi
+  fi
+fi
+
+# Phase B: Memory (inject MEMORY.md content directly)
+if [ -f "$INSTAR_DIR/MEMORY.md" ]; then
+  # Only inject if MEMORY.md has actual content (more than the template skeleton)
+  MEMORY_LINES=$(wc -l < "$INSTAR_DIR/MEMORY.md" | tr -d ' ')
+  if [ "$MEMORY_LINES" -gt "15" ]; then
+    echo "--- YOUR MEMORY (from .instar/MEMORY.md) ---"
+    cat "$INSTAR_DIR/MEMORY.md"
+    echo ""
+    echo "--- END MEMORY ---"
+    echo ""
+  else
+    echo "Memory file exists at .instar/MEMORY.md (minimal content — check if needed)."
+    echo ""
+  fi
+fi
+
+# Phase C: User context (inject USER.md content directly)
+if [ -f "$INSTAR_DIR/USER.md" ]; then
+  echo "--- YOUR USER (from .instar/USER.md) ---"
+  cat "$INSTAR_DIR/USER.md"
+  echo ""
+  echo "--- END USER ---"
+  echo ""
+fi
+
+# Phase D: Active dispatch context (behavioral lessons from Dawn)
+if [ -f "$INSTAR_DIR/state/dispatch-context.md" ]; then
+  DISPATCH_LINES=$(wc -l < "$INSTAR_DIR/state/dispatch-context.md" | tr -d ' ')
+  if [ "$DISPATCH_LINES" -gt "2" ]; then
+    echo "--- ACTIVE DISPATCHES (behavioral lessons) ---"
+    cat "$INSTAR_DIR/state/dispatch-context.md"
+    echo ""
+    echo "--- END DISPATCHES ---"
+    echo ""
+  fi
+fi
+
+# Phase E: Job-specific grounding (if a job slug is detectable)
+if [ -f "$INSTAR_DIR/state/active-job.json" ]; then
+  JOB_SLUG=$(grep -o '"slug":"[^"]*"' "$INSTAR_DIR/state/active-job.json" 2>/dev/null | head -1 | cut -d'"' -f4)
+  JOB_TOPIC_ID=$(python3 -c "
+import json, sys
+try:
+    d = json.load(open('$INSTAR_DIR/state/active-job.json'))
+    tid = d.get('topicId')
+    print(tid if tid is not None else '')
+except:
+    print('')
+" 2>/dev/null)
+  if [ -n "$JOB_SLUG" ]; then
+    if [ -f "$INSTAR_DIR/grounding/jobs/${JOB_SLUG}.md" ]; then
+      echo "--- JOB CONTEXT: ${JOB_SLUG} ---"
+      cat "$INSTAR_DIR/grounding/jobs/${JOB_SLUG}.md"
+      echo ""
+      echo "--- END JOB CONTEXT ---"
+      echo ""
+    fi
+    # Surface the job's Telegram topic ID so agents don't hardcode it
+    if [ -n "$JOB_TOPIC_ID" ]; then
+      echo "JOB TELEGRAM TOPIC: This job's Telegram topic ID is ${JOB_TOPIC_ID}."
+      echo "Use: cat <<'EOF' | .instar/scripts/telegram-reply.sh ${JOB_TOPIC_ID}"
+      echo "Your message here"
+      echo "EOF"
+      echo ""
+    fi
+  fi
+fi
+
+# Phase F: Core cognitive principles (universal, survive compaction)
+echo "--- COGNITIVE PRINCIPLES (always active) ---"
+echo "1. SUBSTANCE OVER LABELS: Identity is content, not metadata. Different titles/IDs/statuses can hide identical content. Always verify at the content level."
+echo "2. CONTRADICTION = NEW CHECK: When a human contradicts your data, run a DIFFERENT kind of check, not the same one again. The human has information you don't."
+echo "3. CONFIDENCE INVERSION: The more obvious something feels, the more it needs verification. High confidence is where errors hide."
+echo "4. INHERITED CLAIMS: Handoff notes and previous session logs are CLAIMS TO VERIFY, not facts. Any claim about external state (repo, deployment, service, file) requires a verification command in THIS session. No command, no claim."
+echo "5. DISMISSAL WITHOUT INVESTIGATION: Never resolve a bug report or feedback item based on the title alone. Trace the reporter's actual code path first. If your resolution says 'this theoretically can't happen' — you haven't investigated."
+echo "--- END PRINCIPLES ---"
+echo ""
+
+# Phase F.5: Discovery state (prevents re-surfacing features already mentioned this session)
+# Resolves Open Question #5 from the Consent & Discovery Framework spec:
+# lastSurfacedAt timestamps persist in SQLite regardless of context state.
+if [ -f "$CONFIG_FILE" ]; then
+  PORT=$(grep -o '"port":[0-9]*' "$CONFIG_FILE" | head -1 | cut -d':' -f2)
+  if [ -n "$PORT" ]; then
+    AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('authToken',''))" 2>/dev/null)
+    FEATURES_JSON=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+      "http://localhost:${PORT}/features/summary" 2>/dev/null)
+    if [ -n "$FEATURES_JSON" ]; then
+      DISCOVERY_STATE=$(echo "$FEATURES_JSON" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    features = data.get('features', [])
+    if not features:
+        sys.exit(0)
+    enabled = [f['name'] for f in features if f.get('discoveryState') == 'enabled']
+    undiscovered = [f['name'] for f in features if f.get('discoveryState') == 'undiscovered']
+    aware = [f['name'] for f in features if f.get('discoveryState') in ('aware', 'interested', 'deferred')]
+    if enabled:
+        print(f'Enabled features: {\", \".join(enabled)}')
+    if undiscovered:
+        print(f'Undiscovered (available to surface): {\", \".join(undiscovered)}')
+    if aware:
+        print(f'User is aware of: {\", \".join(aware)}')
+    print()
+    print('IMPORTANT: Do NOT re-surface features already mentioned this session.')
+    print('Check POST /features/:id/surface timestamps before surfacing.')
+    print('Max 1 feature per conversation turn. Never during user frustration.')
+except Exception:
+    pass
+" 2>/dev/null)
+      if [ -n "$DISCOVERY_STATE" ]; then
+        echo "--- FEATURE DISCOVERY STATE (compaction-safe) ---"
+        echo "$DISCOVERY_STATE"
+        echo "--- END DISCOVERY STATE ---"
+        echo ""
+      fi
+    fi
+  fi
+fi
+
+# Relationships summary
+if [ -d "$INSTAR_DIR/relationships" ]; then
+  REL_COUNT=$(ls -1 "$INSTAR_DIR/relationships"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$REL_COUNT" -gt "0" ]; then
+    echo "You have ${REL_COUNT} tracked relationships in .instar/relationships/."
+    echo ""
+  fi
+fi
+
+# Serendipity findings status
+SERENDIPITY_DIR="$INSTAR_DIR/state/serendipity"
+if [ -d "$SERENDIPITY_DIR" ]; then
+  PENDING_COUNT=$(find "$SERENDIPITY_DIR" -maxdepth 1 -name "*.json" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$PENDING_COUNT" -gt "0" ]; then
+    echo "${PENDING_COUNT} pending serendipity finding(s) in .instar/state/serendipity/ — triage when current task completes."
+    echo ""
+  fi
+fi
+
+# Server health reminder + recent Telegram context
+CONFIG_FILE="$INSTAR_DIR/config.json"
+if [ -f "$CONFIG_FILE" ]; then
+  PORT=$(grep -o '"port":[0-9]*' "$CONFIG_FILE" | head -1 | cut -d':' -f2)
+  if [ -n "$PORT" ]; then
+    echo "Server: curl http://localhost:${PORT}/health | Capabilities: curl http://localhost:${PORT}/capabilities"
+
+    # Inject recent Telegram messages after compaction — thread context is often
+    # the first thing lost in compaction; re-injecting it immediately restores continuity.
+    # Use INSTAR_TELEGRAM_TOPIC (the actual session topic) first, fall back to lifeline topic.
+    HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${PORT}/health" 2>/dev/null)
+    if [ "$HEALTH" = "200" ]; then
+      TOPIC_FOR_CONTEXT="${INSTAR_TELEGRAM_TOPIC:-}"
+
+      # Fall back to lifeline topic if no session topic set
+      if [ -z "$TOPIC_FOR_CONTEXT" ]; then
+        TOPIC_FOR_CONTEXT=$(python3 -c "
+import json, sys
+try:
+    cfg = json.load(open('$CONFIG_FILE'))
+    for m in cfg.get('messaging', []):
+        if m.get('type') == 'telegram':
+            tid = m.get('config', {}).get('lifelineTopicId')
+            if tid:
+                print(tid)
+                sys.exit(0)
+    tid = cfg.get('telegram', {}).get('lifelineTopicId')
+    if tid:
+        print(tid)
+except Exception:
+    pass
+" 2>/dev/null)
+      fi
+
+      if [ -n "$TOPIC_FOR_CONTEXT" ]; then
+        AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('authToken',''))" 2>/dev/null)
+        if [ -n "$AUTH_TOKEN" ]; then
+          RECENT_MSGS=$(curl -s \
+            -H "Authorization: Bearer ${AUTH_TOKEN}" \
+            "http://localhost:${PORT}/telegram/topics/${TOPIC_FOR_CONTEXT}/messages?limit=15" 2>/dev/null)
+        else
+          RECENT_MSGS=$(curl -s \
+            "http://localhost:${PORT}/telegram/topics/${TOPIC_FOR_CONTEXT}/messages?limit=15" 2>/dev/null)
+        fi
+
+        # Format messages and detect unanswered user messages
+        echo "$RECENT_MSGS" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    msgs = data.get('messages', [])
+    if not msgs:
+        sys.exit(0)
+
+    print()
+    print('--- RECENT TELEGRAM CONTEXT (restoring after compaction, last %d messages) ---' % len(msgs))
+
+    for m in msgs:
+        ts = m.get('timestamp', '')[:16].replace('T', ' ')
+        from_user = m.get('fromUser', m.get('direction', 'in') == 'in')
+        text = m.get('text', '').strip()
+        sender = 'User' if from_user else 'Agent'
+        if len(text) > 300:
+            text = text[:297] + '...'
+        print(f'[{ts}] {sender}: {text}')
+
+    # Detect unanswered user messages
+    pending_user = []
+    for m in msgs:
+        text = m.get('text', '').strip()
+        if not text:
+            continue
+        from_user = m.get('fromUser', m.get('direction', 'in') == 'in')
+        if from_user:
+            pending_user.append(m)
+        else:
+            pending_user = []
+
+    if pending_user:
+        print()
+        print('!' * 60)
+        print('UNANSWERED MESSAGE(S) FROM USER:')
+        for pm in pending_user:
+            pm_text = pm.get('text', '')[:200]
+            pm_ts = pm.get('timestamp', '')[:16].replace('T', ' ')
+            print(f'  [{pm_ts}] \"{pm_text}\"')
+        print()
+        print('You MUST address these messages substantively. Do NOT respond')
+        print('with just a greeting or generic reply. If the latest message')
+        print('is a follow-up like \"hello?\" or \"please respond\", address')
+        print('the EARLIER unanswered message — that is what the user is')
+        print('waiting for.')
+        print('!' * 60)
+    print()
+    print('--- END TELEGRAM CONTEXT ---')
+except Exception:
+    pass
+" 2>/dev/null
+      fi
+    fi
+  fi
+fi
+
+# Phase G: Working Memory Assembly — inject relevant semantic knowledge after compaction
+# This surfaces what you already know that's relevant to the current context,
+# preventing you from re-deriving knowledge you've already accumulated.
+if [ -f "$CONFIG_FILE" ]; then
+  PORT=$(grep -o '"port":[0-9]*' "$CONFIG_FILE" | head -1 | cut -d':' -f2)
+  if [ -n "$PORT" ]; then
+    AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('authToken',''))" 2>/dev/null)
+    WORKING_MEM=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+      "http://localhost:${PORT}/context/working-memory?prompt=compaction-recovery&limit=5" 2>/dev/null)
+    if [ -n "$WORKING_MEM" ]; then
+      CONTEXT=$(echo "$WORKING_MEM" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ctx = data.get('context', '')
+    tokens = data.get('estimatedTokens', 0)
+    if ctx and tokens > 0:
+        print(f'[{tokens} tokens assembled from memory]')
+        print(ctx)
+except Exception:
+    pass
+" 2>/dev/null)
+      if [ -n "$CONTEXT" ]; then
+        echo ""
+        echo "--- WORKING MEMORY (relevant knowledge restored after compaction) ---"
+        echo "$CONTEXT"
+        echo "--- END WORKING MEMORY ---"
+      fi
+    fi
+  fi
+fi
+
+echo ""
+echo "=== RECOVERY COMPLETE — You are grounded. Continue your work. ==="

package/src/templates/hooks/dangerous-command-guard.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Dangerous command guard — safety infrastructure for autonomous agents.
+# Part of instar's "Security Through Identity" model.
+#
+# Supports two safety levels (configured in .instar/config.json → safety.level):
+#
+#   Level 1 (default): Block risky commands and tell the agent to ask the user.
+#     → Safe starting point. Human stays in the loop. Trust builds over time.
+#
+#   Level 2 (autonomous): Inject a self-verification prompt instead of blocking.
+#     → Agent reasons about whether the action is correct before proceeding.
+#     → Enables fully hands-off operation while maintaining intelligent safety.
+#     → Truly catastrophic commands (rm -rf /, fork bombs) are ALWAYS blocked.
+#
+# The progression from Level 1 → Level 2 is the path to full autonomy.
+# The agent isn't blindly executing — it's running an intelligent self-check
+# before every sensitive action. The hook makes this structural, not optional.
+#
+# Installed by instar during setup. Runs as a Claude Code PreToolUse hook on Bash.
+
+INPUT="$1"
+INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+
+# --- Read safety level from config ---
+SAFETY_LEVEL=1
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  SAFETY_LEVEL=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('safety', {}).get('level', 1))" 2>/dev/null || echo "1")
+fi
+
+# --- ALWAYS blocked (regardless of safety level) ---
+# These are catastrophic, irreversible operations that no self-check can undo.
+ALWAYS_BLOCK_PATTERNS=(
+  "rm -rf /"
+  "rm -rf ~"
+  "> /dev/sda"
+  "mkfs\."
+  "dd if="
+  ":(){:|:&};:"
+  # Database schema destruction — these flags/commands exist specifically to bypass
+  # safety checks. Treat them as catastrophic regardless of context.
+  # (Learned from Portal production data loss incident 2026-02-22)
+  "--accept-data-loss"
+  "prisma migrate reset"
+)
+
+for pattern in "${ALWAYS_BLOCK_PATTERNS[@]}"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    echo "BLOCKED: Catastrophic command detected: $pattern" >&2
+    echo "This command is always blocked regardless of safety level." >&2
+    echo "If you genuinely need to run this, the user must execute it directly." >&2
+    exit 2
+  fi
+done
+
+# --- Risky commands: behavior depends on safety level ---
+RISKY_PATTERNS=(
+  "rm -rf \."
+  "git push --force"
+  "git push -f"
+  "git reset --hard"
+  "git clean -fd"
+  "DROP TABLE"
+  "DROP DATABASE"
+  "TRUNCATE"
+  "DELETE FROM"
+  # Schema push against production — "non-destructive" additions can silently
+  # drop tables when schema/DB naming conventions are inconsistent.
+  # Use SQL ALTER TABLE for targeted production changes instead.
+  "prisma db push"
+  "prisma migrate deploy"
+)
+
+for pattern in "${RISKY_PATTERNS[@]}"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    if [ "$SAFETY_LEVEL" -eq 1 ]; then
+      # Level 1: Block and require authorization — agent executes after user confirms
+      echo "BLOCKED: Potentially destructive command detected: $pattern" >&2
+      echo "Authorization required: Ask the user whether to proceed with this operation." >&2
+      echo "Once they confirm, YOU execute the command — never ask the user to run it themselves." >&2
+      exit 2
+    else
+      # Level 2: Inject self-verification prompt (don't block)
+      # The agent must reason about whether this action is correct.
+      AGENT_IDENTITY=""
+      if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+        AGENT_IDENTITY=$(head -20 "$INSTAR_DIR/AGENT.md")
+      fi
+
+      VERIFICATION=$(cat <<VERIFY
+{
+  "decision": "approve",
+  "additionalContext": "=== SELF-VERIFICATION REQUIRED ===\nA potentially destructive command was detected: $pattern\n\nBefore proceeding, verify:\n1. Is this command necessary for the current task?\n2. Have you considered the consequences if this goes wrong?\n3. Is there a safer alternative that achieves the same result?\n4. Does this align with your principles and the user's intent?\n\nYour identity:\n$AGENT_IDENTITY\n\nIf ALL checks pass, proceed. If ANY check fails, stop and reconsider.\n=== END SELF-VERIFICATION ==="
+}
+VERIFY
+)
+      echo "$VERIFICATION"
+      exit 0
+    fi
+  fi
+done

package/src/templates/hooks/free-text-guard.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# ── Free-Text Input Guard ─────────────────────────────────────────────
+# PreToolUse hook on AskUserQuestion
+#
+# BLOCKS AskUserQuestion when the question is asking for free-text input
+# like passwords, emails, tokens, or names. These should be collected via
+# plain text output followed by waiting for the user's next message — NOT
+# via AskUserQuestion, which adds confusing multi-choice escape hatches.
+#
+# ALLOWS AskUserQuestion for legitimate multi-choice decisions.
+#
+# Structure > Willpower: training pressure makes Claude prefer structured
+# tools. Prompt instructions alone cannot reliably prevent this.
+# ──────────────────────────────────────────────────────────────────────
+
+INPUT=$(cat)
+
+RESULT=$(echo "$INPUT" | python3 -c "
+import sys, json, re
+
+try:
+    data = json.load(sys.stdin)
+    tool_input = data.get('tool_input', {})
+    questions = tool_input.get('questions', [])
+except:
+    print('allow')
+    sys.exit(0)
+
+if not questions:
+    print('allow')
+    sys.exit(0)
+
+free_text_patterns = [
+    r'\bpassword\b',
+    r'\bmaster password\b',
+    r'\bpassphrase\b',
+    r'\bapi[- _]?key\b',
+    r'\baccess[- _]?token\b',
+    r'\bauth[- _]?token\b',
+    r'\bcredential',
+    r'\b2fa\b',
+    r'\botp\b',
+    r'\bverification code\b',
+    r'\bauthenticator\b',
+    r'\bone[- ]time',
+    r'enter your ',
+    r'type your ',
+    r'provide your ',
+    r'input your ',
+    r'what(\x27s| is) your (email|password|name|token|key|code|address)',
+    r'your (bitwarden|master|vault) ',
+]
+
+decision_patterns = [
+    r'\bwhich\b',
+    r'\bprefer\b',
+    r'\bchoose\b',
+    r'\bselect\b',
+    r'\bpick\b',
+    r'\bwant to\b',
+    r'\bwould you\b',
+    r'\bshould (we|i)\b',
+    r'\bhow should\b',
+    r'\bwhat (approach|method|option|strategy)\b',
+]
+
+for q in questions:
+    text = q.get('question', '').lower()
+    is_decision = any(re.search(p, text) for p in decision_patterns)
+    is_free_text = any(re.search(p, text) for p in free_text_patterns)
+    if is_free_text and not is_decision:
+        print('block')
+        sys.exit(0)
+
+print('allow')
+" 2>/dev/null)
+
+if [ "$RESULT" = "block" ]; then
+    cat >&2 <<'BLOCKED'
+BLOCKED: AskUserQuestion cannot be used for free-text input.
+
+You asked a question that expects the user to TYPE a response (password,
+email, token, name, etc). AskUserQuestion adds multi-choice escape hatches
+beneath the input, creating a confusing UX.
+
+CORRECT APPROACH:
+  1. Output the question as plain text
+  2. STOP — do not call any tool
+  3. Wait for the user's next message — their response IS the answer
+
+AskUserQuestion is ONLY for multi-choice DECISIONS (pick A or B or C).
+BLOCKED
+    exit 2
+fi
+
+exit 0