# Session watchdog — optional hook setup

`cai watchdog` reads the live context-fill of the current session and, past a
threshold, prints a scaffold-grounded condense brief (keep / drop / reload).

By default it only prints. To have the brief injected into the agent's context
automatically, wire it as an **opt-in** PostToolUse hook. CAI never installs this
for you — copy it yourself.

## Claude Code (PostToolUse)

Add to `~/.claude/settings.json` (adjust the `cai` path if not globally linked):

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cai watchdog --session \"$CLAUDE_SESSION_ID\" --json"
          }
        ]
      }
    ]
  }
}
```

The `--json` output carries `{ level, percent, estimate, source, brief }`. A thin
wrapper can forward the `brief` as `additionalContext` when `level` is `warn` or
`critical`, and stay silent when `ok`.

## Signal source

- Primary: the statusline bridge file `/tmp/claude-ctx-<session>.json` (written
  by the statusline hook). Pass the session id with `--session`.
- Fallback: `--transcript <path>` estimates fill from transcript size (flagged as
  an estimate).

## Thresholds

Configure in your scaffold config (defaults: warn 55%, critical 75%):

```json
{ "watchdog": { "warnPercent": 55, "criticalPercent": 75 } }
```

## Relationship to existing features

The watchdog is the live **threshold + condense brief** only. Context *selection*
and the session prompt already live in `cai session` / `session-auto`; the
watchdog reuses that machinery rather than duplicating it, and is not a
replacement for native compaction — it tells the agent what to keep when
compaction is near.