session-health

name	session-health
description	Check whether the current session has coherent guidance, focus, handoff state, working-tree ownership, and enough context to proceed safely. Use when starting, resuming, or diagnosing a confused session. Not for auditing the machine or deployed AI infrastructure; use $system-audit.
allowed-tools	["Read","Glob","Bash(ls*, cat*)"]

Context Status: Session Health Check

On-demand diagnostic showing context usage, preservation state, and open work items. Fast and lightweight — no vault queries.

What to Check

1. Context Usage Estimate (host-aware)

Use the active client's native context meter when it is exposed. A client adapter may provide a tool-call counter, but it is optional and must never be treated as shared memory. If no meter is available, report SKIPPED (client does not expose context telemetry); do not guess a percentage from conversation length.

Calculate:

• Tool calls so far
• Estimated percentage (calls / 150)
• Which thresholds have fired (from the fired array)
• Time since last warning

2. Active Plan

Find the latest file in log/plans/:

• If found: show filename, first 3 lines, and whether it contains "APPROVED" or is still "DRAFT"
• If none: report "No active plan"

3. Latest Session Log

Find the latest non-compact .md file in log/ (skip files with -compact in the name):

• If found: show filename and first 3 lines
• If none: report "No session log found"

4. Focus Freshness

Check when .context/current-focus.md was last modified:

• Show the modification date
• If older than 3 days: warn "Focus file is stale — consider running update-focus"
• Show the first 5 lines (headline)

5. Preservation and Continuity

Verify the client-neutral continuity files first: applicable root guidance, .context/ai-handoff.md, .context/current-focus.md, latest approved plan, and portable memory index. Then read docs/reference/ai-surface-availability.md or run the staged AI-infrastructure doctor to report each client hook adapter as CONFIGURED, UNAVAILABLE, or NOT APPLICABLE. Missing optional lifecycle hooks are informational when the files-first layer is healthy.

6. Open Loops

Count unchecked items (- [ ]) in .context/current-focus.md:

• Report the count
• If > 5: warn "Many open loops — consider triaging"

Output Format

Present as a compact status panel:

## Session Health

| Metric | Value |
|--------|-------|
| Context usage | ~XX% (N/150 tool calls) |
| Thresholds fired | none / info / warning / critical |
| Active plan | filename (DRAFT/APPROVED) / none |
| Latest log | filename / none |
| Focus freshness | N days ago / stale warning |
| Open loops | N items |

### Preservation Hooks

| Hook | Status |
|------|--------|
| Files-first continuity | HEALTHY / DEGRADED |
| Current client lifecycle adapter | CONFIGURED / UNAVAILABLE / NOT APPLICABLE |
| Context telemetry | AVAILABLE / SKIPPED |

### Recommendations

[Only if there are issues — e.g., stale focus, missing hooks, high context usage]

7. Compaction Guidance

When context is high (>60%), include these reference tables in the output:

When to compact:

Phase Transition	Compact?	Why
Research to Planning	Yes	Research context is bulky; plan is the distilled output
Planning to Implementation	Yes	Plan is in a file; free up context for code
Implementation to Testing	Maybe	Keep if tests reference recent code
Debugging to Next feature	Yes	Debug traces pollute context
Mid-implementation	No	Losing file paths and partial state is costly
After a failed approach	Yes	Clear dead-end reasoning

What survives compaction:

Persists	Lost
CLAUDE.md / AGENTS.md + rules	Intermediate reasoning
Task list	File contents previously read
MEMORY.md + .context/	Multi-step conversation context
Git state	Tool call history
Files on disk	Verbal preferences
.context/ai-handoff.md	—

When to Use

• When the context monitor fires a warning
• Before starting a large task (to check remaining capacity)
• After resuming a session (to verify state was preserved)
• When unsure if preservation hooks are working