@@ -11,8 +11,8 @@ Metadata-protocol: none
 A developer driving an MCP client (Claude Code, Claude Desktop, …) against a hosted environment could read and run it over `/api/v1/mcp` but never build in it: `handleHttpRequest` served the data and action tools only, and no OAuth scope existed under which a token could even ask for authoring. This change adds the scope and its first reader.
 
 - **`@objectstack/spec` — `MCP_OAUTH_SCOPE_METADATA_WRITE` (`metadata:write`)** joins `data:read`, `data:write` and `actions:execute` in `MCP_OAUTH_SCOPES`, so the authorization server advertises it and the runtime's up-front scope check admits it. It is a tool-surface grant, not a data grant: `scopesToAgentPermissionSets` maps it alone to the no-object-access floor, and beside a data scope it changes nothing about the data ceiling. **`MCP_OAUTH_SCOPE_CONSENT_COPY`** declares the one-sentence consent copy for every scope (the three existing sentences the Console already renders, plus the new one), keyed by `McpOauthScope` so a scope cannot be added without its sentence.
-- **`@objectstack/mcp` — `handleHttpRequest(request, { authoring })`** accepts an optional `McpAuthoringInjection`: a host's `McpAuthoringToolRegistry` plus the token principal and the environment. Its tools appear in `tools/list` only when the request's `grantedScopes` names `metadata:write`; without the scope they are not registered, so `tools/call` on one is answered exactly as `create_record` is without `data:write` (the SDK's unknown-tool error, one mechanism). The undefined grant of an API key or a session is served no authoring tool: authoring follows the token's consent. Every call into the registry receives a fresh `McpAuthoringToolContext` — `door: 'mcp'` (`MCP_TOOL_DOOR`), `actor.id`, `principal`, `environmentId` — built from the host's inputs alone, so no request header can claim another door, user or environment. The runtime stays door-agnostic: which tools the host injects is the host's business.
-- **`renderSkillMarkdown({ grantedScopes, authoringTools })`** renders a Build section naming the injected tools, with the build loop (create → verify → draft, a person publishes in the UI) and the switched frontmatter description `OBJECTSTACK_SKILL_DESCRIPTION_WITH_AUTHORING`, only under the same grant; every other render is byte-identical to before.
+- **`@objectstack/mcp` — `handleHttpRequest(request, { authoring })`** accepts an optional `McpAuthoringInjection`: a host's `McpAuthoringToolRegistry` plus the token principal and the environment. Its tools appear in `tools/list` only when the request's `grantedScopes` names `metadata:write`; without the scope they are not registered, so `tools/call` on one is answered exactly as `create_record` is without `data:write` (the SDK's unknown-tool error, one mechanism). The undefined grant of an API key or a session is served no authoring tool: authoring follows the token's consent. Every call into the registry receives a fresh `McpAuthoringToolContext` — `door: 'mcp'` (`MCP_TOOL_DOOR`), `actor.id`, `principal`, `environmentId` — built from the host's inputs alone, so no request header can claim another door, user or environment; the principal (and its `scopes`) is a frozen per-call copy, so a tool that writes into its context taints neither the next call nor the host's object. Tool names are the host's to keep unique: the SDK throws on a duplicate registration (a native name or a repeat within the registry) and the request fails with it. The runtime stays door-agnostic: which tools the host injects is the host's business.
+- **`renderSkillMarkdown({ grantedScopes, authoringTools })`** renders a Build section naming the injected tools, with the build loop (create → verify → draft, a person publishes in the UI) and the switched frontmatter description `OBJECTSTACK_SKILL_DESCRIPTION_WITH_AUTHORING`, only under the same grant; it teaches `describe_object` before a change only when the grant also carries `data:read`, the scope that registers it; every other render is byte-identical to before.
 - **Unchanged.** The stdio transport's `bridgeTools` still calls its registry with one argument; the data and action tools register, refuse and answer as before. New exports: `MCP_TOOL_DOOR`, `grantsAuthoringTools`, and the types `McpToolDoor`, `McpTokenPrincipal`, `McpAuthoringToolContext`, `McpAuthoringToolRegistry`, `McpAuthoringInjection`.
 
 What to do: nothing for an existing host. A host that wants the build door passes `authoring` to `handleHttpRequest` and `grantedScopes` / `authoringTools` to `renderSkill`.
@@ -411,6 +411,66 @@ describe('[#26464] authoring tools over HTTP — door provenance in the tool con
     expect(PRINCIPAL.userId).toBe('usr_dev_1');
   });
 
+  it('the principal in the context is a frozen per-call copy: a handler can taint neither the next call nor the host object', async () => {
+    const attempts: unknown[] = [];
+    const tainting: McpAuthoringToolRegistry = {
+      getAll: () => AUTHORING_TOOLS,
+      async execute(toolCall, context) {
+        registry.calls.push({ toolCall, context });
+        // Each write is what a hostile or buggy tool would try; every one must be refused,
+        // not silently absorbed into state a later call could read.
+        for (const write of [
+          () => { (context.principal as any).userId = 'usr_admin_evil'; },
+          () => { (context.principal as any).organizationId = 'org_victim'; },
+          () => { (context.principal.scopes as any).push(MCP_OAUTH_SCOPE_DATA_WRITE); },
+          () => { (context.actor as any).id = 'usr_admin_evil'; },
+        ]) {
+          try { write(); attempts.push('absorbed'); } catch (e) { attempts.push(e); }
+        }
+        return {
+          type: 'tool-result',
+          toolCallId: toolCall.toolCallId,
+          toolName: toolCall.toolName,
+          output: { type: 'text', value: 'ok' },
+        } as ToolExecutionResult;
+      },
+    };
+    const o: CallOptions = { grantedScopes: GRANT, registry: tainting }; // the harness injects PRINCIPAL + ENVIRONMENT_ID
+    await callTool(runtime, bridge, 'verify_build', {}, o);
+    await callTool(runtime, bridge, 'verify_build', {}, o);
+    expect(registry.calls).toHaveLength(2);
+    // Every write was refused (strict-mode TypeError on a frozen object), none absorbed.
+    expect(attempts).toHaveLength(8);
+    for (const a of attempts) expect(a).toBeInstanceOf(TypeError);
+    const [first, second] = registry.calls.map((c) => c.context);
+    expect(Object.isFrozen(first.principal)).toBe(true);
+    expect(Object.isFrozen(first.principal.scopes)).toBe(true);
+    expect(Object.isFrozen(first.actor)).toBe(true);
+    // A copy, not the host's reference — and a copy per call, not one shared copy.
+    expect(first.principal).not.toBe(PRINCIPAL);
+    expect(second.principal).not.toBe(first.principal);
+    expect(first.principal.scopes).not.toBe(PRINCIPAL.scopes);
+    // The second call still sees the host's principal, byte for byte …
+    expect(second.principal).toEqual(PRINCIPAL);
+    expect(second.actor).toEqual({ id: PRINCIPAL.userId });
+    // … and the host's own object is untouched.
+    expect(PRINCIPAL).toEqual({
+      userId: 'usr_dev_1',
+      organizationId: 'org_acme',
+      clientId: 'claude-code',
+      scopes: [MCP_OAUTH_SCOPE_METADATA_WRITE],
+    });
+  });
+
+  it('a tool name already on the server is refused at registration (the SDK throws), so a host keeps its names unique', () => {
+    const server = new McpServer({ name: 'x', version: '0' });
+    const first = registerAuthoringTools(server, { registry, principal: PRINCIPAL }, GRANT);
+    expect(first).toEqual(AUTHORING_TOOLS.map((t) => t.name));
+    // The same names a second time — as a registry that duplicates one of its own, or one
+    // that reuses a native name, would — is thrown back by the SDK, not merged or shadowed.
+    expect(() => registerAuthoringTools(server, { registry, principal: PRINCIPAL }, GRANT)).toThrow(/already registered/i);
+  });
+
   it('an environment the host did not name is absent from the context, not undefined-valued', async () => {
     const server = new McpServer({ name: 'x', version: '0' });
     const names = registerAuthoringTools(server, { registry, principal: PRINCIPAL }, GRANT);
 
@@ -10,6 +10,7 @@ import { MCP_TOOL_DOOR } from './types.js';
 import type {
   McpAuthoringInjection,
   McpAuthoringToolContext,
+  McpTokenPrincipal,
   ToolRegistry,
   ToolExecutionResult,
 } from './types.js';
@@ -1130,7 +1131,16 @@ function registerToolFromDefinition(
  * so no header can reach the context — a client sending `x-door`,
  * `x-environment-id` or any other spelling changes nothing a tool sees. The
  * host's access check and tier mapping read the door from the context; that is
- * the whole reason it is stamped on the server side of the transport.
+ * the whole reason it is stamped on the server side of the transport. The
+ * principal (and its `scopes` array) is copied and frozen per call, so a tool
+ * that writes into its context taints neither the next call nor the host's
+ * object.
+ *
+ * Tool names are the host's to keep unique: the SDK refuses a second
+ * registration under a name already on the server — a native name such as
+ * `describe_object`, or a duplicate within the registry — by throwing, and
+ * the request fails with it. A host checks its names against the native
+ * surface before injecting.
  *
  * ## What stays the host's
  *
@@ -1154,12 +1164,22 @@ export function registerAuthoringTools(
   if (!grantsAuthoringTools(grantedScopes)) return registered;
 
   const { registry, principal, environmentId } = authoring;
-  const provenance = (): McpAuthoringToolContext => ({
-    door: MCP_TOOL_DOOR,
-    actor: { id: principal.userId },
-    principal,
-    ...(environmentId !== undefined ? { environmentId } : {}),
-  });
+  // Each call gets its own FROZEN copy of the principal (and of its one array,
+  // `scopes`): a tool that writes into its context taints neither the next
+  // call in this request nor the host's own object. The context object itself
+  // is fresh per call for the same reason.
+  const provenance = (): McpAuthoringToolContext => {
+    const frozenPrincipal: McpTokenPrincipal = Object.freeze({
+      ...principal,
+      ...(principal.scopes !== undefined ? { scopes: Object.freeze([...principal.scopes]) } : {}),
+    });
+    return {
+      door: MCP_TOOL_DOOR,
+      actor: Object.freeze({ id: frozenPrincipal.userId }),
+      principal: frozenPrincipal,
+      ...(environmentId !== undefined ? { environmentId } : {}),
+    };
+  };
 
   for (const tool of registry.getAll()) {
     registerToolFromDefinition(server, tool, (call) => registry.execute(call, provenance()), logger);
 
@@ -164,4 +164,18 @@ describe('SKILL.md ↔ native tool surface drift guard', () => {
       expect(mdWithoutScope).not.toContain(t.name);
     }
   });
+
+  it('[#26464] the Build section names no native tool the same grant does not register (metadata:write alone has no data tool)', async () => {
+    const registry = makeAuthoringRegistry();
+    const native = await listRegisteredToolNames({ grantedScopes: EVERY_SCOPE });
+    expect(native.length).toBeGreaterThanOrEqual(9);
+    const metadataOnly = await listRegisteredToolNames({ grantedScopes: [MCP_OAUTH_SCOPE_METADATA_WRITE], registry });
+    expect(metadataOnly.sort()).toEqual(AUTHORING_TOOLS.map((t) => t.name).sort());
+
+    const md = renderSkillMarkdown({ grantedScopes: [MCP_OAUTH_SCOPE_METADATA_WRITE], authoringTools: registry.getAll() });
+    const section = md.slice(md.indexOf('## Build — authoring tools'), md.indexOf('## Conventions & gotchas'));
+    expect(section.length).toBeGreaterThan(0);
+    const taughtButUnregistered = native.filter((name) => section.includes(name) && !metadataOnly.includes(name));
+    expect(taughtButUnregistered, `the Build section teaches a tool this grant does not register: ${taughtButUnregistered.join(', ')}`).toEqual([]);
+  });
 });
@@ -85,6 +85,25 @@ describe('[#26464] renderSkillMarkdown — the authoring section follows the gra
     expect(OBJECTSTACK_SKILL_DESCRIPTION_WITH_AUTHORING).not.toContain('\n');
   });
 
+  it('metadata:write alone does not teach describe_object in the Build section — that grant registers no data tool', () => {
+    const md = renderSkillMarkdown({ grantedScopes: [MCP_OAUTH_SCOPE_METADATA_WRITE], authoringTools: TOOLS });
+    const section = md.slice(md.indexOf(SECTION), md.indexOf('## Conventions & gotchas'));
+    expect(section).not.toContain('describe_object');
+    expect(section).not.toContain('list_objects');
+    expect(section).toContain('no `data:read`');
+    expect(section).toMatch(/before you change an object/);
+  });
+
+  it('metadata:write beside data:read teaches describe_object before a change — the same grant registers it', () => {
+    const md = renderSkillMarkdown({
+      grantedScopes: [MCP_OAUTH_SCOPE_DATA_READ, MCP_OAUTH_SCOPE_METADATA_WRITE],
+      authoringTools: TOOLS,
+    });
+    const section = md.slice(md.indexOf(SECTION), md.indexOf('## Conventions & gotchas'));
+    expect(section).toContain('`describe_object` on an object');
+    expect(section).not.toContain('no `data:read`');
+  });
+
   it('the section is placed after the native tools and before the conventions, with the data content untouched', () => {
     const md = renderSkillMarkdown({ grantedScopes: [MCP_OAUTH_SCOPE_METADATA_WRITE], authoringTools: TOOLS });
     const tools = md.indexOf('## Tools');
 
@@ -31,7 +31,7 @@
  */
 
 import type { AIToolDefinition } from '@objectstack/spec/contracts';
-import { MCP_OAUTH_SCOPE_METADATA_WRITE } from '@objectstack/spec/ai';
+import { MCP_OAUTH_SCOPE_DATA_READ, MCP_OAUTH_SCOPE_METADATA_WRITE } from '@objectstack/spec/ai';
 import { grantsAuthoringTools } from './mcp-http-tools.js';
 
 /** Skill identity (mirrors the `SKILL.md` YAML frontmatter). */
@@ -108,8 +108,17 @@ function oneLine(text: string): string {
  * UI — from the same source as the data loop, so the client model learns both
  * the same way. Tool names come from the host; none is hard-coded here.
  */
-function renderAuthoringSection(tools: ReadonlyArray<Pick<AIToolDefinition, 'name' | 'description'>>): string {
+function renderAuthoringSection(
+  tools: ReadonlyArray<Pick<AIToolDefinition, 'name' | 'description'>>,
+  describeObjectRegistered: boolean,
+): string {
   const bullets = tools.map((t) => `- **${t.name}** — ${oneLine(t.description)}`).join('\n');
+  // Name `describe_object` only when the same grant registers it (the data
+  // gate: `data:read`). A metadata:write-only connection has no data tool, so
+  // teaching one there would be teaching a tool the server refuses.
+  const discover = describeObjectRegistered
+    ? 'Discover first here too — `describe_object` on an object\nbefore you change it.'
+    : 'Your grant carries no `data:read`, so the data tools are not on this\nconnection: read the current state through the authoring tools\' own verify\nstep before you change an object.';
   return `
 ## Build — authoring tools (\`${MCP_OAUTH_SCOPE_METADATA_WRITE}\`)
 
@@ -125,8 +134,7 @@ broken.
 The build loop is **create → verify → draft**: create or change the metadata,
 verify it (the environment validates what you wrote and reports what it
 refuses, so read the result before the next step), and leave it as a draft for
-a person to publish. Discover first here too — \`describe_object\` on an object
-before you change it.
+a person to publish. ${discover}
 
 ${bullets}
 `;
@@ -150,6 +158,8 @@ export function renderSkillMarkdown(options: RenderSkillOptions = {}): string {
       ? options.authoringTools
       : undefined;
   const description = authoringTools ? OBJECTSTACK_SKILL_DESCRIPTION_WITH_AUTHORING : OBJECTSTACK_SKILL_DESCRIPTION;
+  // Mirrors the native data gate in `wireBridgeTools` (`!scopes || scopes.includes(data:read)`).
+  const describeObjectRegistered = !options.grantedScopes || options.grantedScopes.includes(MCP_OAUTH_SCOPE_DATA_READ);
 
   return `---
 name: ${OBJECTSTACK_SKILL_NAME}
@@ -264,7 +274,7 @@ create/update payload.
   screen, which you fill with another \`resume_run\`. Only the user whose call
   started the run can resume it, under the same gates as \`run_action\`
   (including \`confirm: true\` for an action flagged \`requiresConfirmation\`).
-${authoringTools ? renderAuthoringSection(authoringTools) : ''}
+${authoringTools ? renderAuthoringSection(authoringTools, describeObjectRegistered) : ''}
 ## Conventions & gotchas
 
 - **Permissions/RLS apply to every call.** Fewer rows than expected, or a
 
@@ -71,7 +71,7 @@ export interface McpAuthoringToolContext extends ToolExecutionContext {
   door: McpToolDoor;
   /** The token's user, as the actor a `ToolExecutionContext` reader expects (RLS on, as that user). */
   actor: { id: string };
-  /** The token principal, verbatim from the host. */
+  /** The token principal: a frozen per-call copy of what the host passed, so a tool cannot taint the next call. */
   principal: McpTokenPrincipal;
   /** The environment the request was dispatched for, verbatim from the host. */
   environmentId?: string;
@@ -98,9 +98,17 @@ export interface McpAuthoringToolRegistry {
  * provenance of every call into it.
  */
 export interface McpAuthoringInjection {
-  /** The authoring registry — which tools it holds is the host's business. */
+  /**
+   * The authoring registry — which tools it holds is the host's business. Its
+   * names must not collide with the native surface or with each other: the SDK
+   * throws on a duplicate registration and the request fails with it.
+   */
   registry: McpAuthoringToolRegistry;
-  /** The token principal the host resolved for this request. */
+  /**
+   * The token principal the host resolved for this request — from the SAME
+   * token whose scopes the host passes as `toolOptions.grantedScopes`, since
+   * that list is what admits the registry. Copied and frozen per call.
+   */
   principal: McpTokenPrincipal;
   /** The environment the host dispatched this request for. */
   environmentId?: string;