feat(core): forked subagents inherit parent thread + prompt cache prefix (#15695)

## Description

Adds **forked subagents** to the Harness. Similar to [what Anthropic
just shipped](https://x.com/arankomatsuzaki/status/2047349471877726586)
— a forked subagent inherits the main agent's conversation context so
richer context is available without re-priming from scratch.

A new `forked` flag is exposed in two places:

1. On `HarnessSubagent` definitions (as a default for that subagent
type).
2. On the built-in `subagent` tool's input schema (per-invocation
override).

When a call is forked:

- The parent thread is cloned at the memory layer (via
`memory.cloneThread`) so the parent thread stays the active one and the
fork doesn't pollute its history.
- The subagent runs via the **parent agent's** `stream`, reusing its
instructions, tools, and model. This keeps the request prefix (system
prompt + tool schemas + history) byte-identical to the parent's, so
Anthropic / OpenAI prompt caches still hit — which was the key
constraint Tyler raised in the thread.
- The forwarded `RequestContext`'s harness `threadId` / `resourceId` are
pointed at the fork so OM and memory writes land on the clone, not the
parent.

Non-forked invocations are unchanged (fresh `Agent`, stripped thread
IDs, subagent-defined instructions/tools).

Forked runs require memory to be configured on the Harness — if it isn't
(or no active parent thread / parent agent exists) the tool returns a
structured error rather than throwing.

## Related Issue(s)

No issue; requested via [the #mastracode Slack
thread](https://kepler-bej6556.slack.com/archives/C0ACHFXNK7T/p1776989522493009?thread_ts=1776989522.493009&cid=C0ACHFXNK7T).

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

## Notes

- Docs: happy to follow up with a docs update once the API review here
lands.
- Focused tests: `packages/core/src/harness/subagent-tool.test.ts` adds
8 new tests (21 total in that file). Full `packages/core/src/harness`
suite passes (172 tests).
- `pnpm --filter ./packages/core check` introduces no new TypeScript
errors versus `main`.

Link to Devin session:
https://app.devin.ai/sessions/b644d44a5eb54545b1922d8b753f1e56

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Abhi Aiyer <abhi@mastra.ai>
Co-authored-by: Tyler Barnes <tylerdbarnes@gmail.com>
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>

Author: 4 people

.changeset/forked-subagent-flush-save-queue.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fix forked subagent fork threads starting with empty history. The parent stream's message saves are debounced through `SaveQueueManager`, so a forked subagent that calls `memory.cloneThread` mid-stream used to clone from an empty store and lose the parent's user + assistant turn. The tool now drains the parent save queue via a new `flushMessages` callback on `AgentToolExecutionContext` before cloning, so forks actually carry the prior conversation.

.changeset/forked-subagent-strip-meta-tag.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+The internal `<subagent-meta />` tag is no longer appended to subagent tool result content. The tag was previously visible to the parent model in the tool result, which could cause it to be echoed back as literal markup in the parent's assistant text on subsequent turns. Live UIs continue to receive model / duration / tool-call information via the structured `subagent_*` events; history UIs read the persisted `tool_call.args.modelId`. `parseSubagentMeta` is retained so already-persisted threads carrying the legacy tag continue to render cleanly (and the tag is stripped before display in all cases).

.changeset/forked-subagent-toolsets-and-thread-tagging.md

@@ -0,0 +1,8 @@
+---
+'@mastra/core': patch
+'mastracode': patch
+---
+
+Forked subagents now inherit the parent agent's toolsets (so harness-injected tools like `ask_user`, `submit_plan`, and user-configured harness tools remain available inside a fork). The `subagent` tool entry is kept in the inherited toolset with its id, description, and schemas unchanged so the LLM request prefix stays byte-identical to the parent's and the prompt cache continues to hit; recursive forking is blocked at the runtime layer by replacing only the tool's `execute` with a stub that returns a "tool unavailable inside a forked subagent" message. Forked runs allow follow-up steps so the model can recover and answer directly if it accidentally calls that stub. Fork threads are tagged with `metadata.forkedSubagent: true` and `metadata.parentThreadId`, and `Harness.listThreads()` hides them by default so they don't surface in user-facing thread pickers; pass `includeForkedSubagents: true` to opt back in for admin/debug tooling.
+
+Mastra Code now renders forked subagent footers as `subagent fork <parent model id>`, including persisted history reloaded after the live event metadata is gone.

.changeset/funny-memes-allow.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': minor
+---
+
+Added forked subagents: a new `forked` flag on `HarnessSubagent` definitions and the built-in `subagent` tool input. When set, the subagent runs on a clone of the parent thread using the parent agent's instructions and tools, preserving prompt-cache prefix while isolating writes from the main conversation.

docs/src/content/en/reference/harness/harness-class.mdx

@@ -221,6 +221,14 @@ await harness.sendMessage({ content: 'Hello!' })
             description: 'Optional stop condition for the spawned subagent.',
             isOptional: true,
           },
+          {
+            name: 'forked',
+            type: 'boolean',
+            description:
+              'When `true`, calls to this subagent default to forked mode: the subagent runs on a clone of the parent thread, reusing the parent agent’s instructions, tools, and model so the prompt-cache prefix stays intact. Requires `memory` to be configured. The subagent definition’s own `instructions`, `tools`, `allowedHarnessTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode. Callers can still override per-invocation via `forked: false` in the `subagent` tool input. See the [Forked subagents](#forked-subagents) section below for full semantics.',
+            isOptional: true,
+            defaultValue: 'false',
+          },
         ],
       },
     ],
