# Session Management

Session management lets the orchestrator keep track of recent delegated child
sessions so follow-up work can continue in the right specialist context instead
of starting from scratch every time.

It is enabled by default. You do not need to add anything to your config unless
you want to change how many sessions are remembered.

---

## Why It Exists

Delegation works best when specialists can continue a thread they already
understand:

- Explorer can continue investigating the same part of the codebase.
- Oracle can keep reviewing the same architecture/debugging thread.
- Fixer can continue a scoped implementation or test update.
- Librarian can continue the same documentation/API research.

Without session management, follow-up delegations usually create fresh child
sessions. That works, but the specialist may need repeated context. With session
management, the orchestrator can reuse recent child sessions when it makes sense.

---

## How It Feels in Practice

When a child task runs, the plugin remembers it under a short alias such as:

```text
exp-1
ora-1
fix-2
```

The orchestrator sees a compact reminder in its system context, for example:

```text
### Resumable Sessions
- explorer: exp-1 Search routing files
  Context read by exp-1: src/router.ts (120 lines), src/routes/api.ts (74 lines)
- oracle: ora-1 Review auth architecture
```

When a child session reads files through OpenCode's `read` tool, the reminder can
include a compact list of files that session has already inspected. This helps the
orchestrator choose the right session to resume for related follow-up work.

To keep the prompt small, read context only shows files where at least 10 lines
were read, includes line counts, and caps each remembered session to the most
recent 8 files by default. Both thresholds are configurable.

On a related follow-up, the orchestrator can reuse that session instead of
launching a fresh one. If the remembered child session no longer exists, the
plugin drops the stale entry and falls back to a new session automatically.

---

## Scope and Safety

Session management is intentionally narrow:

- It only applies to orchestrator-managed `task` delegations.
- It is scoped to the current parent orchestrator session.
- It is in-memory only and disappears when OpenCode/plugin state restarts.
- It does not change manual `@agent` calls.
- It keeps only a small number of recent sessions per specialist type.
- Missing or deleted child sessions are cleaned up automatically.
- Read context is best-effort and tracks normal OpenCode `read` tool usage, not
  arbitrary filesystem access through shell commands or external MCP tools.

This keeps the feature useful for continuity without turning child sessions into
long-lived global state.

---

## Default Behavior

By default, the plugin remembers **2 recent child sessions per specialist type**.

That means the generated starter config can stay clean:

```jsonc
{
  "preset": "openai",
  "presets": {
    "openai": {
      "orchestrator": { "model": "openai/gpt-5.5" },
      "explorer": { "model": "openai/gpt-5.4-mini" },
      "fixer": { "model": "openai/gpt-5.4-mini" }
    }
  }
}
```

Session management still works because the runtime falls back to the built-in
default.

---

## Configuration

Only add `sessionManager` if you want to change the default limits:

```jsonc
{
  "sessionManager": {
    "maxSessionsPerAgent": 2,
    "readContextMinLines": 10,
    "readContextMaxFiles": 8
  }
}
```

### `sessionManager.maxSessionsPerAgent`

| Type | Default | Range | Meaning |
|------|---------|-------|---------|
| integer | `2` | `1`–`10` | Number of recent resumable child sessions remembered per specialist type in the current parent session |

### `sessionManager.readContextMinLines`

| Type | Default | Range | Meaning |
|------|---------|-------|---------|
| integer | `10` | `0`–`1000` | Minimum number of lines read from a file before it appears in resumable-session context |

Set this lower if you want short config files to appear. Set it higher to keep
the prompt focused on substantial file reads.

### `sessionManager.readContextMaxFiles`

| Type | Default | Range | Meaning |
|------|---------|-------|---------|
| integer | `8` | `0`–`50` | Maximum number of recent read-context files shown per remembered child session |

Set this to `0` to keep session aliases but hide read-context file lists.

Use a higher value if you often run several parallel threads per specialist. Use
a lower value if you want fewer aliases in the orchestrator context.

---

## When To Tune It

Most users should leave the default alone.

Consider changing it when:

- You frequently run multiple independent Explorer/Oracle/Fixer threads in one
  long orchestrator session.
- You want the orchestrator prompt to stay smaller and prefer only one remembered
  thread per specialist.
- You are debugging session reuse behavior and want a predictable small window.

Example with a smaller memory window:

```jsonc
{
  "sessionManager": {
    "maxSessionsPerAgent": 1,
    "readContextMaxFiles": 4
  }
}
```

Example with a larger memory window:

```jsonc
{
  "sessionManager": {
    "maxSessionsPerAgent": 4,
    "readContextMinLines": 5
  }
}
```