@@ -0,0 +1,14 @@
+---
+'@objectstack/mcp': patch
+---
+
+fix(mcp): a coded refusal from a sandboxed hook or action body answers the body's own sentence, not the sandbox wrapper that names the hook
+
+Clause-②: no
+Metadata-protocol: none
+
+A QuickJS hook or action body that throws with a declared `code` and `status` (for example `throw Object.assign(new Error('Locked.'), { code: 'RECORD_LOCKED', status: 409 })`) reached every MCP tool and the `objectstack://objects/{name}/records/{id}` resource with the sandbox's debug wrapper as its message, `hook '<name>' threw: Error: Locked.`, so an agent saw the hook's internal name. `/api/v1/data` answers the same throw with the body's sentence alone.
+
+The MCP tools and the record resource now read that sentence the way the `/data` door does (`sandboxBusinessMessage`, `@objectstack/types`): `{ "error": { "code": "RECORD_LOCKED", "message": "Locked.", "status": 409 } }`. The code and status are unchanged. A coded refusal that does not come from a sandbox keeps its own message byte for byte, and a sandboxed body that crashed keeps today's message.
+
+This supersedes one sentence of the `@objectstack/mcp` note for the record data tools' code-less throw ("A thrown error that carries a `code` is answered exactly as before"): a coded refusal from a sandboxed body now answers its inner sentence; its code and status are still answered as before.
@@ -424,6 +424,71 @@ describe('the record data tools: a code-less throw answers what the /data door a
   });
 });
 
+/**
+ * [#31246] A CODED sandboxed refusal. A QuickJS hook (or action) body that runs
+ * `throw Object.assign(new Error(SENTENCE), { code: 'RECORD_LOCKED', status: 409 })`
+ * leaves the runner as this `SandboxError` (measured on the real
+ * `QuickJSScriptRunner`): `.message` is the `hook '<name>' threw: Error: …`
+ * debug wrapper, `.innerMessage` the sentence the author addressed to the
+ * caller, `code` and `status` as declared.
+ */
+const SANDBOX_SENTENCE = 'A finished invoice cannot be changed.';
+const SANDBOX_WRAPPER = `hook 'demo_invoice_guard' threw: Error: ${SANDBOX_SENTENCE}`;
+function codedSandboxRefusal(): Error {
+  return Object.assign(new Error(SANDBOX_WRAPPER), {
+    name: 'SandboxError',
+    innerMessage: SANDBOX_SENTENCE,
+    code: 'RECORD_LOCKED',
+    status: 409,
+  });
+}
+
+/**
+ * [#31246] Every tool renders a coded sandboxed refusal as the body's own
+ * sentence beside its code and status. `thrownRefusalEnvelope` read `.message`,
+ * so each answered the wrapper, the hook's internal name included, where
+ * `/api/v1/data` answers the inner sentence. It now reads the sentence through
+ * `sandboxBusinessMessage` (`@objectstack/types`), the read that door makes.
+ */
+describe('every tool: a coded sandboxed refusal answers the body\'s sentence, never the wrapper naming the hook (#31246)', () => {
+  for (const site of SITES) {
+    it(`${site.tool}: RECORD_LOCKED, the inner sentence and 409; the hook name is absent`, async () => {
+      const thrown = codedSandboxRefusal();
+      const result = await callTool(site, thrown);
+      expect(result.isError).toBe(true);
+      expect(result.content).toHaveLength(1);
+      expect(JSON.parse(result.content[0].text)).toEqual({
+        error: { code: 'RECORD_LOCKED', message: SANDBOX_SENTENCE, status: 409 },
+      });
+      // The answer the data door gives the same throw.
+      const door = mapDataError(thrown, 'task');
+      expect([door.body.code, door.body.error, door.status]).toEqual(['RECORD_LOCKED', SANDBOX_SENTENCE, 409]);
+      expect(result.content[0].text).not.toContain('demo_invoice_guard');
+      expect(result.content[0].text).not.toContain('threw');
+    });
+  }
+
+  // CONTROL: a READ of the field the sandbox populated, never a strip of the
+  // wrapper's prose. A coded refusal that is not a sandbox's renders byte for
+  // byte as before, even when its own sentence reads like the wrapper.
+  it('CONTROL: a coded non-sandbox refusal renders its own message byte for byte, wrapper-like prose included', async () => {
+    const query = SITES.find((s) => s.tool === 'query_records')!;
+    for (const thrown of [
+      Object.assign(new Error('The period is closed.'), { code: 'RECORD_LOCKED', status: 409 }),
+      Object.assign(new Error(SANDBOX_WRAPPER), { code: 'RECORD_LOCKED', status: 409 }),
+      Object.assign(new Error(SANDBOX_WRAPPER), { name: 'SandboxError', innerMessage: '', code: 'RECORD_LOCKED', status: 409 }),
+    ]) {
+      expect(await callTool(query, thrown), thrown.message).toEqual({
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ error: { code: 'RECORD_LOCKED', message: thrown.message, status: 409 } }, null, 2),
+        }],
+        isError: true,
+      });
+    }
+  });
+});
+
 describe('the record resource: a coded refusal adds its code beside the unchanged sentence (#23509)', () => {
   const URI = 'objectstack://objects/task/records/t1';
 
@@ -476,6 +541,18 @@ describe('the record resource: a coded refusal adds its code beside the unchange
     });
   });
 