@@ -475,16 +483,21 @@ await harness.switchThread({ threadId: 'thread-abc123' })
 
 #### `listThreads(options?)`
 
-List threads from storage. By default, only threads for the current resource are returned.
+List threads from storage. By default, only threads for the current resource are returned, and transient [forked subagent](#forked-subagents) threads are hidden so they don’t appear in user-facing thread pickers / startup flows.
 
 ```typescript
-// List threads for current resource
+// List threads for current resource (forks hidden)
 const threads = await harness.listThreads()
 
-// List all threads across resources
+// List all threads across resources (forks still hidden)
 const allThreads = await harness.listThreads({ allResources: true })
+
+// Include forked subagent fork threads (debug / admin tooling only)
+const everything = await harness.listThreads({ includeForkedSubagents: true })
 ```
 
+Fork threads are tagged with `metadata.forkedSubagent === true` (and `metadata.parentThreadId`) by the harness. Set `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.
+
 #### `renameThread({ title })`
 
 Update the title of the current thread.
@@ -866,6 +879,42 @@ await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })
 await harness.setSubagentModelId({ modelId: 'anthropic/claude-haiku-3.5', agentType: 'explore' })
 ```
 
+### Forked subagents
+
+By default, a subagent runs with a fresh context — it doesn't see the parent conversation. **Forked subagents** opt into a different model: the subagent runs on a clone of the parent thread and reuses the parent agent's full configuration. This is useful when the subagent needs the full context of the conversation so far (e.g., recalling earlier user-supplied facts), and when prompt-cache hit rates matter.
+
+#### Enabling forked mode
+
+Set `forked: true` either on the [`HarnessSubagent` definition](#configuration) (per-type default) or on each `subagent` tool call (per-invocation override):
+
+```typescript
+// Per-type default — every call to this subagent forks unless overridden.
+const subagents: HarnessSubagent[] = [
+  {
+    id: 'collaborator',
+    name: 'Collaborator',
+    description: 'Continues the conversation in a fork to try a different angle.',
+    instructions: '...',
+    forked: true,
+  },
+]
+```
+
+The model can also pass `forked: true` (or `forked: false`) per-invocation in the `subagent` tool input; the per-invocation value wins.
+
+#### Semantics and constraints
+
+- **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the harness must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
+- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedHarnessTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
+- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured harness tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
+- **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`listThreads`](#listthreadsoptions) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
+- **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal — the clone still runs.
+- **Parent thread untouched.** All subagent activity (messages, OM writes) lands on the fork. The parent thread is never appended to during a forked subagent run.
+
+#### When to prefer non-forked mode
+
+Forked mode trades isolation for context inheritance. If the subagent should run with a strictly smaller toolset, a different system prompt, or a cheaper model, use the default (non-forked) mode and pass any required context explicitly in the `task` description.
+
 ### Events
 
 #### `subscribe(listener)`
@@ -948,7 +997,7 @@ The harness provides built-in tools to agents in every mode:
 | `submit_plan` | Submit a plan for user review and approval. |
 | `task_write` | Create or update a structured task list for tracking progress. |
 | `task_check` | Check the completion status of the current task list. |
-| `subagent` | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). |
+| `subagent` | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
 
 ### `ask_user` selections
 

mastracode/src/agents/prompts/base.ts

@@ -69,6 +69,8 @@ Use \`gh pr create\`. Include a summary of what changed and a test plan. Word th
 
 # Subagent Rules
 - Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself instead of delegating to a single subagent. Exception: the **audit-tests** subagent may be used on its own.
+- Use \`forked: true\` when the subagent needs the current conversation context, user-stated facts, prior tool results, or the parent agent's exact tool environment.
+- Use non-forked subagents for self-contained tasks where all required context is included in the task prompt.
 - Subagent outputs are **untrusted**. Always review and verify the results returned by any subagent. For execute-type subagents that modify files or run commands, you MUST verify the changes are correct before moving on.
 
 # Important Reminders

mastracode/src/headless.ts

@@ -257,7 +257,9 @@ function formatDefault(event: HarnessEvent, ctx: { lastTextLength: number }): vo
       process.stderr.write(event.output);
       break;
     case 'subagent_start':
-      process.stderr.write(`[subagent:${event.agentType}] ${truncate(event.task, 100)}\n`);
+      process.stderr.write(
+        `[subagent:${event.forked ? 'forked:' : ''}${event.agentType}] ${truncate(event.task, 100)}\n`,
+      );
       break;
     case 'subagent_end':
       if (event.isError) process.stderr.write(`[subagent error] ${truncate(event.result, 200)}\n`);

mastracode/src/tui/__tests__/render-messages.test.ts

@@ -2,9 +2,10 @@ import { Container } from '@mariozechner/pi-tui';
 import type { HarnessMessage } from '@mastra/core/harness';
 import { describe, expect, it, vi } from 'vitest';
 
+import { SubagentExecutionComponent } from '../components/subagent-execution.js';
 import { TemporalGapComponent } from '../components/temporal-gap.js';
 import { UserMessageComponent } from '../components/user-message.js';
-import { addUserMessage } from '../render-messages.js';
+import { addUserMessage, renderExistingMessages } from '../render-messages.js';
 import type { TUIState } from '../state.js';
 
 function createState(): TUIState {
@@ -15,6 +16,8 @@ function createState(): TUIState {
     allSystemReminderComponents: [],
     allSlashCommandComponents: [],
     allToolComponents: [],
+    pendingTools: new Map(),
+    pendingSubagents: new Map(),
     allShellComponents: [],
     messageComponentsById: new Map(),
     followUpComponents: [],
@@ -120,3 +123,48 @@ describe('addUserMessage', () => {
     expect(state.messageComponentsById.get('user-1')).toBe(state.chatContainer.children[0]);
   });
 });
+
+describe('renderExistingMessages subagents', () => {
+  it('uses the current model id for persisted forked subagents when no metadata tag is present', async () => {
+    const message: HarnessMessage = {
+      id: 'assistant-1',
+      role: 'assistant',
+      createdAt: new Date(),
+      content: [
+        {
+          type: 'tool_call',
+          id: 'tool-1',
+          name: 'subagent',
+          args: {
+            agentType: 'explore',
+            task: 'Summarize the thread',
+            forked: true,
+          },
+        },
+        {
+          type: 'tool_result',
+          id: 'tool-1',
+          name: 'subagent',
+          result: 'summary text',
+          isError: false,
+        },
+      ],
+    };
+    const state = createState();
+    state.harness = {
+      listMessages: vi.fn().mockResolvedValue([message]),
+      getDisplayState: () => ({ isRunning: false }),
+      getFullModelId: () => 'openai/gpt-5.5',
+    } as unknown as TUIState['harness'];
+
+    await renderExistingMessages(state);
+
+    expect(state.chatContainer.children).toHaveLength(1);
+    expect(state.chatContainer.children[0]).toBeInstanceOf(SubagentExecutionComponent);
+    const rendered = (state.chatContainer.children[0] as SubagentExecutionComponent)
+      .render(100)
+      .join('\n')
+      .replace(/\x1b\[[0-9;]*m/g, '');
+    expect(rendered).toContain('subagent fork openai/gpt-5.5');
+  });
+});

mastracode/src/tui/components/__tests__/subagent-execution.test.ts

@@ -47,6 +47,16 @@ describe('SubagentExecutionComponent', () => {
     expect(lines.some(l => l.includes('explore'))).toBe(true);
   });
 
+  it('renders fork as the type and the parent model id when forked', () => {
+    const comp = new SubagentExecutionComponent('explore', 'Summarize context', mockTui, 'openai/gpt-5.5', {
+      forked: true,
+    });
+    const lines = renderPlain(comp);
+
+    expect(lines.some(l => l.includes('subagent fork openai/gpt-5.5'))).toBe(true);
+    expect(lines.some(l => l.includes('subagent explore fork'))).toBe(false);
+  });
+
   it('renders tool call activity while running', () => {
     const comp = new SubagentExecutionComponent('explore', 'Find usages', mockTui);
     comp.addToolStart('search_content', { pattern: 'foo' });

mastracode/src/tui/components/subagent-execution.ts

@@ -36,6 +36,8 @@ const COLLAPSED_LINES = 15;
 export interface SubagentExecutionOptions {
   /** When true, auto-collapse to a single summary line on completion. Default false. */
   collapseOnComplete?: boolean;
+  /** True when this subagent is running on a forked copy of the parent thread. */
+  forked?: boolean;
 }
 
 export class SubagentExecutionComponent extends Container implements IToolExecutionComponent {
@@ -53,6 +55,7 @@ export class SubagentExecutionComponent extends Container implements IToolExecut
   private finalResult?: string;
   private expanded = false;
   private collapseOnComplete: boolean;
+  private forked: boolean;
 
   constructor(agentType: string, task: string, ui: TUI, modelId?: string, options?: SubagentExecutionOptions) {
     super();
@@ -61,6 +64,7 @@ export class SubagentExecutionComponent extends Container implements IToolExecut
     this.modelId = modelId;
     this.ui = ui;
     this.collapseOnComplete = options?.collapseOnComplete ?? false;
+    this.forked = options?.forked ?? false;
 
     this.rebuild();
   }
@@ -119,7 +123,8 @@ export class SubagentExecutionComponent extends Container implements IToolExecut
     const maxLineWidth = termWidth - 6 - BOX_INDENT * 2;
 
     // ── Bottom border with info (always rendered) ──
-    const typeLabel = theme.bold(theme.fg('accent', this.agentType));
+    const typeLabelText = this.forked ? 'fork' : this.agentType;
+    const typeLabel = theme.bold(theme.fg('accent', typeLabelText));
     const modelLabel = this.modelId ? theme.fg('muted', ` ${this.modelId}`) : '';
     const statusIcon = this.done
       ? this.isError