Feature: PostToolUse hooks for automatic error issue creation

[oitray]

Summary

Add a PostToolUse hook to .claude/settings.json that intercepts MCP tool errors and automatically creates a GitHub issue in the appropriate parent repo for diagnostics and monitoring.

Teams that fork this blueprint should get error reporting out of the box — no additional setup required.

Motivation

MCP tool errors currently surface in the Claude Code session and disappear — no persistent record, no admin notification, no audit trail. This creates reliability blind spots across all catalog tools.

Self-healing infrastructure requires observability first: capture errors → create issues → (future) trigger remediation.

Proposed Implementation

Hook Configuration (.claude/settings.json)

"hooks": {
  "PostToolUse": [
    {
      "matcher": "mcp__*",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'if echo \"$CLAUDE_TOOL_RESULT\" | jq -e \".isError == true\" > /dev/null 2>&1; then TOOL=\"$CLAUDE_TOOL_NAME\"; BODY=$(echo \"$CLAUDE_TOOL_RESULT\" | jq -r \".content // .error // .\"); gh issue create --repo \"YOUR_ORG/YOUR_REPO\" --title \"🔴 Tool error: $TOOL\" --body \"**Tool:** \`$TOOL\`\\n\\n**Error:**\\n\`\`\`\\n$BODY\\n\`\`\`\\n\\n**Session date:** $(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\" --label bug; fi'"
      }]
    }
  ]
}

Teams customize YOUR_ORG/YOUR_REPO or implement per-tool routing logic (see OITApps/claude-config#23 for the full routing table pattern).

Blueprint Placement

• Hook lives in .claude/settings.json — committed to the template
• Documentation in docs/error-reporting.md explaining how to configure repo routing for a given team's tool set

Scope

• All MCP tools (mcp__* matcher)
• Silent on success — hook is a no-op unless isError == true
• GitHub only for diagnostics/monitoring
• Blueprint clones inherit automatically — no manual opt-in

Future: Self-Healing Layer (not in scope here)

Once errors land as GitHub issues:

1. GitHub Actions label watcher → diagnostic script on tool-error issues
2. Auto-close transient errors (timeouts, auth expiry)
3. Escalate persistent errors to project management tooling

Acceptance Criteria

• PostToolUse hook added to .claude/settings.json in blueprint template
• Hook fires only on isError == true, silent on success
• Error issues include: tool name, error body, UTC timestamp, bug + tool-error labels
• docs/error-reporting.md documents how teams configure repo routing
• Hook tested against an intentional MCP error
• Cross-reference: OITApps/claude-config#23 (OIT-specific implementation)