session

Carry the durable part of a session across /clear, hold open loops until they land. dump composes a small handover doc from the live conversation, writes it to .claude/state/session/<slug>.md, ends by printing /clear. The session-restore.js hook (SessionStart, matcher clear) injects that doc into the fresh session, so restore is free. Implementation detail — diffs, tool output, exploration transcript, abandoned approaches — dropped on purpose; only the decision that settled an approach survives.

Runs inline, never context: fork. Conversation history is the authoritative source for what changed, what was decided, what never landed; a forked run would see none of it.

NOT for: auto-compact survival (compaction.md skill contract); reviving a finished conversation (native /resume). Boundary table in the notes section below.

• $ARGUMENTS: required. Six modes:
  • dump [name] — sweep, compose and write handover doc, set LATEST pointer, print /clear next step. name optional; unnamed dumps derive a slug from branch + UTC timestamp.
  • recall [name] — print a stored handover into context, mark it consumed. Named, or LATEST when omitted. Manual path for dumps the hook skips.
  • list — table of stored handovers (slug, age, consumed) plus open parked items.
  • park <idea> — append one open-loop item to .claude/state/session/PARKED.md. No dump needed; works any time.
  • sweep — read conversation for unlanded ideas, unanswered questions, pending tasks; report them, offer to park.
  • drop <item> — fuzzy-match a parked item, remove it, log the closure.

• Store dir: .claude/state/session/ (project-local; .claude/state/ gitignored, same as session-context.md)
• Item store: .claude/state/session/PARKED.md — one bullet per open item; survives every dump, never auto-deleted
• Pointer file: .claude/state/session/LATEST — plain text, slug of most recent unconsumed dump. Blank or missing = nothing pending.
• Closure log: .claude/state/session/dropped.jsonl — one JSON line per drop
• Doc size cap: ~1.5K tokens (~75 lines). Compress prose, never drop a decision.
• Hook auto-restore window: unconsumed and created within 30 min. Outside it, recall is the manual path.
• Hook truncation threshold: ~8000 chars — above it hook injects ## Goal + files table + ## Next step + a → /foundry:session recall <slug> pointer instead of the whole doc.
• Stale threshold: 14 days (⚠ stale prefix when listing) — applies to handover docs and parked items
• Delete threshold: 30 days — handover docs only, swept during list. Parked items never auto-deleted; only drop removes one.
• Files-table row cap: 25 (over that, group by directory, state elided count)

Task hygiene — task tools may be deferred; load before first use: ToolSearch(query="select:TaskList,TaskCreate,TaskUpdate,TaskGet", max_results=4). Call TaskList first and triage each task it returns: completed if work clearly done, deleted if orphaned, keep in_progress only if genuinely continuing. Never spend a turn on bookkeeping alone — every TaskCreate/TaskUpdate ships in the same response as the next substantive tool call; one exception, TaskUpdate(completed) immediately before a long output block (rules/task-lifecycle.md).

Step 0: Validate and dispatch mode

Extract first word of $ARGUMENTS as MODE.

If MODE matches:

• dump (alias: save) → Mode: dump
• recall (aliases: restore, load) → Mode: recall
• list → Mode: list
• park → Mode: park
• sweep → Mode: sweep
• drop (alias: archive) → Mode: drop

Unsupported flag check — after extracting mode token, scan the tokens after it for --<token> patterns — except in park and drop, whose whole remainder is free-text payload (an idea or item may itself contain --), never flags. Found: invoke AskUserQuestion with question text ! Unknown flag(s): `--<token>`. Supported modes: dump, recall, list, park, sweep, drop. — (a) Abort (stop, re-invoke correctly) · (b) Continue ignoring (skip unknown flags, proceed with recognized mode).