@@ -0,0 +1,25 @@
+---
+'@objectstack/types': patch
+'@objectstack/runtime': patch
+'@objectstack/mcp': patch
+---
+
+fix(mcp): `run_action` and `resume_run` answer a thrown error the way `POST /api/v1/actions` does, through that door's one reader
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+MCP `run_action` and `resume_run` answered an error thrown while running an action differently from `POST /api/v1/actions/:object/:action`, which runs the same action:
+
+| The action threw | MCP answered | `/actions` answers, and MCP now answers |
+| --- | --- | --- |
+| A sandboxed body's own `throw new Error('Not enough leave')` | the runner's wrapper as bare text, naming the body: `action 'NAME' threw: Error: Not enough leave` | `400`, `HOOK_ABORTED`, `Not enough leave` |
+| A plain `Error` | its bare text, no code | `400`, `VALIDATION_ERROR`, its own sentence |
+| A driver error with a string code (`SQLITE_BUSY`) | `{ code: 'SQLITE_BUSY', message }`, no status | `400`, `VALIDATION_ERROR`, `declaredCode: 'SQLITE_BUSY'` |
+| A sandboxed body that crashed (`TypeError`), with or without a declared code | the wrapper with the native error text | `500`, `INTERNAL_ERROR`, `Internal server error` |
+
+The tool error is `{ "error": { "code", "message", "status" } }` with `isError`, plus `declaredCode` and `userMessage` when the door serves them. The full wrapper and the fault line are logged on the server, as the door logs them. A refusal with a registered code (a body that throws `{ code: 'RECORD_LOCKED', status: 409 }`) keeps its code, its own sentence and its status. A refusal with an app's own unregistered code (`{ code: 'LEAVE_EXHAUSTED', status: 409 }`) now crosses as `/actions` serves it: the closed code its status derives (`RESOURCE_CONFLICT`), with `declaredCode: 'LEAVE_EXHAUSTED'` beside it; MCP used to answer `code: 'LEAVE_EXHAUSTED'`. A thrown `details` (the confirmation gate's) still rides on a refusal and is no longer served on a fault (status 500 and above), which answers only the door's sanitised envelope; the `PERMISSION_DENIED` withhold is unchanged. This supersedes the line in the `31218` changeset that says `run_action` and `resume_run` are unchanged.
+
+A driver string code answers what `/actions` answers. `/api/v1/data` answers the same throw `500 DATABASE_ERROR`; that difference between the two REST doors is not changed here.
+
+**New export (`@objectstack/types`): `actionsDoorAnswerOf(err, objectName?)` and its `ActionsDoorAnswer` type**, the `/api/v1/actions` door's answer to a thrown value, beside `mapDataError` (the `/api/v1/data` door's). The `/actions` door (`@objectstack/runtime`) now answers through it; its responses are unchanged byte for byte.
@@ -388,7 +388,16 @@ describe('#21321: an install-local package runs its script actions and body hook
       it('list_actions does not advertise a declared action run_action cannot run', () => {
         const p = phases[name]!;
         expect(p.ghostRun.isError, 'precondition: ghost_task has no handler anywhere').toBe(true);
-        expect(String(p.ghostRun.payload)).toMatch(/No handler registered/);
+        // [#31271] `run_action` answers a throw through the `/actions` door's
+        // reader (`actionsDoorAnswerOf`), so the bridge's uncoded "No handler
+        // registered" throw arrives as that door's 400 rejection envelope, its
+        // sentence intact. (`POST /api/v1/actions` answers the same ghost action
+        // from its own routing-miss branch, a 404, before any throw.)
+        expect(p.ghostRun.payload?.error, JSON.stringify(p.ghostRun.payload)).toMatchObject({
+          code: 'VALIDATION_ERROR',
+          status: 400,
+          message: expect.stringMatching(/No handler registered/),
+        });
         expect(p.listed, 'advertised an action the run door refuses').not.toContain('ghost_task');
       });
     });
 
@@ -203,7 +203,10 @@ describe('run_action carries the confirmation member through the real MCP door (
     expect(bridge.calls).toHaveLength(0);
   });
 
