125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
---
|
||
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"
|
||
}
|
||
}
|
||
```
|