debug

name	debug
description	Diagnose agent session issues — show recent logs, tool errors, and configuration problems
when_to_use	When the agent is behaving unexpectedly, a tool keeps failing, permissions are being denied unexpectedly, or the user wants to understand what happened in the current session.
argument-hint	optional: specific issue to investigate, e.g. 'bash tool always denied'
context	inline
allowed-tools	["read_file","glob","grep_file","bash"]
disable-model-invocation	true

Diagnose the current session and report findings.

$ARGUMENTS

Step 1: Check settings files

Read the following files (skip if absent):

• ~/.claude/settings.json — user-level permissions, hooks, env vars
• .claude/settings.json — project-level settings
• .claude/settings.local.json — local overrides

Look for:

• Permission rules that might be blocking tool calls (deny entries).
• Hooks that might be exiting non-zero and aborting tool calls.
• Missing or incorrect environment variables.

Step 2: Scan for recent tool errors

Run:

# Show last 50 lines of the agent log if it exists
ls -t /tmp/ai-coding-*.log 2>/dev/null | head -1 | xargs tail -50 2>/dev/null || echo "No log file found"

Look for patterns:

• permission denied → tool blocked by a deny rule or OS permission
• exit code → command failed; note the exit code and stderr
• interrupt → tool was suspended waiting for user approval

Step 3: Inspect recent git state (if relevant)

git status --short 2>/dev/null | head -20
git log --oneline -5 2>/dev/null

This helps confirm whether file-write tools actually worked.

Step 4: Report

Structure the report as:

Session summary

• Working directory
• Settings files found and their scopes
• Number of permission rules (allow / deny)
• Hooks registered

Issues found

For each issue:

• Symptom: what the user observed
• Root cause: what the diagnostic found
• Fix: exact change to make (e.g., add "allow": ["bash(go *)"] to .claude/settings.json)

No issues found

If nothing is wrong, say so and describe what was checked.