[FEATURE]: Ephemeral, tool-capable sessions for the V2 plugin API #58060

Related issues

• [FEATURE]: Add explicit hidden or ephemeral sessions for plugin background tasks #40863 — the same plugin use case, proposing hidden / ephemeral fields. It was auto-closed after 60 days of inactivity; the close comment is a bot, not a maintainer decision.
• Support session visibility independently of parentage #39911 — session visibility independent of parentage (hidden).
• [FEATURE]: Add an ephemeral mode that does not persist sessions locally #53921 — an ephemeral mode that does not persist sessions locally.
• [FEATURE]: Ephemeral one‑off sessions for opencode run (happy to implement) #4489 — ephemeral opencode run (closed; PR feat(opencode): OpenCode ephemeral sessions #43656 closed unmerged).

The problem

Plugins often need to run a short, tool-using agent turn as an internal step: consolidate memory, review a diff, classify files, etc. The V2 plugin API has no way to do that without creating a normal, persisted session.

ctx.generate.text is not enough. The docs describe it as generating text "without creating a session, invoking tools, or adding to session history". A tool loop needs a session.

The only workaround is a child session:

const child = await ctx.session.create({ parentID, agent, model })
try {
  await ctx.session.prompt({ sessionID: child.id, text })
  await ctx.session.wait({ sessionID: child.id })
  const messages = await ctx.session.context({ sessionID: child.id })
} finally {
  await ctx.session.remove({ sessionID: child.id })
}

This is not a temporary session:

1. parentID is hierarchy, not visibility. The child is persisted from creation and appears in unfiltered GET /api/session / ctx.session.list, and in any client that does not filter by parentID.
2. Nothing guarantees cleanup. If the plugin is unloaded, crashes, or the server exits mid-run, the session and its messages, tool output and snapshots remain. remove only runs if the plugin reaches finally.
3. Parentage and visibility are conflated. A background controller may be top-level; a child may need to be visible.
4. The write happens before plugin hooks, so a hook cannot prevent persistence.

Proposed API

Add two independent properties to ctx.session.create (and POST /api/session):

const temp = await ctx.session.create({
  title: "memory-consolidation",
  agent: "build",
  hidden: true,      // keep it out of user-facing pickers/history
  ephemeral: true,   // do not leave a durable session/message record
})

await ctx.session.prompt({ sessionID: temp.id, text: "..." })
await ctx.session.wait({ sessionID: temp.id })
const messages = await ctx.session.context({ sessionID: temp.id })

Semantics

• hidden: true — excluded from user-facing session lists, pickers and live session events by default; addressable by ID; list APIs accept includeHidden; persistence unchanged. This is the shape proposed in Support session visibility independently of parentage #39911.
• ephemeral: true — the session exists only for its lifetime. Tools, permissions, prompt, wait, context and interrupt work normally, but the server owns cleanup: on completion, cancellation, a TTL, plugin unload and process exit. After that there is no recoverable session or message row. Session snapshots and tool artifacts are cleaned up with it. Implies hidden.
• parentID remains independent: an ephemeral/hidden session can be top-level; a child can be visible.
• Optional convenience for the common one-shot case: ctx.session.run({ prompt }) returning the final assistant text, implemented on top of an ephemeral session. Not required if the create properties exist.

Observability: ephemeral does not have to mean "no logs". Server logs, traces and usage accounting can still record the run; the request is about not polluting user session history and not leaving a recoverable conversation.

Acceptance criteria

• A plugin can create a session, run a prompt that calls tools, wait, read the result, and leave no user-facing session in GET /api/session or ctx.session.list.
• Cleanup happens on completion, cancellation, plugin unload/crash and server exit, not only when the plugin reaches finally.
• hidden sessions are excluded from the TUI/app root session lists but remain readable by ID.
• hidden / ephemeral are independent of parentID.
• Normal sessions behave exactly as today.

Environment

OpenCode 2.1.0, @opencode/plugin 2.1.2.