-  it('leaves an UNCODED bridge failure as a plain message (the envelope widens, it narrows nothing)', async () => {
+  // [#31271] An uncoded bridge failure answers what `POST /api/v1/actions`
+  // answers it (`actionsDoorAnswerOf`): that door's 400 rejection, with the
+  // failure's own sentence and no `details`.
+  it('answers an UNCODED bridge failure as the /actions door does: 400 VALIDATION_ERROR, its own sentence', async () => {
     const failing = {
       ...bridge,
       async runAction() {
@@ -214,6 +217,8 @@ describe('run_action carries the confirmation member through the real MCP door (
     const res = await runtime.handleHttpRequest(mcpRequest(body), { bridge: failing, parsedBody: body });
     const json: any = await res.json();
     expect(json.result.isError).toBe(true);
-    expect(json.result.content[0].text).toBe('handler exploded');
+    expect(JSON.parse(json.result.content[0].text)).toEqual({
+      error: { code: 'VALIDATION_ERROR', message: 'handler exploded', status: 400 },
+    });
   });
 });
@@ -49,7 +49,7 @@ import { describe, it, expect, vi, afterEach } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { recordNotFoundError } from '@objectstack/core';
-import { mapDataError } from '@objectstack/types';
+import { actionsDoorAnswerOf, mapDataError } from '@objectstack/types';
 import type { IMetadataService } from '@objectstack/spec/contracts';
 
 import { MCPServerRuntime } from './mcp-server-runtime.js';
@@ -214,6 +214,18 @@ describe('MCP tools over HTTP /mcp: a coded refusal carries its code (#23509)',
           error: { code: 'INTERNAL_ERROR', message: 'Internal server error', status: 500 },
         });
       });
