Session Management

CLI Usage: When unsure about a CLI's interface or flags, run it with --help first. Do NOT attempt to discover functionality by reading plugin source code — doing so leads to incorrect execution from assumptions made without context of the holistic flow.

Session Management Skill

Purpose

This skill provides guidance for Claude on managing session lifecycle in the CLEAR framework. It explains token thresholds, handoff procedures, and how to manually invoke session operations.

Plugin Root Resolution

CLI commands in this skill reference $CLEAR_PLUGIN_ROOT — a .claude/settings.json env var the shell expands. The SessionStart hook persists it, but settings env vars load at session launch, so on a brand-new consumer's first session (before its next restart) the variable is empty and node "$CLEAR_PLUGIN_ROOT/build/..." fails with MODULE_NOT_FOUND.

First-session bootstrap — if $CLEAR_PLUGIN_ROOT is empty, set it inline in the same Bash call as the CLI (each Bash call is a fresh shell, so a separate export would not carry over):

export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"

Prepend it to the CLI in one shell line: export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"; <node "$CLEAR_PLUGIN_ROOT/build/..." command>. ${CLAUDE_PLUGIN_ROOT} resolves in this SKILL.md body to the actually-loaded plugin path; once the consumer restarts, $CLEAR_PLUGIN_ROOT is populated and the assignment is a harmless no-op. Reference files are left unchanged.

When to Take Action vs. Just Answer

TAKE ACTION (run scripts) when user says:

• "check my token usage" / "how much context have I used"
• "prepare session handoff" / "prepare for handoff"
• "end session early" / "wrap up this session"
• "initialize session tracking"

JUST READ FILES (no scripts) when user asks:

• "have we completed the handoff?" → Check .clear/state/session.json
• "what was in the last handoff?" → Read .clear/sessions/*.md
• "how many sessions have we had?" → Read .clear/state/session-history.json
• "what happened in session 14?" → Read the specific session file

Command Reference

Session management is implemented as bash scripts in ${CLEAR_PLUGIN_ROOT}/scripts/session/ rather than TypeScript CLIs. The architectural inversion is intentional: session events come directly from Claude Code hook bindings, so the bash layer IS the implementation, not an envelope translator. Scripts read JSON via stdin from the hook dispatcher and emit JSON to stdout (which CC interprets as either additionalContext injection or decision:block semantics, depending on hook event).

All script invocations expect JSON via stdin (session_id, cwd, plus event-specific fields). Manual snippets are documented in Manual Invocation below.

Manual Invocation

When the user requests a session action, run the appropriate script.

Script Location: scripts/session/ in the CLEAR plugin directory

Check Token/Context Usage

User says: "check my token usage", "how much context am I using"

Action: Run the session monitor script

echo '{"session_id":"manual","cwd":"'$(pwd)'","hook_event_name":"Manual"}' | "$CLEAR_PLUGIN_ROOT/scripts/session/session-monitor.sh"

Present to user: The estimated token usage percentage and prompt count.

Prepare Session Handoff

User says: "prepare session handoff", "prepare for handoff", "end session early"

Action: Run the session handoff script

echo '{"session_id":"manual","cwd":"'$(pwd)'","manual":true}' | "$CLEAR_PLUGIN_ROOT/scripts/session/session-handoff.sh"

Present to user:

• Path to the generated handoff document
• Resume command for next session
• Prompt user to review and enhance the handoff content

Initialize Session (if needed)

User says: "initialize session tracking", "start session tracking"

Action: Run the session init script

echo '{"session_id":"manual-'$(date +%s)'","cwd":"'$(pwd)'","hook_event_name":"Manual"}' | "$CLEAR_PLUGIN_ROOT/scripts/session/session-init.sh"

Present to user: Confirmation of session initialization with session number.

SessionStart Dispatcher Orchestration

The SessionStart hook does NOT call session-init.sh directly. Instead, it routes through scripts/dispatchers/session-start.sh, which fans out to multiple domain scripts and aggregates their JSON output into the additionalContext injection.

Source-aware reload behavior: the dispatcher reads a source field from stdin JSON and adjusts behavior accordingly:

Fan-out (in order):

1. session-init.sh — Creates/resumes session state, initializes thresholds from config
2. scripts/plan/plan-load.sh — Loads master-plan + active phase context
3. scripts/workpackage/workpackage-load.sh — Loads active WP detail + dependencies
4. scripts/knowledge/knowledge-load.sh — Loads recent knowledge entries + pending captures
5. sync-bridge-cli --op=load — Loads sync-state aggregator (cross-domain summary)
6. Pending-Reviews Carry-over — see subsection below
7. Prior-session handoff load — reads most recent .clear/sessions/session_*.md as resume context

When /cf-reload is invoked, it triggers this same dispatcher with source: clear, refreshing the entire context stack without reinitializing the project.

Pending-Reviews Carry-over

Closes a SessionEnd-invisibility gap: SessionEnd stdout is invisible to Claude (a Claude Code platform limitation), so the carry-over surface had to move to SessionStart where stdout IS visible.

Flow:

1. During a Claude turn, the PostToolUse hook (via dispatchers/post-tool.sh) detects edits to CLEAR-managed files. On Level A/B surfaces, it appends knowledge entry IDs needing review to .clear/state/pending-reviews.json.
2. If those reviews aren't actioned before session end, the file persists across the session boundary.
3. On the next SessionStart, dispatchers/session-start.sh reads pending-reviews.json and invokes pending-reviews-cli to render unactioned flags into the additionalContext injection.
4. Claude sees a "PENDING REVIEW" banner at session start and can act on it.

This is a load-bearing Claude-facing surface — session start may include text that requires acknowledgement before normal work resumes.

Stop Hook 3-Tier Knowledge Assessment

The Stop hook fires after every Claude response turn (not just at session close). It is bound to scripts/dispatchers/session-stop.sh, which implements a three-tier assessment of whether knowledge capture should be prompted.

Important separation from finalization: session-finalize.sh runs on SessionEnd, NOT Stop — Stop fires every turn. The Stop hook is exclusively for knowledge capture, NOT session lifecycle finalization.

Mechanism: decision:block is a JSON return value from the dispatcher's stdout ({"decision": "block", "reason": "..."}). Claude Code's hook runtime parses the JSON; when decision is block, the reason text is injected into the conversation. The emit_blocking_decision() helper in scripts/lib/common.sh emits these payloads and logs to hooks.log for observability.

Recursion guard: when Claude responds to an injected decision:block reason, the next Stop fire receives stop_hook_active: true in the stdin JSON. The dispatcher checks this guard first and exits silently to prevent infinite assessment loops.

Accumulator semantics: .clear/state/accumulator/changed-files.json (or similar — see dispatchers/post-tool.sh) accumulates changed files across turns. Level C uses this accumulation. A/B fires checkpoint the accumulator (clear-and-record). C below threshold preserves it for the next turn.

Exclusion filter: .clear/state/**, .clear/audit/**, logs/**, tmp/**, sessions/**, node_modules/**, .claude/**, .git/**, build/** are excluded BEFORE assessment runs. Project-root files matching excluded dir names (e.g., build.sh) are NOT excluded.

Diagnostics Cross-References

For session-state issues, prefer purpose-built tools over manual file reads:

• /cf-debug session — Routes to debug-cli session which validates session state integrity (e.g., dual-ID consistency, schema version, stale-active detection). Supports --repair for auto-fixable issues.
• /cf-status — Read-only formatted session summary (number, tokens, thresholds, active WP, context health). No mutations.
• sync-bridge-cli operations (--op=) — Cross-domain sync state ops: load, persist, update-workpackage, update-knowledge, link-knowledge, reconcile, reconcile-plan. Most invocations are hook-internal (see Dispatcher Orchestration); manual invocation is rare.

How Automatic Session Automation Works

All session scripts above are wired to Claude Code hooks via hooks/hooks.json and the dispatcher layer in scripts/dispatchers/. See the Command Reference table for the full script ↔ hook mapping, and the sections below for behavioral detail on SessionStart fan-out, Pending-Reviews carry-over, and the Stop hook 3-tier assessment. Manual invocation (above) is for on-demand user requests; the automation runs without explicit user intent.

Token Thresholds

The scripts monitor token consumption against these thresholds:

Understanding Session State

The scripts maintain state in .clear/state/session.json:

{
  "sessionId": "uuid-from-claude-code",
  "clearSessionNumber": 15,
  "tokenUsage": { "estimate": 0.45, "promptCount": 12 },
  "status": "active",
  "handoff": { "prepared": false }
}

Session Files Reference

Configuration

The scripts read configuration from .clear/config/session-management.yaml if it exists:

session_management:
  token_thresholds:
    warning: 0.60
    critical: 0.75
    emergency: 0.85