+  it('[#31246] a coded sandboxed refusal: `error` is the inner sentence, beside its code and status', async () => {
+    const text = await readRefused(codedSandboxRefusal());
+    expect(JSON.parse(text)).toEqual({ error: SANDBOX_SENTENCE, code: 'RECORD_LOCKED', status: 409 });
+    expect(text).not.toContain('demo_invoice_guard');
+  });
+
+  it('[#31246] CONTROL: a coded non-sandbox refusal keeps its own sentence, wrapper-like prose included', async () => {
+    expect(await readRefused(Object.assign(new Error(SANDBOX_WRAPPER), { code: 'RECORD_LOCKED', status: 409 }))).toBe(
+      JSON.stringify({ error: SANDBOX_WRAPPER, code: 'RECORD_LOCKED', status: 409 }),
+    );
+  });
+
   it('a code-less throw answers `{ error }` byte-identically', async () => {
     expect(await readRefused(new Error('engine exploded'))).toBe(JSON.stringify({ error: 'engine exploded' }));
     expect(await readRefused('a thrown string')).toBe(JSON.stringify({ error: 'a thrown string' }));
 
@@ -653,6 +653,33 @@ describe('MCP delete_records: many records of one object in one confirmed call (
       });
       expect([...rows.keys()]).toEqual(['t2', 't3', 't4', 't5']);
     });
+
+    it('[#31246] a CODED sandboxed refusal is grouped under its code with the body\'s sentence, never the wrapper naming the hook', async () => {
+      const sentence = 'This task is approved and cannot be deleted.';
+      // The `SandboxError` the QuickJS runner raises for a body's
+      // `throw Object.assign(new Error(sentence), { code, status })`.
+      rows.get('t3')!.throws = Object.assign(new Error(`hook 'dlr_task_guard' threw: Error: ${sentence}`), {
+        name: 'SandboxError',
+        innerMessage: sentence,
+        code: 'RECORD_LOCKED',
+        status: 409,
+      });
+
+      const result = await callTool(bridge, 'delete_records', {
+        objectName: OBJECT,
+        recordIds: ['t1', 't3', 't6'],
+        [AI_ACTION_CONFIRMATION_MEMBER]: true,
+      });
+
+      expect(result.isError, result.content[0]?.text).toBeFalsy();
+      expect(parsed(result)).toMatchObject({
+        attempted: 3,
+        deleted: 2,
+        refused: 1,
+        refusals: [{ code: 'RECORD_LOCKED', status: 409, reason: sentence, count: 1, recordIds: ['t3'] }],
+      });
+      expect(result.content[0]!.text).not.toContain('dlr_task_guard');
+    });
   });
 
   it('the long-lived server the stdio transport serves refuses, previews and deletes the same way', async () => {
 
@@ -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, isServerFault, logServerFault, mapDataError, resolveQueryReadLimits, staleSummaryAnswerLines, structuredCodeAnswer, type SummaryRecomputeRefusal } from '@objectstack/types';
+import { earnedAnswerOf, isEngineDuplicateRecordEnvelope, isServerFault, logServerFault, mapDataError, resolveQueryReadLimits, sandboxBusinessMessage, staleSummaryAnswerLines, structuredCodeAnswer, type SummaryRecomputeRefusal } from '@objectstack/types';
 import {
   MCP_OAUTH_SCOPE_DATA_READ,
   MCP_OAUTH_SCOPE_DATA_WRITE,
@@ -1118,14 +1118,27 @@ export interface ThrownRefusalEnvelope {
  * (`developerMessage`, `object`, `field`) in their envelope's context slot;
  * this envelope has none. It is `code`, `message` and `status`, and the data
  * tools withhold `details` by design ({@link errorResultWithCode}).
+ *
+ * ## The caller-addressed sentence of a sandboxed refusal (#31246)
+ *
+ * A QuickJS hook or action body that throws with a declared `code` and
+ * `status` leaves the runner as a `SandboxError` whose `.message` is the
+ * `<kind> '<name>' threw: Error: …` debug wrapper, naming the hook, and whose
+ * `.innerMessage` is the sentence the author addressed to the caller. The
+ * `message` here is `sandboxBusinessMessage` (`@objectstack/types`), the read
+ * the `/api/v1/data` door makes for the same throw, and `.message` only when
+ * that read declines: not a sandbox refusal, or a body that crashed. ⛔ One
+ * reader, never a copy of its logic here, and never a strip of the wrapper's
+ * prose: a non-sandbox refusal keeps its own message byte for byte. The code
+ * and status are unchanged.
  */
 export function thrownRefusalEnvelope(err: unknown): ThrownRefusalEnvelope | undefined {
   const thrownCode = (err as { code?: unknown } | null | undefined)?.code;
   if (typeof thrownCode !== 'string' || thrownCode.length === 0) return undefined;
   const status = (err as { status?: unknown }).status;
   return {
     code: wireCodeOf(err, thrownCode),
-    message: messageOf(err),
+    message: sandboxBusinessMessage(err) ?? messageOf(err),
     ...(typeof status === 'number' ? { status } : {}),
   };
 }
 
@@ -1567,6 +1567,9 @@ export class MCPServerRuntime {
             // does. A throw with no code answers `{ error }` as before.
             // `details` is withheld, as on the data tools; `errorResultWithCode`
             // in mcp-http-tools.ts says why.
+            // [#31246] A coded refusal's `error` is the envelope's sentence,
+            // so a sandboxed hook's refusal answers the body's own sentence
+            // rather than the runner's wrapper naming the hook, as the tools do.
             const envelope = thrownRefusalEnvelope(err);
             return {
               contents: [{
@@ -1575,7 +1578,7 @@ export class MCPServerRuntime {
                 text: JSON.stringify(
                   envelope
                     ? {
-                        error: message,
+                        error: envelope.message,
                         code: envelope.code,
                         ...(envelope.status !== undefined ? { status: envelope.status } : {}),
                       }