# session-health-full-util — Comprehensive Health Analyst

**Agent file:** [`agents/session-health-full-util.md`](../../../../agents/session-health-full-util.md)

**Invoked by:** `session-health-util` (Tier 2 — only when quick evaluator returns `escalate`)

**Hidden:** Yes (internal infrastructure, not user-facing)

## Purpose

Performs a comprehensive health evaluation of a single session across three dimensions — timing, tool usage, and content — fetching its own message history. Uses the `auto-agents-system` skill for contextual awareness of what each agent type is supposed to achieve, enabling accurate classification of states that require deeper analysis (e.g. distinguishing a supervisor paused between cycles from a worker stuck mid-task).

## Data Fetched

```bash
session_messages.ts \
  --session-id {id} \
  --limit 10 \
  --reasoning-max 400 \
  --tool-output-max 300 \
  --no-patches
```

10 most recent messages: reasoning truncated to 400 chars, tool output to 300 chars. Step boundaries included (needed for timing). Patches excluded (no health signal).

## Evaluation Dimensions

### Timing
- Computes `minutes_inactive` from `collected_at_ms - last_active_ms`
- Checks `step_finish.reason` on the most recent step: `"tool-calls"` = waiting on results (never stuck), `"stop"` = model finished
- Classifies as: `active` / `waiting_on_tool_calls` / `stuck`

### Tools
- Counts total calls, error rate, retry loops, permission errors, cascading failures
- Classifies as: `ok` / `warning` / `degraded`

### Content
- Reads text and reasoning with full system context from the skill
- Identifies: progress signals, completion signals, permanent blocks, degraded operation patterns
- Classifies as: `ok` / `idle` / `finished` / `unhealthy` / `errored`

## Precedence Table

| Condition | health_state |
|-----------|-------------|
| Content shows permanent block | `errored` |
| Timing stuck + no explanation | `stuck` |
| Tools degraded OR content unhealthy | `unhealthy` |
| Idle + clear completion for this agent type | `finished` |
| Idle + supervisor (expected to pause) | `idle` |
| Idle + more work remains | `idle` |
| Busy + waiting on tool calls + no errors | `healthy` |
| Busy + recently active + no errors | `healthy` |
| Mixed/unclear signals | `healthy` (default) |

## Input (prompt from session-health-util)

| Field | Description |
|-------|-------------|
| `session_id` | Session ID (agent fetches its own messages) |
| `title` | Full session title |
| `tag` | Extracted tag or null |
| `status` | `busy` or `idle` |
| `last_active_ms` | Epoch ms of last activity |
| `collected_at_ms` | Epoch ms when snapshot was taken |
| `idle_threshold_minutes` | Stuck threshold in minutes |

## Output

```json
{
  "session_id": "ses_abc123",
  "title": "[AUTO-IMP-ISSUE-42] task-implementor",
  "tag": "AUTO-IMP-ISSUE-42",
  "status": "idle",
  "last_active_ms": 1776700000000,
  "minutes_inactive": 12.3,
  "health_state": "finished",
  "summary": "PR created and issue moved to In Review; task conclusively complete.",
  "signals": {
    "timing": { "verdict": "active", "minutes_inactive": 12.3, "last_step_reason": "stop" },
    "tools": { "verdict": "ok", "total_calls": 14, "error_count": 0, "has_loops": false, "has_permission_errors": false },
    "content": { "verdict": "finished", "is_making_progress": false, "shows_completion": true, "shows_permanent_block": false, "shows_degraded_operation": false }
  }
}
```

## Skill loaded

`auto-agents-system` — critical for understanding what `finished` means for each agent type and distinguishing supervisor idle cycles from worker completion.