+    } else if (site.actionDoor) {
+      // [#31271] `run_action` / `resume_run` answer a code-less throw as the
+      // `/api/v1/actions` door does (`actionsDoorAnswerOf`): a plain `Error`
+      // is that door's rejection, `400 VALIDATION_ERROR` with its own
+      // sentence. The cases live in the #31271 block below.
+      it(`${site.tool}: a code-less throw from ${String(site.member)} answers the /actions door's 400 rejection`, async () => {
+        const result = await callTool(site, new Error('engine exploded'));
+        expect(result.isError).toBe(true);
+        expect(JSON.parse(result.content[0].text)).toEqual({
+          error: { code: 'VALIDATION_ERROR', message: 'engine exploded', status: 400 },
+        });
+      });
     } else {
       it(`${site.tool}: a code-less throw from ${String(site.member)} answers its bare message, as before`, async () => {
         const result = await callTool(site, new Error('engine exploded'));
@@ -428,8 +440,8 @@ describe('the record data tools: a code-less throw answers what the /data door a
     expect(log).not.toHaveBeenCalled();
   });
 
-  it('CONTROL: the tools that are not record data tools still answer a code-less throw with its bare message', async () => {
-    for (const site of SITES.filter((s) => !s.dataDoor)) {
+  it('CONTROL: the tools that are neither record data tools nor action tools still answer a code-less throw with its bare message', async () => {
+    for (const site of SITES.filter((s) => !s.dataDoor && !s.actionDoor)) {
       const result = await callTool(site, sandboxAbort('Not enough annual leave remaining'));
       expect(result, site.tool).toEqual({
         content: [{ type: 'text', text: "hook 'demoleave_leave_request_guard' threw: Error: Not enough annual leave remaining" }],
@@ -757,6 +769,136 @@ describe('a coded sandboxed CRASH is a fault on every face, never a refusal at i
   });
 });
 
+/**
+ * [#31271] `run_action` / `resume_run` answer a throw as the `/api/v1/actions`
+ * door answers it: through that door's own reader, `actionsDoorAnswerOf`
+ * (`@objectstack/types`), never a copy. Each row asserts the literal answer
+ * AND its equality with the reader's on a fresh copy of the same throw, so the
+ * pin cannot pass by the two agreeing on something nobody wrote down.
+ *
+ * These tools used to answer a code-less sandboxed body abort with the
+ * runner's `KIND 'NAME' threw: …` wrapper naming the body, a bare `Error` with
+ * its bare text and no code, a driver string code as `{ code: SQLITE_BUSY }`
+ * with no status, and a sandboxed crash (coded or not) with the wrapper and
+ * the native error text.
+ *
+ * ⚠️ `SQLITE_BUSY` answers what `/actions` answers, `400 VALIDATION_ERROR` with
+ * `declaredCode`; `/api/v1/data` answers the same throw `500 DATABASE_ERROR`.
+ * That REST-side difference is not this card's.
+ */
+describe('run_action / resume_run: a throw answers what the /actions door answers (#31271)', () => {
+  const ACTION_SITES = SITES.filter((s) => s.actionDoor);
+  const BODY_WRAPPER = "action 'demo_leave_body' threw: Error: Not enough annual leave remaining";
+  const CRASH_WRAPPER = "action 'demo_leave_body' threw: TypeError: boom";
+
+  const CASES: ReadonlyArray<{ name: string; thrown: () => unknown; answer: Record<string, unknown>; logs: number }> = [
+    {
+      name: 'a code-less sandboxed body abort: 400 HOOK_ABORTED with the inner sentence',
+      thrown: () => Object.assign(new Error(BODY_WRAPPER), { name: 'SandboxError', innerMessage: 'Not enough annual leave remaining' }),
+      answer: { code: 'HOOK_ABORTED', message: 'Not enough annual leave remaining', status: 400 },
+      logs: 1,
+    },
+    {
+      name: 'a bare Error: the door\'s 400 rejection, VALIDATION_ERROR with its own sentence',
+      thrown: () => new Error('socket hang up'),
+      answer: { code: 'VALIDATION_ERROR', message: 'socket hang up', status: 400 },
+      logs: 0,
+    },
+    {
+      name: 'a driver string code: 400 VALIDATION_ERROR, SQLITE_BUSY demoted to declaredCode',
+      thrown: () => Object.assign(new Error('SQLITE_BUSY: database is locked'), { code: 'SQLITE_BUSY' }),
+      answer: { code: 'VALIDATION_ERROR', message: 'SQLITE_BUSY: database is locked', status: 400, declaredCode: 'SQLITE_BUSY' },
+      logs: 0,
+    },
+    {
+      name: 'a sandboxed CRASH with no code: 500 INTERNAL_ERROR, the generic sentence',
+      thrown: () => Object.assign(new Error(CRASH_WRAPPER), { name: 'SandboxError', innerMessage: 'TypeError: boom' }),
+      answer: { code: 'INTERNAL_ERROR', message: 'Internal server error', status: 500 },
+      logs: 1,
+    },
+    {
+      name: 'a sandboxed CRASH that declared a code and status: the same fault; neither is served',
+      thrown: () => Object.assign(new Error(CRASH_WRAPPER), {
+        name: 'SandboxError', innerMessage: 'TypeError: boom', code: 'RECORD_LOCKED', status: 409,
+      }),
+      answer: { code: 'INTERNAL_ERROR', message: 'Internal server error', status: 500 },
+      logs: 1,
+    },
+  ];
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('the two action tools are the rows this block drives', () => {
+    expect(ACTION_SITES.map((s) => s.tool).sort()).toEqual(['resume_run', 'run_action']);
+  });
+
+  for (const site of ACTION_SITES) {
+    for (const c of CASES) {
+      it(`${site.tool}: ${c.name}`, async () => {
+        const log = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const result = await callTool(site, c.thrown());
+        expect(result.isError).toBe(true);
+        expect(result.content).toHaveLength(1);
+        const text = String(result.content[0].text);
+        const { error } = JSON.parse(text);
+        expect(error).toEqual(c.answer);
+        // The door's reader, on a fresh copy of the same throw.
+        const door = actionsDoorAnswerOf(c.thrown());
+        expect(error).toEqual({
+          code: door.code,
+          message: door.message,
+          status: door.status,
+          ...(door.declaredCode !== undefined ? { declaredCode: door.declaredCode } : {}),
+        });
+        expect(text).not.toContain('demo_leave_body');
+        expect(text).not.toContain('TypeError');
+        // The wrapper and the fault line reach the operator, as the door prints them.
+        expect(log).toHaveBeenCalledTimes(c.logs);
+      });
+    }
+
+    it(`${site.tool}: an app's own unregistered code crosses as the status-derived closed code, its spelling in declaredCode`, async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      const thrown = () => Object.assign(new Error('No leave days left this year.'), { code: 'LEAVE_EXHAUSTED', status: 409 });
+      const { error } = JSON.parse((await callTool(site, thrown())).content[0].text);
+      expect(error).toEqual({
+        code: 'RESOURCE_CONFLICT', message: 'No leave days left this year.', status: 409, declaredCode: 'LEAVE_EXHAUSTED',
+      });
+      const door = actionsDoorAnswerOf(thrown());
+      expect([door.code, door.declaredCode, door.status]).toEqual([error.code, error.declaredCode, error.status]);
+    });
+
+    it(`${site.tool}: a fault carries no thrown details; a refusal still does`, async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      const details = { host: 'db-primary.internal', pool: 'writer' };
+      for (const fault of [
+        Object.assign(new Error('pool exhausted'), { status: 503, details }),
+        Object.assign(new Error(CRASH_WRAPPER), { name: 'SandboxError', innerMessage: 'TypeError: boom', details }),
+      ]) {
+        const result = await callTool(site, fault);
+        const { error } = JSON.parse(result.content[0].text);
+        expect(error.status).toBeGreaterThanOrEqual(500);
+        expect(error).not.toHaveProperty('details');
+        expect(result.content[0].text).not.toContain('db-primary.internal');
+      }
+      const refusal = Object.assign(new Error('Confirm first.'), { code: 'ACTION_CONFIRMATION_REQUIRED', status: 428, details });
+      expect(JSON.parse((await callTool(site, refusal)).content[0].text).error).toEqual({
+        code: 'ACTION_CONFIRMATION_REQUIRED', message: 'Confirm first.', status: 428, details,
+      });
+    });
+
+    it(`${site.tool}: CONTROL: a coded sandboxed refusal keeps the #31246 answer (code, inner sentence, status)`, async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+      const result = await callTool(site, codedSandboxRefusal());
+      expect(JSON.parse(result.content[0].text)).toEqual({
+        error: { code: 'RECORD_LOCKED', message: SANDBOX_SENTENCE, status: 409 },
+      });
+    });
+  }
+});
+
 /**
  * [#31272] The metadata tools (`list_objects`, `describe_object`,
  * `validate_expression`) and `list_actions` answer a FAULT as the `/meta` door
 
@@ -50,7 +50,7 @@ import { StandardErrorCode, type ErrorCode } from '@objectstack/spec/api';
 // [#23701] The one key every door that translates the engine's unique-violation
 // envelope asks (the registered code AND the class name, never message text),
 // and the one classification whose arm states the wire code for it.
-import { earnedAnswerOf, isEngineDuplicateRecordEnvelope, isSandboxCrash, isServerFault, logServerFault, mapDataError, resolveQueryReadLimits, resolveThrownHttpError, sandboxBusinessMessage, serverFaultProvenance, staleSummaryAnswerLines, structuredCodeAnswer, type SummaryRecomputeRefusal } from '@objectstack/types';
+import { actionsDoorAnswerOf, earnedAnswerOf, isEngineDuplicateRecordEnvelope, isSandboxCrash, isServerFault, logServerFault, mapDataError, resolveQueryReadLimits, resolveThrownHttpError, sandboxBusinessMessage, serverFaultProvenance, staleSummaryAnswerLines, structuredCodeAnswer, type SummaryRecomputeRefusal } from '@objectstack/types';
 import {
   MCP_OAUTH_SCOPE_DATA_READ,
   MCP_OAUTH_SCOPE_DATA_WRITE,
@@ -441,8 +441,6 @@ function errorResult(message: string) {
  * nobody and the agent is back to guessing the member's spelling from
  * documentation.
  *
- * Uncoded throws fall through to `errorResult` unchanged.
- *
  * `run_action` and `resume_run` only. The other catches render through
  * {@link errorResultWithCode}, which serves the same envelope WITHOUT `details`;
  * that function says why.
@@ -465,12 +463,41 @@ function errorResult(message: string) {
  * reaches the `details` read at all. Every other coded refusal keeps its
  * `details` as before, so #15942's confirmation contract and `resume_run`'s
  * REST-built `details` are unchanged.
+ *
+ * [#31271] The answer is the `/api/v1/actions` door's, read off that door's own
+ * reader, `actionsDoorAnswerOf` (`@objectstack/types`), never a copy of its
+ * arms: a code-less sandboxed body abort answers `400 HOOK_ABORTED` with the
+ * body's sentence (it answered the runner's `KIND 'NAME' threw: …` wrapper
+ * naming the body), a plain `Error` the door's `400 VALIDATION_ERROR`
+ * rejection, a sandboxed or in-process crash the door's `500` fault with no
+ * body name and no native text, and an unregistered code is demoted to
+ * `declaredCode` beside the closed `code`, as the door serves it. The lines
+ * the door prints for the operator (the full wrapper, the fault line) are
+ * printed here under `request`. A thrown `details` rides on a refusal (a
+ * status below 500) as before, and never on a fault, whose answer is the
+ * door's sanitised one; the context the door adds (`fields`, `issues`, the
+ * unique arm's `object` / `field`) is not served, as on every other tool
+ * ({@link errorResultWithCode} says why).
+ *
+ * ⚠️ A driver string code (`SQLITE_BUSY`) answers what `/actions` answers,
+ * `400 VALIDATION_ERROR` with `declaredCode`, where `/api/v1/data` answers
+ * `500 DATABASE_ERROR`. That difference is between the two REST doors.
  */
-function errorResultFromThrown(err: unknown) {
-  const envelope = thrownRefusalEnvelope(err);
-  if (!envelope) return errorResult(messageOf(err));
-  if (envelope.code === StandardErrorCode.enum.PERMISSION_DENIED) return errorResultWithCode(err);
-  const details = (err as { details?: unknown }).details;
+function errorResultFromThrown(err: unknown, request: string, objectName?: string) {
+  const answer = actionsDoorAnswerOf(err, objectName);
+  for (const line of answer.operatorLines) console.error(`[MCP] ${request}: ${line}`);
+  const envelope = {
+    code: answer.code,
+    message: answer.message,
+    status: answer.status,
+    ...(answer.declaredCode !== undefined ? { declaredCode: answer.declaredCode } : {}),
+    ...(answer.userMessage !== undefined ? { userMessage: answer.userMessage } : {}),
+  };
+  if (answer.code === StandardErrorCode.enum.PERMISSION_DENIED) return codedErrorResult(envelope);
+  // A fault (5xx) carries nothing but the door's sanitised answer: a thrown
+  // `details` rides only on a refusal, as `/actions` serves no producer
+  // context on a fault.
+  const details = answer.status < 500 ? (err as { details?: unknown } | null | undefined)?.details : undefined;
   return codedErrorResult({ ...envelope, ...(details !== undefined ? { details } : {}) });
 }
 
@@ -695,7 +722,14 @@ function landedWriteResultOrError(
   return textResult(earned);
 }
 
-function codedErrorResult(error: { code?: string; message: string; status?: number; details?: unknown }) {
+function codedErrorResult(error: {
+  code?: string;
+  message: string;
+  status?: number;
+  declaredCode?: string;
+  userMessage?: string;
+  details?: unknown;
+}) {
   return {
     content: [{ type: 'text' as const, text: jsonText({ error }) }],
     isError: true as const,
@@ -2571,7 +2605,11 @@ export function registerActionTools(
         });
         return textResult(result);
       } catch (err) {
-        return landedWriteResultOrError(err, objectName, errorResultFromThrown);
+        return landedWriteResultOrError(
+          err,
+          objectName,
+          (thrown) => errorResultFromThrown(thrown, `run_action ${actionName}`, objectName),
+        );
       }
     },
   );
@@ -2665,7 +2703,7 @@ export function registerActionTools(
           });
           return textResult(result);
         } catch (err) {
-          return errorResultFromThrown(err);
+          return errorResultFromThrown(err, `resume_run ${runId}`);
         }
       },
     );