fix(signals): add subscription-native tool approval (#17311)

## Summary

- Add subscription-native approve/decline routes and client helpers for
tool approvals.
- Wire React `useChat()` to use the JSON subscription approval path when
subscribed.
- Restore suspended memory thread/resource in `resumeStream()` so
resumed approval chunks register to the active thread subscription.
- Document subscription-native approval in signals, client-js, and
server route docs.

## Stack navigation

Stack position: 3/5.

- Previous: #17310
- Next: #17312

## Test plan

- `pnpm --filter @mastra/core test
src/agent/__tests__/agent-signals.test.ts
src/agent/__tests__/resume-span-tracing.test.ts --bail 1 --reporter=dot`
- `pnpm --filter ./packages/server test
src/server/handlers/agents.test.ts --bail 1 --reporter=dot`
- `pnpm --filter @mastra/client-js test src/resources/agent.test.ts
--bail 1 --reporter=dot`
- `pnpm --filter @mastra/react test src/agent/hooks.test.ts --bail 1
--reporter=dot`
- `pnpm --filter @mastra/core build:lib`
- `pnpm --filter @mastra/client-js build:lib`
- `pnpm --filter @mastra/react build:js`
- `pnpm --filter @mastra/server build:lib`
- `pnpm --filter ./packages/playground build`
- `pnpm --filter ./packages/server check:permissions`
- `pnpm --filter ./packages/server check:core-imports`
- `pnpm run prettier:changed`


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5 (Explain Like I'm 5)
If a paused AI needs permission to continue, you can now approve or
decline it directly in the same chat subscription and the AI will resume
speaking in that same conversation; you immediately get a small JSON
confirmation that the approval was received.

## Overview
Implements subscription-native tool approval/decline so paused tool
calls are acknowledged with a JSON response and resumed output is
delivered through the existing thread subscription (no separate
continuation stream). Changes span server routes and schemas, core agent
runtime and APIs, client-js SDK, React hook integration, tests,
playground helpers, and documentation. Also ensures suspended-run
memory/thread context is preserved on resume so resumed chunks attach to
the active subscription.

## Key changes
- Server (packages/server)
  - Add POST endpoints for subscription-native approvals:
    - POST /agents/:agentId/approve-tool-call-for-thread
    - POST /agents/:agentId/decline-tool-call-for-thread
- Add Zod schemas (toolCallSubscriptionBodySchema,
toolCallSubscriptionResponseSchema).
- Handlers validate effective thread access, merge requestContext
safely, sanitize body, and call the core agent thread-scoped approval
helpers.
- Thread ownership validation was added in review to prevent
cross-thread approvals.

- Core (packages/core)
- Add getActiveThreadRunId() to look up an active runId for a (threadId,
resourceId) scope (treating suspended runs as active).
- resumeStream(): restore memory.thread/resource from suspended-run
snapshot when resuming (without overwriting caller-provided memory).
- Add approveToolCallForThread and declineToolCallForThread helpers
which require an active thread-scoped run, default memory keys from
thread/resource, call the generic approve/decline flow, and return {
accepted: true; runId; toolCallId? }.
- Thread-stream runtime: publish run-suspended, keep reservation records
for suspended runs, treat suspended as active for queuing and resume,
and centralize active-run lookup.

- Client SDKs
- client-js: add Agent methods approveToolCallForThread /
declineToolCallForThread and generated route types / CLI metadata for
the new endpoints.
- react: useChat now tracks pending tool-approval IDs, exposes
isAwaitingToolApproval, treats tool-call-approval and
tool-call-suspended chunks as non-running, and routes approve/decline to
thread-native APIs when subscribed.

- Playground / runtime state
- Add getCanSendWhileStreaming helper and use it in
MastraRuntimeProvider.
- MastraRuntimeProvider updated to include isAwaitingToolApproval
gating.

- Tests
- Core: resumed-run delivery and queuing-behind-suspended-run tests;
end-to-end subscription-native approval test covering memory restore.
- Server: schema and handler tests for the new routes and authorization.
  - client-js: tests for new Agent methods calling the new endpoints.
- react: extensive useChat tests for subscription approval flows and
routing to thread-native approvals.
  - playground: tests updated to include isAwaitingToolApproval.

- Docs
- New and updated docs describing subscription-native approve/decline
(JSON ack + resumed chunks via thread subscription) and guidance
distinguishing for-thread APIs vs legacy continuation-stream APIs.
- client-js and server route references updated with examples and route
metadata.

## CI / Review notes (actionable)
- CI blocker: the shared server-adapter integration tests
(express/fastify/hono/koa) fail with 500s for the two new routes because
the shared test-helpers do not mock the new agent thread-approval
methods; the real implementations run in the synthetic test context and
getActiveThreadRunId() can throw when no active run exists.
- Immediate test fix: add the thread-approval spies to the central mock
setup (server-adapters/_test-utils/src/test-helpers.ts). Example mocks
to add:
- vi.spyOn(agent, 'approveToolCallForThread' /* or
approveToolCallAndSubscribe if that helper is present
*/).mockResolvedValue({ accepted: true, runId: 'test-run', toolCallId:
'test-tool-call' } as any);
- vi.spyOn(agent, 'declineToolCallForThread' /* or
declineToolCallAndSubscribe */).mockResolvedValue({ accepted: true,
runId: 'test-run', toolCallId: 'test-tool-call' } as any);
- Adding these spies alongside existing tool-call mocks in the shared
test-helpers will unblock adapter tests.

- Security / ownership
- Review feedback to validate thread ownership was applied in the
subscription route handlers; the author addressed this in follow-up
changes. Verify handlers call the same validateThreadOwnership check
used by abort-thread routes before delegating.

## Test plan
Run the package-scoped tests/build/checks listed in the PR (package
filter/test commands included in the PR) and the server
permission/core-import checks, then run prettier on changed files.

## Status / Next steps
- Add the two mock spies to
server-adapters/_test-utils/src/test-helpers.ts to make adapter tests
green (CI blocker).
- Confirm thread-ownership validation is present and correct in the
subscription routes (review indicates it was added).
- Once CI passes and ownership validation is confirmed, this is ready to
merge.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>

Author: TylerBarnes

.changeset/curly-mice-approve.md

@@ -0,0 +1,18 @@
+---
+'@mastra/core': patch
+'@mastra/client-js': patch
+'@mastra/react': patch
+'@mastra/server': patch
+'mastra': patch
+---
+
+Added subscription-native tool approval APIs so approving or declining a tool call resumes through the active thread subscription instead of requiring a separate continuation stream. New messages are queued while a tool approval is waiting, preventing overlapping runs from duplicating approval requests.
+
+```ts
+await agent.sendToolApproval({
+  resourceId: 'user-123',
+  threadId: 'thread-123',
+  toolCallId: 'tool-call-123',
+  approved: true,
+});
+```

client-sdks/client-js/src/resources/agent.test.ts

@@ -89,6 +89,58 @@ describe('Agent signal routes', () => {
     });
   });
 
