log-agent-issue

Log Agent Issue

Structured issue logger for subagents. Appends JSONL entries to ~/.claude/logs/agent-issues.jsonl.

When to Log

Log issues when you encounter:

• error — Tool failures, timeouts, unexpected exceptions
• warning — Skipped steps, degraded results, fallback paths taken
• info — Notable events worth tracking (optional, use sparingly)

How to Log

Pipe a JSON payload to the script via Bash with run_in_background: true:

echo '{"agentId":"<your-agent-id>","issues":[{"type":"error","message":"<what happened>","toolName":"<tool>","context":{"key":"value"},"suggestion":"<how to fix>"}]}' | bun ${CLAUDE_PLUGIN_ROOT}/src/log-issue.ts "${CLAUDE_SESSION_ID}" 2>/dev/null

Payload Shape

{
  "agentId": "triage-worker",
  "issues": [
    {
      "type": "error | warning | info",
      "message": "Human-readable description",
      "toolName": "optional — MCP tool that failed",
      "filePath": "optional — file involved",
      "context": "optional — object with extra details",
      "suggestion": "optional — remediation hint"
    }
  ]
}

Rules

• Always use run_in_background: true — never block on logging
• Always include 2>/dev/null — silent failure, never interrupt workflow
• Keep messages concise — one sentence, actionable
• Batch related issues — use the issues array, don't make multiple calls
• The script adds timestamp and sessionId automatically