oh-my-opencode-slim/docs/session-management.md

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:

exp-1
ora-1
fix-2

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

### Resumable Sessions
- explorer: exp-1 Search routing files — Found route handlers and middleware entry points.
- oracle: ora-1 Review auth architecture — Reviewed auth flow and token refresh trade-offs.

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.

Child agents are asked to return a short <context_summary> metadata block as the final standalone block in delegated task results. The context summary should capture the concrete context now present in that child session, such as files inspected, findings, decisions, or state it can recall if resumed. It is capped to keep prompt usage bounded. The plugin stores that summary when present, strips the metadata from the visible result, and falls back to the original task label if the agent omits it.

---

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.

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:

{
  "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 limit:

{
  "sessionManager": {
    "maxSessionsPerAgent": 2
  }
}

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

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:

{
  "sessionManager": {
    "maxSessionsPerAgent": 1
  }
}

Example with a larger memory window:

{
  "sessionManager": {
    "maxSessionsPerAgent": 4
  }
}