+  it('approves tool calls through the subscription-native route', async () => {
+    const agent = new Agent(mockClientOptions, 'test-agent');
+    const mockRequest = vi.fn().mockResolvedValue({ accepted: true, runId: 'run-123', toolCallId: 'tool-call-123' });
+    agent['request'] = mockRequest as (typeof agent)['request'];
+
+    const result = await agent.sendToolApproval({
+      resourceId: 'resource-123',
+      threadId: 'thread-123',
+      toolCallId: 'tool-call-123',
+      approved: true,
+      requestContext: { userId: 'user-123' },
+    });
+
+    expect(result).toEqual({ accepted: true, runId: 'run-123', toolCallId: 'tool-call-123' });
+    expect(mockRequest).toHaveBeenCalledWith('/agents/test-agent/send-tool-approval', {
+      method: 'POST',
+      body: {
+        resourceId: 'resource-123',
+        threadId: 'thread-123',
+        toolCallId: 'tool-call-123',
+        approved: true,
+        requestContext: { userId: 'user-123' },
+      },
+    });
+  });
+
+  it('declines tool calls through the subscription-native route', async () => {
+    const agent = new Agent(mockClientOptions, 'test-agent');
+    const mockRequest = vi.fn().mockResolvedValue({ accepted: true, runId: 'run-123', toolCallId: 'tool-call-123' });
+    agent['request'] = mockRequest as (typeof agent)['request'];
+
+    const result = await agent.sendToolApproval({
+      resourceId: 'resource-123',
+      threadId: 'thread-123',
+      toolCallId: 'tool-call-123',
+      approved: false,
+      requestContext: { userId: 'user-123' },
+    });
+
+    expect(result).toEqual({ accepted: true, runId: 'run-123', toolCallId: 'tool-call-123' });
+    expect(mockRequest).toHaveBeenCalledWith('/agents/test-agent/send-tool-approval', {
+      method: 'POST',
+      body: {
+        resourceId: 'resource-123',
+        threadId: 'thread-123',
+        toolCallId: 'tool-call-123',
+        approved: false,
+        requestContext: { userId: 'user-123' },
+      },
+    });
+  });
+
   it('sends thread-targeted signals with active and idle behavior unchanged', async () => {
     const agent = new Agent(mockClientOptions, 'test-agent');
     const mockRequest = vi.fn().mockResolvedValue({ accepted: true, runId: 'run-123' });

client-sdks/client-js/src/resources/agent.ts

@@ -2717,6 +2717,23 @@ export class Agent extends BaseResource {
     return streamResponse;
   }
 
+  async sendToolApproval(params: {
+    resourceId: string;
+    threadId: string;
+    toolCallId: string;
+    approved: boolean;
+    requestContext?: RequestContext | Record<string, any>;
+  }): Promise<{ accepted: true; runId: string; toolCallId?: string }> {
+    const { requestContext, ...rest } = params;
+    return this.request<{ accepted: true; runId: string; toolCallId?: string }>(
+      `/agents/${this.agentId}/send-tool-approval`,
+      {
+        method: 'POST',
+        body: { ...rest, requestContext: parseClientRequestContext(requestContext) },
+      },
+    );
+  }
+
   async declineToolCall(params: {
     runId: string;
     toolCallId: string;

client-sdks/client-js/src/route-types.generated.ts

@@ -6942,6 +6942,54 @@ export interface PostAgentsAgentIdApproveToolCall_RouteContract {
   responseType: 'stream';
 }
 
+// ============================================================================
+// Route: POST /agents/:agentId/send-tool-approval
+// ============================================================================
+export type PostAgentsAgentIdSendToolApproval_PathParams = {
+  /** Unique identifier for the agent */
+  agentId: string;
+};
+
+export type PostAgentsAgentIdSendToolApproval_Body = {
+  resourceId: string;
+  threadId: string;
+  requestContext?:
+    | {
+        [key: string]: any;
+      }
+    | undefined;
+  toolCallId: string;
+  approved: boolean;
+  format?: string | undefined;
+};
+
+export type PostAgentsAgentIdSendToolApproval_Response = {
+  accepted: true;
+  runId: string;
+  toolCallId?: string | undefined;
+};
+
+export type PostAgentsAgentIdSendToolApproval_Request = Simplify<
+  (PostAgentsAgentIdSendToolApproval_PathParams extends never
+    ? {}
+    : { params: PostAgentsAgentIdSendToolApproval_PathParams }) &
+    (never extends never ? {} : {} extends never ? { query?: never } : { query: never }) &
+    (PostAgentsAgentIdSendToolApproval_Body extends never
+      ? {}
+      : {} extends PostAgentsAgentIdSendToolApproval_Body
+        ? { body?: PostAgentsAgentIdSendToolApproval_Body }
+        : { body: PostAgentsAgentIdSendToolApproval_Body })
+>;
+
+export interface PostAgentsAgentIdSendToolApproval_RouteContract {
+  pathParams: PostAgentsAgentIdSendToolApproval_PathParams;
+  queryParams: never;
+  body: PostAgentsAgentIdSendToolApproval_Body;
+  request: PostAgentsAgentIdSendToolApproval_Request;
+  response: PostAgentsAgentIdSendToolApproval_Response;
+  responseType: 'json';
+}
+
 // ============================================================================
 // Route: POST /agents/:agentId/decline-tool-call
 // ============================================================================
@@ -84754,6 +84802,7 @@ export interface RouteTypes {
   'POST /agents/:agentId/threads/subscribe': PostAgentsAgentIdThreadsSubscribe_RouteContract;
   'POST /agents/:agentId/tools/:toolId/execute': PostAgentsAgentIdToolsToolIdExecute_RouteContract;
   'POST /agents/:agentId/approve-tool-call': PostAgentsAgentIdApproveToolCall_RouteContract;
+  'POST /agents/:agentId/send-tool-approval': PostAgentsAgentIdSendToolApproval_RouteContract;
   'POST /agents/:agentId/decline-tool-call': PostAgentsAgentIdDeclineToolCall_RouteContract;
   'POST /agents/:agentId/resume-stream': PostAgentsAgentIdResumeStream_RouteContract;
   'POST /agents/:agentId/approve-tool-call-generate': PostAgentsAgentIdApproveToolCallGenerate_RouteContract;
@@ -85221,6 +85270,9 @@ export interface Client {
   '/agents/:agentId/send-message': {
     POST: PostAgentsAgentIdSendMessage_RouteContract;
   };
+  '/agents/:agentId/send-tool-approval': {
+    POST: PostAgentsAgentIdSendToolApproval_RouteContract;
+  };
   '/agents/:agentId/signals': {
     POST: PostAgentsAgentIdSignals_RouteContract;
   };