---
name: ck-session-guard
description: Session lifecycle management — initializes environment context, injects project info into subagents, tracks usage limits, cleans up on session end. Activates automatically at session start, subagent start, and session end.
---

# ck-session-guard

Manages session lifecycle: environment detection at startup, context injection into subagents, usage limit tracking, and clean teardown. This guard runs automatically — it is not manually invoked.

## When Active

- **Session Start**: Fires once per session (startup, resume, `/clear`, compact)
- **Subagent Start**: Fires when any agent is dispatched
- **Session End**: Fires when session ends (clear, compact, user exit)
- **Usage Tracking**: Fires on each user prompt and periodically on tool use

## Don't Use When

- This is a background guard — never invoke manually
- If session context appears stale, use `/clear` to reset

---

## Session Start Behavior

Detects and injects into the session environment:

**Project Detection:**
- Project type (Node.js, Python, Go, etc.)
- Package manager (npm, yarn, pnpm, bun)
- Framework (Next.js, NestJS, FastAPI, etc.)
- Git branch, remote URL, and root directory

**Plan Resolution:**
- Active plan: explicitly set via session state — used for report paths
- Suggested plan: branch-matched hint — shown to user, NOT auto-activated
- No plan: create new using `## Naming` pattern

**Environment Variables set:**
- `CK_SESSION_ID`, `CK_ACTIVE_PLAN`, `CK_SUGGESTED_PLAN`
- `CK_REPORTS_PATH`, `CK_PLANS_PATH`, `CK_DOCS_PATH`
- `CK_GIT_BRANCH`, `CK_GIT_ROOT`, `CK_PROJECT_TYPE`
- `CK_NAME_PATTERN` — computed naming pattern for reports/plans

**Coding Level Guidelines:** If configured (levels 0–5), injects response format guidelines for output depth and style.

**User Assertions:** If configured, injects custom user rules into session context.

**Post-Compact Warning:** When session was compacted, injects a reminder:
> "Context was compacted. If you were waiting for user approval via an interactive question (e.g., a review gate), you MUST re-confirm with the user before proceeding. Do NOT assume approval was given."

---

## Subagent Start Behavior

Injects a compact context block (~200 tokens) into every dispatched agent:

```
## Subagent: {agent-type}
ID: {id} | CWD: {cwd}

## Context
- Plan: {active-plan or none}
- Reports: {reports-path}
- Paths: {plans-path}/ | {docs-path}/

## Rules
- Reports → {reports-path}
- YAGNI / KISS / DRY
- Concise, list unresolved Qs at end
- Python scripts in .claude/skills/: Use `{venv-path}`
- Never use global pip install

## Naming
- Report: {reports-path}/{agent-type}-{name-pattern}.md
- Plan dir: {plans-path}/{name-pattern}/
```

**Monorepo support:** Uses the subagent's own CWD (not process CWD) for path resolution, enabling subdirectory workflows.

---

## Session End Behavior

On `/clear`: Deletes the compact marker file to reset the context baseline for the next session. Ensures a clean slate without stale state from the previous session.

---

## Usage Tracking Behavior

Fetches Claude usage limits from the Anthropic OAuth API and writes to a local cache file (`/tmp/ck-usage-limits-cache.json`).

- Throttled: 1-minute intervals on user prompts; 5-minute intervals on tool use
- Cross-platform credential retrieval: macOS Keychain, or file-based at `~/.claude/.credentials.json`
- Cache TTL: 60 seconds
- Fails silently — never blocks the session

---

## Skill Dedup (Reference Only)

Originally designed to prevent local project skills from shadowing global versions. **Disabled** due to race conditions with parallel sessions. Any orphaned `.claude/skills/.shadowed/` directories are automatically restored at session start.

---

## Configuration

All behavior configurable in `$HOME/.claude/.ck.json`:

```json
{
  "hooks": {
    "session-init": true,
    "subagent-init": true,
    "session-end": true,
    "usage-context-awareness": true
  },
  "codingLevel": 5,
  "plan": {
    "namingFormat": "{date}-{slug}",
    "reportsDir": "plans/reports"
  }
}
```