[FEATURE] Session API

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• Related but not identical requests found and reviewed: #29145 (URI handler to open new sessions programmatically), #20132 (expose session ID programmatically), #24947 (claude inject — send prompts to a running session externally), #30498 (session-start hook), #36117 (/new to start a named session), #33165 (programmatic session rename). None of them cover creating and querying an ordinary, first-class session (Cowork task or Claude Code session) from within another running session.
• [x] This is a single feature request (not multiple features)

Problem Statement

When a session needs to do isolated, well-scoped background work — e.g. scanning hundreds of files in a personal knowledge-management vault for structural drift, or running a bulk analysis — there's currently no way to hand that work off to a genuinely separate, independently trackable session. Everything available today is a workaround with a real gap:

• Sub-agents (Agent tool): run synchronously inside the parent session. Their internal steps are invisible to the user by design, but so is their existence — there's no independent, user-visible identity for a sub-agent run. The parent session has to manually relay a summary back into the conversation, which either clutters the chat (if verbose) or hides the work entirely (if terse).
• Scheduled tasks: the closest built-in approximation. A one-shot task (fireAt) does create a separate, trackable unit with its own run history under "Scheduled." But the tool a session uses to create one has no model parameter, so a session can't request a specific (e.g. cheaper) model — only the user can choose a model, manually, through the UI after the fact. The UX also doesn't behave like an ordinary session: finished runs "disappear" from view and need Scheduled → task → history → pin to resurface.
• Claude Code agent teams (teammates): scoped to one lead session's lifetime, can't spawn their own teammates, have no session resumption for in-process teammates, and explicitly can't run background work that outlives the lead's process. Not independently persistent.
• Managed Agents API (platform.claude.com/docs/en/managed-agents): already has the right shape — create a session, send it events, list/retrieve/archive/delete sessions — but it's scoped to a separate product (custom agent + environment definitions for developers), not callable from inside a Cowork or Claude Code session, and not the same session/task list a user is already looking at.

None of these let a session say "start a normal session for this piece of work, and let me (or the user) check on it independently, wherever we look" — without either hiding the work completely or accepting real UX/cost friction.

Proposed Solution

The deeper issue behind all of the examples above: sub-agents, agent teams, one-shot/scheduled tasks, Managed Agents sessions, Claude Code's local claude --bg background agents, a Cowork task, and a Claude.ai chat are all, fundamentally, a session. Today each of these is its own separate, independently-implemented system with its own quirks, rather than a thin front-end over one shared primitive. Unifying them behind a single, simple Session API wouldn't require inventing new UI at all — every existing surface (the Cowork sidebar, the Scheduled list, the Claude Code CLI, the VS Code extension, the agent-teams panel) could keep its current look and just render from the same underlying store. As a side effect, this would very likely fix a lot of currently inconsistent/broken session-rendering behavior across surfaces, simply because there'd be one correct backend implementation instead of several independent, partial ones (see Additional Context for concrete examples of this fragmentation).

Concretely, expose a lightweight Session API, callable from within a running Cowork or Claude Code session, with two operations:

1. Create session — start a new, ordinary session (not a sub-agent, not a scheduled task, not a teammate) with a given prompt/context. Crucially, none of today's special cases — a background task, a sub-agent, a multi-agent teammate, a session that writes files — should be architecturally distinct kinds of thing with hard-coded, mechanism-specific visibility rules (sub-agents always hidden, scheduled tasks always tucked under "Scheduled," etc.). They're all just sessions; whether a given one is visible/trackable to the user should be a simple, per-session, user-controlled preference ("show me this" vs. "keep this silent"), not something baked into which of the many current mechanisms happened to spawn it. Concretely, the resulting session should:

• Appear in the same session/task list a user-started session would appear in, on every client (web, desktop, mobile) — by default, or opt-in/opt-out per creation call, at the user's choice.
• Support choosing a model at creation time (including the cheapest available model), so a session can hand off well-scoped, mechanical work without paying for a bigger model than it needs.
• Respect the same permission/security boundaries as a normal session (connected folders, network egress policy, connector permissions) — this is not a request to bypass any existing safety control.

1. Query sessions — list existing sessions and read their metadata/transcript/output (status, start/end time, model used, token usage, final result), callable both from a running session and from external tooling. Critically, this should be uniform across every Claude surface — Cowork, Claude.ai chat, Claude Code CLI, Claude Code IDE integrations, Managed Agents — so a single external integration can enumerate and archive all of a user's Claude session history in one place, instead of needing a different, product-specific export mechanism per surface. (Unifying with non-Claude tools, e.g. Google/Perplexity, is out of scope for Anthropic to solve — this request is only about Claude's own surfaces being consistent with each other.)

In short: make the Managed-Agents-style session create/list/retrieve primitive reachable from inside the product a user is already working in, targeting the same session list they already see, instead of requiring a separate product surface with its own agent/environment setup.

Alternative Solutions

Workarounds tried and rejected during the conversation that led to this request:

