oh-my-customcode 0.19.4 → 0.20.0

package/README.md

@@ -124,7 +124,7 @@ Claude Code selects the appropriate model and parallelizes independent tasks (up
 | **QA** | 3 | qa-planner, qa-writer, qa-engineer |
 | **Total** | **41** | |
 
-### Skills (56)
+### Skills (58)
 
 | Category | Count | Skills |
 |----------|-------|--------|
@@ -137,7 +137,7 @@ Claude Code selects the appropriate model and parallelizes independent tasks (up
 | **Package Management** | 3 | npm-publish, npm-version, npm-audit |
 | **Operations** | 7 | update-docs, update-external, audit-agents, fix-refs, sauron-watch, monitoring-setup, claude-code-bible |
 | **Utilities** | 5 | lists, help, status, result-aggregation, writing-clearly-and-concisely |
-| **Quality & Workflow** | 2 | multi-model-verification, structured-dev-cycle |
+| **Quality & Workflow** | 4 | multi-model-verification, structured-dev-cycle, model-escalation, stuck-recovery |
 | **Deploy** | 2 | vercel-deploy, codex-exec |
 | **External** | 1 | skills-sh-search |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.19.4",
+  "version": "0.20.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/hooks/hooks.json

@@ -76,6 +76,10 @@
           {
             "type": "command",
             "command": "bash .claude/hooks/scripts/agent-teams-advisor.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/model-escalation-advisor.sh"
           }
         ],
         "description": "HUD statusline + R010 git delegation guard + R018 Agent Teams advisor on Task spawn"
@@ -163,6 +167,26 @@
           }
         ],
         "description": "Type check Python files with ty after edits"
