---
name: session-management
description: "Reset the current session, list past sessions, continue a previous session, or read the session memory. Triggers when the owner says 'start a new session', 'continue the last session', 'pick up where we left off', 'what were we doing last time', or asks about session state."
---

# Session management

Invoked by the admin agent directly.

This skill wraps the session tools and carries the discipline that keeps long-running work coherent across sessions. The platform handles a lot of session machinery automatically: this skill is for the moments where the owner names a session intent directly.

## The tools

| Tool | Purpose |
|---|---|
| `session-reset` | Clear the current session and return to idle. |
| `session-list` | List recent sessions with metadata. |
| `session-resume` | Resume a specific session by `sessionId`. |
| `session-compact-status` | Read the compaction state of the current session: how much context has been compacted, what remains. |

## Resetting the session

When the owner asks to start a new session, clear the conversation, or reset, call `session-reset`. Do not ask for confirmation. After the tool call, say nothing further; the UI clears and returns to idle.

**Before suggesting a reset (e.g. after a plugin activation, when context has drifted), persist every actionable finding from the current conversation to its durable store first.** Compaction saves a session summary, but summaries are lossy: decisions, working state, and unfinished threads must be captured explicitly before the context window is cleared. Write open tasks via `work-create`, profile updates via `profile-update`, and any other graph state. Then tell the owner what will carry into the new session (the summary and the open tasks via `<previous-context>`) and suggest the reset.

## Continuing a previous session

When the owner asks to continue, pick up, resume, or carry on:

- **Most recent session.** Call `session-list` with `limit: 1`, then `session-resume` with the returned `sessionId`.
- **Specific session by name or topic.** Call `session-list` with a higher limit, identify the matching session, then `session-resume`.
- **No sessions found.** Tell the owner. Do not improvise by reading `<previous-context>`, searching memory, or re-researching prior work.

## Trusting the session summary

When `<previous-context>` is present in the system prompt, the platform has injected a recent session summary and the open tasks at session end. The platform rejects stale summaries older than 48 hours; when the summary is present, it is recent and trustworthy.

- Trust the summary for state orientation. Do not re-verify claims it already describes.
- Pick up from the state the summary describes. Redundant `memory-search` or other tool calls for information already in the summary waste the owner's time.
- Use the summary to greet the owner with awareness of prior work and outstanding tasks.

When `<previous-context>` is absent, Neo4j was unreachable or no prior context exists: proceed normally, using tool calls to establish state.

## The recovery context block

A `<recovery-context>` block on the user-message side appears whenever the previous turn was aborted by a stall recovery. It is the authoritative description of what failed, what was incomplete, and what to do now.

- The **resume variant** announces that a synthetic tool result for the in-flight `tool_use_id` was just pushed above this message. Read it for the completed-work summary, then resume by re-issuing the next pending step concretely.
- The **handoff variant** carries an LLM-generated continuation summary describing what was happening before the abort.

In both shapes, the next operator message means resume the work. Never treat it as empty, never ask "what would you like to do?", never wait for direction. Do not re-research the blocker. Do not call `session-list` to figure out what was happening.

## The api-wait-ping liveness gate

The platform suppresses a heartbeat-driven stall fire while the SDK API request is still alive, bounded by a 600-second cap. When the cap forces an abort, the synthetic tool result names "API request stayed alive past the 600 s cap without producing tokens". This is upstream API latency, not specialist failure. Do not infer that the specialist's approach was wrong from a long stall; many stalls are not the subagent's fault.

## In managed context mode

Conversation history is provided inside `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.

## What this skill does not do

It does not edit summaries, delete past sessions, or modify the recovery-context block. These are platform-owned mechanics.