• Delegating to a Haiku sub-agent and relaying a full or short summary back into the chat — works for cost/model control, but the sub-agent's existence is invisible outside the parent session; nothing to independently check on later.
• One-shot scheduled tasks (fireAt) — closest existing approximation, but no programmatic model selection and real sidebar/UX friction (see Problem Statement).
• Standing up a Managed Agents agent + environment just to get session create/query for otherwise-interactive Cowork usage — technically possible, but disproportionate setup for what should be a lightweight capability, and produces a session that isn't the one in the user's normal Cowork/Claude Code session list.
• UI automation of the Claude Desktop app (it's Electron-based, so in principle attachable via Chrome DevTools Protocol if launched with a debug port) — considered and rejected: no documented/supported debug-port flag for the shipped app, would require reverse-engineering an undocumented internal API, is fragile across app updates, and is exactly the kind of unsupported workaround this feature request is meant to make unnecessary.
• Claude Code's local claude --bg background agents (managed via claude agents) — a different product surface entirely, with its own local session tracking; not connected to Cowork's session list, and not reachable from a Cowork session's sandboxed code-execution environment (which, by design, only ever holds short-lived, scoped tokens, never full account credentials).

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

This isn't a one-off need tied to a single project — it's a recurring pattern across essentially every kind of session I run, Cowork and Claude Code alike, any time a piece of work is (a) well-scoped and mechanical enough to hand off, and (b) something I want to keep working alongside rather than wait for inline. A few concrete instances:

• Knowledge-management vault (Cowork): I maintain a personal Obsidian vault ("LCARS") for project planning. Periodically I need to check whether ~150+ Issue/Project files still match their current templates, or scan the vault for checklist items that look like real tasks but aren't tagged correctly — both are large, mechanical, read-only analyses across many files.
• Coding (Claude Code): while actively working on a feature in my main session, I want to hand off things like "run the full test suite and report failures," "search the whole codebase for every place a deprecated API is still used and summarize," or "do a read-only review pass over this large diff" — without blocking my current train of thought, and without that work being invisible sub-agent output I only see once I explicitly ask for it.
• Pure discussion sessions (my most common case): I regularly keep one session open purely to think through and discuss a solution — it writes no files at all, not even a plan document. Once the discussion converges on something concrete, that session drafts prompts for follow-up work (writing the actual code, running a feasibility test, etc.), and today I have to copy those prompts out and paste them into new sessions myself, by hand, one at a time. If I instead let the discussion session dispatch that work itself via a sub-agent, I hit the same core problem from the other direction: the sub-agent's tool calls, file edits, and system output end up spilling into the discussion session anyway, which is exactly the pollution I was trying to keep out of it by keeping it a pure-discussion session in the first place.
• Unified session archive: I keep a personal archive of every AI session I have — across Claude, Google/Gemini, Perplexity, and others — as one note per session in the same vault. My actual goal spans all of those tools, and I don't expect Anthropic to solve the cross-vendor part (there's no way for Claude to reach into Google's or Perplexity's session data, nor should this request ask for that). What Anthropic can fix, and what makes this unnecessarily hard today, is that Claude itself doesn't have one clear, uniform session API across its own surfaces — Cowork, Claude.ai chat, and Claude Code each behave differently for session listing/export, so even archiving just the Claude portion of my history requires separate, product-specific handling instead of one integration. Fixing that (uniform query across Cowork/Chat/Code) is squarely in scope for this request, even though it only solves part of my broader personal goal.
• General pattern: anywhere I'd otherwise reach for a sub-agent purely to avoid derailing my current session, but actually want the result to be checkable independently, later, from a different device, or by someone else looking at my account's session list — or anywhere I want a session to stay strictly free of side effects (no file writes, no tool-call noise) while still being able to dispatch real, file-touching work elsewhere.

In every one of these, today I have to choose between: (a) a sub-agent call that spills its tool calls, file edits, and output into my current session regardless of whether I wanted that session to stay clean, (b) a scheduled task where I can't set the model programmatically and have to manually dig the result back out of Scheduled → task → history → pin, or (c) — my most common actual workaround — manually copying a prompt the assistant drafted out of the discussion session and pasting it into a brand-new session myself, one at a time.

What I actually want, consistently, regardless of whether I'm in Cowork or Claude Code: ask the assistant to hand a piece of work off to a new, ordinary, appropriately-cheap-model session. I keep working in my current session; separately, I can open the new session — from any device — check its progress or read its finished result, exactly like any other session I started myself. No manual model-picking after the fact, no UI archaeology to find it again.

Additional Context

• Fragmentation as evidence for the "one shared primitive" argument above: in my own experience, the VS Code integration alone renders a Claude Code session in at least four different ways (extension panel, integrated-terminal CLI, inline diff/chat view, background/agent-teams panel) — depending on which one is active, session state, resumption, and visibility all behave differently, and none of the four covers everything correctly. The Desktop app fragments similarly across its Code, Cowork, and Chat modes, each with its own session handling. This isn't just an inconvenience for the workflow described above — it looks like the same architectural gap (no single, canonical session backend) surfacing repeatedly across unrelated parts of the product.
• Managed Agents API docs (existing, related capability): https://platform.claude.com/docs/en/managed-agents/sessions and https://platform.claude.com/docs/en/managed-agents/session-operations
• Claude Code agent teams docs (considered, doesn't fit): https://code.claude.com/docs/en/agent-teams
• Related issues reviewed: #29145, #20132, #24947, #30498, #36117, #33165
• Technical note: Claude Desktop is an Electron app; this request is explicitly not asking for UI-automation-based workarounds against it — see "Alternative Solutions" above for why that path was rejected.