+      },
+      {
+        "matcher": "tool == \"Task\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/task-outcome-recorder.sh"
+          }
+        ],
+        "description": "Record task outcomes (success/failure) for model escalation decisions"
+      },
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"Bash\" || tool == \"Task\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/stuck-detector.sh"
+          }
+        ],
+        "description": "Detect repetitive failure loops and advise recovery strategies"
       }
     ],
     "Stop": [

package/templates/.claude/hooks/scripts/model-escalation-advisor.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+set -euo pipefail
+
+# Model Escalation Advisor Hook
+# Trigger: PreToolUse, tool == "Task"
+# Purpose: Advise model escalation when failure patterns detected
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract current task info
+agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // "unknown"')
+current_model=$(echo "$input" | jq -r '.tool_input.model // "inherit"')
+
+# Session-scoped outcome log
+OUTCOME_FILE="/tmp/.claude-task-outcomes-${PPID}"
+
+# Skip if no history
+if [ ! -f "$OUTCOME_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+# Thresholds
+FAILURE_THRESHOLD=2
+CONSECUTIVE_THRESHOLD=3
+COOLDOWN=5
+
+# Count failures for this agent type
+agent_failures=0
+if [ -n "$agent_type" ] && [ "$agent_type" != "unknown" ]; then
+  agent_failures=$(grep -c "\"agent_type\":\"${agent_type}\".*\"outcome\":\"failure\"" "$OUTCOME_FILE" 2>/dev/null || echo "0")
+fi
+
+# Count consecutive failures (tail entries)
+consecutive_failures=$(tail -${CONSECUTIVE_THRESHOLD} "$OUTCOME_FILE" 2>/dev/null | grep -c '"outcome":"failure"' 2>/dev/null || echo "0")
+
+# Escalation path
+next_model=""
+cost_multiplier=""
+case "$current_model" in
+  haiku)
+    next_model="sonnet"
+    cost_multiplier="~3-5x"
+    ;;
+  sonnet)
+    next_model="opus"
+    cost_multiplier="~5-10x"
+    ;;
+  *)
+    next_model=""
+    ;;
+esac
+
+# Advise escalation
+if [ -n "$next_model" ]; then
+  should_advise=false
+  reason=""
+
+  if [ "$agent_failures" -ge "$FAILURE_THRESHOLD" ]; then
+    should_advise=true
+    reason="${agent_type} failed ${agent_failures}x with ${current_model}"
+  elif [ "$consecutive_failures" -ge "$CONSECUTIVE_THRESHOLD" ]; then
+    should_advise=true
+    reason="${consecutive_failures} consecutive failures"
+  fi
+
+  if [ "$should_advise" = true ]; then
+    echo "" >&2
+    echo "--- [Model Escalation Advisory] ---" >&2
+    echo "  Agent type: ${agent_type}" >&2
+    echo "  Current model: ${current_model}" >&2
+    echo "  ⚡ Recommended: Escalate to ${next_model}" >&2
+    echo "  Cost impact: ${cost_multiplier} per task" >&2
+    echo "  Reason: ${reason}" >&2
+    echo "------------------------------------" >&2
+  fi
+fi
+
+# De-escalation check
+if [ "$current_model" != "haiku" ] && [ "$current_model" != "inherit" ] && [ "$current_model" != "" ]; then
+  recent_successes=$(tail -${COOLDOWN} "$OUTCOME_FILE" 2>/dev/null | grep -c '"outcome":"success"' 2>/dev/null || echo "0")
+
+  if [ "$recent_successes" -ge "$COOLDOWN" ]; then
+    lower_model=""
+    case "$current_model" in
+      opus) lower_model="sonnet" ;;
+      sonnet) lower_model="haiku" ;;
+    esac
+
+    if [ -n "$lower_model" ]; then
+      echo "" >&2
+      echo "--- [Model De-escalation Advisory] ---" >&2
+      echo "  ↓ Consider: ${current_model} → ${lower_model}" >&2
+      echo "  ${recent_successes} consecutive successes" >&2
+      echo "--------------------------------------" >&2
+    fi
+  fi
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/stuck-detector.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+set -euo pipefail
+
+# Stuck Detector Hook
+# Trigger: PostToolUse, tool matches "Edit|Write|Bash|Task"
+# Purpose: Detect repetitive failure loops and advise recovery
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract tool info
+tool_name=$(echo "$input" | jq -r '.tool_name // "unknown"')
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.command // ""' | head -c 120)
+is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
+output_preview=$(echo "$input" | jq -r '.tool_output.output // ""' | head -c 200)
+
+# Session-scoped history
+HISTORY_FILE="/tmp/.claude-tool-history-${PPID}"
+
+# Create entry
+timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Generate error hash for deduplication (first 50 chars of error)
+error_hash=""
+if [ "$is_error" = "true" ]; then
+  error_hash=$(echo "$output_preview" | head -c 50 | md5sum 2>/dev/null | cut -d' ' -f1 || echo "unknown")
+fi
+
+entry=$(jq -n \
+  --arg ts "$timestamp" \
+  --arg tool "$tool_name" \
+  --arg path "$file_path" \
+  --arg err "$is_error" \
+  --arg hash "$error_hash" \
+  --arg preview "$output_preview" \
+  '{timestamp: $ts, tool: $tool, path: $path, is_error: $err, error_hash: $hash, preview: $preview}')
+
+echo "$entry" >> "$HISTORY_FILE"
+
+# Ring buffer: keep last 100 entries
+if [ -f "$HISTORY_FILE" ]; then
+  line_count=$(wc -l < "$HISTORY_FILE")
+  if [ "$line_count" -gt 100 ]; then
+    tail -100 "$HISTORY_FILE" > "${HISTORY_FILE}.tmp"
+    mv "${HISTORY_FILE}.tmp" "$HISTORY_FILE"
+  fi
+fi
+
+# --- Detection Logic ---
+
+# Only check for patterns if we have enough history
+if [ ! -f "$HISTORY_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+recent_count=$(wc -l < "$HISTORY_FILE")
+if [ "$recent_count" -lt 3 ]; then
+  echo "$input"
+  exit 0
+fi
+
+stuck_detected=false
+signal_type=""
+pattern_desc=""
+occurrence_count=0
+threshold=0
+recovery=""
+
+# Signal 1: Repeated error (same error_hash 3+ times in last 10 entries)
+if [ "$is_error" = "true" ] && [ -n "$error_hash" ]; then
+  error_repeat=$(tail -10 "$HISTORY_FILE" | grep -c "\"error_hash\":\"${error_hash}\"" 2>/dev/null || echo "0")
+  if [ "$error_repeat" -ge 3 ]; then
+    stuck_detected=true
+    signal_type="Repeated error"
+    pattern_desc="Same error appeared ${error_repeat} times in last 10 tool calls"
+    occurrence_count=$error_repeat
+    threshold=3
+    recovery="Rephrase the task or try a different approach"
+  fi
+fi
+
+# Signal 2: Edit loop (same file edited 3+ times in last 8 entries)
+if [ "$stuck_detected" = false ] && { [ "$tool_name" = "Edit" ] || [ "$tool_name" = "Write" ]; }; then
+  if [ -n "$file_path" ]; then
+    escaped_path=$(echo "$file_path" | sed 's/[.[\*^$()+?{|]/\\&/g')
+    edit_repeat=$(tail -8 "$HISTORY_FILE" | grep -c "\"path\":\"${escaped_path}\"" 2>/dev/null || echo "0")
+    if [ "$edit_repeat" -ge 3 ]; then
+      stuck_detected=true
+      signal_type="Edit loop"
+      pattern_desc="$(basename "$file_path") edited ${edit_repeat} times in last 8 calls"
+      occurrence_count=$edit_repeat
+      threshold=3
+      recovery="Try a different file or approach instead of re-editing"
+    fi
+  fi
+fi
+
+# Signal 3: Tool spam (same tool 5+ times in last 8 entries)
+if [ "$stuck_detected" = false ]; then
+  tool_repeat=$(tail -8 "$HISTORY_FILE" | grep -c "\"tool\":\"${tool_name}\"" 2>/dev/null || echo "0")
+  if [ "$tool_repeat" -ge 5 ]; then
+    stuck_detected=true
+    signal_type="Tool loop"
+    pattern_desc="${tool_name} called ${tool_repeat} times in last 8 calls"
+    occurrence_count=$tool_repeat
+    threshold=5
+    recovery="Step back and reconsider the approach"
+  fi
+fi
+
+# Output advisory if stuck detected
+if [ "$stuck_detected" = true ]; then
+  echo "" >&2
+  echo "--- [Stuck Detection] Loop detected ---" >&2
+  echo "  Signal: ${signal_type}" >&2
+  echo "  Pattern: ${pattern_desc}" >&2
+  echo "  Occurrences: ${occurrence_count}/${threshold}" >&2
+  echo "  💡 Recovery: ${recovery}" >&2
+  echo "----------------------------------------" >&2
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/task-outcome-recorder.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+set -euo pipefail
+
+# Task Outcome Recorder Hook
+# Trigger: PostToolUse, tool == "Task"
+# Purpose: Record task outcomes for model escalation decisions
+# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+
+input=$(cat)
+
+# Extract task info
+agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // "unknown"')
+model=$(echo "$input" | jq -r '.tool_input.model // "inherit"')
+description=$(echo "$input" | jq -r '.tool_input.description // ""' | head -c 80)
+
+# Determine outcome
+is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
+
+if [ "$is_error" = "true" ]; then
+  outcome="failure"
+  error_summary=$(echo "$input" | jq -r '.tool_output.output // ""' | head -c 200)
+else
+  outcome="success"
+  error_summary=""
+fi
+
+# Session-scoped outcome log
+OUTCOME_FILE="/tmp/.claude-task-outcomes-${PPID}"
+
+# Append JSON line entry
+timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+entry=$(jq -n \
+  --arg ts "$timestamp" \
+  --arg agent "$agent_type" \
+  --arg model "$model" \
+  --arg outcome "$outcome" \
+  --arg desc "$description" \
+  --arg err "$error_summary" \
+  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, description: $desc, error_summary: $err}')
+
+echo "$entry" >> "$OUTCOME_FILE"
+
+# Ring buffer: keep last 50 entries
+if [ -f "$OUTCOME_FILE" ]; then
+  line_count=$(wc -l < "$OUTCOME_FILE")
+  if [ "$line_count" -gt 50 ]; then
+    tail -50 "$OUTCOME_FILE" > "${OUTCOME_FILE}.tmp"
+    mv "${OUTCOME_FILE}.tmp" "$OUTCOME_FILE"
+  fi
+fi
+
+# Report failures to stderr
+if [ "$outcome" = "failure" ]; then
+  echo "" >&2
+  echo "--- [Task Outcome] FAILURE: ${agent_type}:${model} ---" >&2
+  echo "  ${description}" >&2
+  echo "  Error: $(echo "$error_summary" | head -c 100)" >&2
+  echo "-----------------------------------------------" >&2
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/rules/MUST-agent-design.md

@@ -26,8 +26,22 @@ source:                    # For external agents
   origin: github | npm
   url: https://...
   version: 1.0.0
+escalation:              # Model escalation policy (optional)
+  enabled: true          # Enable auto-escalation advisory
+  path: haiku → sonnet → opus  # Escalation sequence
+  threshold: 2           # Failures before advisory
 ```
 
+### Escalation Policy
+
+When `escalation.enabled: true`, the model-escalation hooks will track outcomes for this agent type and advise escalation when failures exceed the threshold. This is advisory-only — the orchestrator decides whether to accept the recommendation.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | false | Enable escalation tracking for this agent |
+| `path` | haiku → sonnet → opus | Model upgrade sequence |
+| `threshold` | 2 | Failure count before escalation advisory |
+
 ## Memory Scopes
 
 | Scope | Location | Git Tracked |

package/templates/.claude/skills/model-escalation/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: model-escalation
+description: Advisory model escalation based on task outcome tracking
+---
+
+# Model Escalation Skill
+
+Tracks task outcomes and advises model upgrades when failures are detected. **Advisory-only** — the orchestrator makes the final decision (R010).
+
+## Escalation Path
+
+```
+haiku → sonnet → opus
+```
+
+## Trigger Conditions
+
+| Condition | Action |
+|-----------|--------|
+| 2+ failures with same model for same agent type | Advise escalation |
+| 3+ consecutive failures across any agent type | Advise global escalation |
+| Sustained success after escalation | Advise de-escalation |
+
+## Thresholds
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `failure_threshold` | 2 | Failures before escalation advisory |
+| `consecutive_threshold` | 3 | Consecutive failures for global advisory |
+| `cooldown_tasks` | 5 | Successes before de-escalation advisory |
+
+## Cost Guard
+
+- Advisory includes estimated cost multiplier
+- De-escalation suggested after sustained success at higher tier
+- Cost tracked per session via PPID-scoped temp file
+
+## Architecture
+
+```
+PostToolUse (Task) → task-outcome-recorder.sh
+  Records: agent_type, model, success/failure, error_summary
+  Storage: /tmp/.claude-task-outcomes-$PPID (JSON lines, max 50)
+
+PreToolUse (Task) → model-escalation-advisor.sh
+  Reads outcomes → counts failures → advises escalation via stderr
+  Advisory only — never blocks, never modifies tool input
+```
+
+## Advisory Format
+
+```
+--- [Model Escalation Advisory] ---
+  Agent type: {agent_type}
+  Current model: {current_model}
+  Recent failures: {count}/{threshold}
+  ⚡ Recommended: Escalate to {next_model}
+  Cost impact: {multiplier} per task
+---
+```

package/templates/.claude/skills/stuck-recovery/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: stuck-recovery
+description: Detect stuck loops and advise recovery strategies
+---
+
+# Stuck Recovery Skill
+
+Detects when tasks are stuck in repetitive failure loops and advises recovery strategies. **Advisory-only** — the orchestrator decides the action (R010).
+
+## Detection Signals
+
+| Signal | Pattern | Threshold |
+|--------|---------|-----------|
+| Repeated error | Same error message appears 3+ times | 3 occurrences |
+| Edit loop | Same file edited 3+ times in sequence | 3 edits |
+| Agent retry | Same agent_type fails 3+ times consecutively | 3 failures |
+| Tool loop | Same tool called 5+ times with similar input | 5 calls |
+
+## Recovery Strategies
+
+| Strategy | When | Action |
+|----------|------|--------|
+| Fresh context | Repeated same error | Suggest rephrasing the task |
+| Model escalation | Agent retry loop | Trigger model-escalation advisory |
+| Alternative approach | Edit loop detected | Suggest different file/method |
+| Human intervention | All automated strategies exhausted | Ask user for guidance |
+
+## Architecture
+
+```
+PostToolUse (Edit, Write, Bash, Task) → stuck-detector.sh
+  Tracks: tool_name, file_path, error_hash, agent_type
+  Storage: /tmp/.claude-tool-history-$PPID (JSON lines, max 100)
+  Detection: sliding window pattern matching
+  Output: stderr advisory when loop detected
+```
+
+## Advisory Format
+
+```
+--- [Stuck Detection] Loop detected ---
+  Signal: {signal_type}
+  Pattern: {description}
+  Occurrences: {count}/{threshold}
+  💡 Recovery: {suggested_strategy}
+---
+```
+
+## Integration
+
+- Complements model-escalation skill (escalation is one recovery strategy)
+- Respects R010 (advisory only, orchestrator decides)
+- Uses same PPID-scoped temp file pattern as other hooks
+- Works with task-outcome-recorder.sh data when available

package/templates/manifest.json

@@ -18,7 +18,7 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 56
+      "files": 58
     },
     {
       "name": "guides",