@things-factory/ai-client-base 10.1.20 → 10.1.26

package/server/service/assistant/registry-assistant.test.ts

@@ -13,6 +13,7 @@
  */
 import { registryAssistantChat } from './registry-assistant'
 import { clearToolRegistry, registerToolCategory } from '../tool-registry/index.js'
+import { toolCallContextFixture } from '../testing/tool-call-context.js'
 import type { AIToolCall, AIToolChatResult } from '../types.js'
 
 const TC = (name: string, args: any = {}, id = 't1'): AIToolCall =>
@@ -60,6 +61,7 @@ beforeEach(() => {
         kind: 'write',
         name: 'addComponent',
         description: 'adds a component to the document',
+        privilege: { category: 'board', privilege: 'mutation' },
         schema: { type: 'object', properties: {} },
         builder: () => {
           ran.push({ name: 'addComponent', args: {}, context: null })
@@ -74,7 +76,7 @@ beforeEach(() => {
     guidance: 'Never state a quantity you did not read.',
     specs: [
       {
-        kind: 'external',
+        kind: 'read',
         name: 'readOrderState',
         description: 'reads live order state',
         schema: { type: 'object', properties: {} },
@@ -85,6 +87,40 @@ beforeEach(() => {
       }
     ]
   } as any)
+
+  /*
+   * A category whose tools change something outside the conversation, each behind the same
+   * privilege its GraphQL door uses. This is the shape of board-import's `materializeImportSession`,
+   * which creates a Board.
+   */
+  registerToolCategory({
+    name: 'board-import',
+    guidance: 'Create a board only after the user confirms.',
+    specs: [
+      {
+        kind: 'read',
+        name: 'getImportSession',
+        description: 'reads an import session',
+        privilege: { category: 'board-import', privilege: 'query' },
+        schema: { type: 'object', properties: {} },
+        builder: (args: any, context: any) => {
+          ran.push({ name: 'getImportSession', args, context })
+          return { status: 'completed' }
+        }
+      },
+      {
+        kind: 'external',
+        name: 'materializeImportSession',
+        description: 'creates a board from an import session',
+        privilege: { category: 'board-import', privilege: 'mutation' },
+        schema: { type: 'object', properties: {} },
+        builder: (args: any, context: any) => {
+          ran.push({ name: 'materializeImportSession', args, context })
+          return { boardId: 'b-1' }
+        }
+      }
+    ]
+  } as any)
 })
 
 const input = (over: any = {}) => ({
@@ -98,7 +134,7 @@ const input = (over: any = {}) => ({
 describe('what the model is offered', () => {
   it('★ only the kinds that answer — a write tool is not offered to a surface with no document', async () => {
     const { client, seen } = recordingClient()
-    await registryAssistantChat(input({ client }))
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring', 'plant-ops'] }))
 
     const offered = seen[0].tools.map(tool => tool.name)
     expect(offered).toEqual(expect.arrayContaining(['listFigures', 'readOrderState']))
@@ -147,7 +183,7 @@ describe('running a tool', () => {
     const { client } = recordingClient([okResult(undefined, [TC('listFigures', { q: 'roller' })]), okResult('two of them')])
 
     const result = await registryAssistantChat(
-      input({ client, hostContext: { surface: 'figure-modeller', figureId: 'fig-1' } })
+      input({ client, toolCategories: ['figure-authoring'], hostContext: { surface: 'figure-modeller', figureId: 'fig-1' } })
     )
 
     expect(ran).toHaveLength(1)
@@ -158,10 +194,12 @@ describe('running a tool', () => {
     expect(result.reply).toContain('two of them')
   })
 
+
   it('★ a write tool call is not executed — the same set decides offering and dispatch', async () => {
     const { client } = recordingClient([okResult(undefined, [TC('addComponent')]), okResult('cannot do that')])
 
-    await registryAssistantChat(input({ client }))
+    /* The category is allowed; the kind is what keeps the write out. */
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
 
     expect(ran.map(one => one.name)).not.toContain('addComponent')
   })
@@ -175,6 +213,95 @@ describe('running a tool', () => {
   })
 })
 
+describe('what a tool is handed (A3)', () => {
+  it('★ exactly the shared shape — state and host side by side', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+    const state = { domain: { id: 'dom-1' }, user: { id: 'u-1' } }
+
+    await registryAssistantChat(input({ client, state, toolCategories: ['figure-authoring'], hostContext: { figureId: 'fig-1' } }))
+
+    expect(ran[0].context).toEqual(toolCallContextFixture({ domainId: 'dom-1', userId: 'u-1', host: { figureId: 'fig-1' } }))
+    expect(ran[0].context.state).not.toHaveProperty('host')
+  })
+
+  it('★ host is an empty object when the surface sent none — a tool never reads it off undefined', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(ran[0].context.host).toEqual({})
+  })
+})
+
+describe('who may use a tool (A1)', () => {
+  const grantAll = async () => true
+  const denyAll = async () => false
+
+  it('★ omitting the category list offers nothing and runs nothing', async () => {
+    const { client, seen } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('done')])
+
+    await registryAssistantChat(input({ client, toolAccess: grantAll }))
+
+    expect(seen[0].tools).toEqual([])
+    expect(ran).toHaveLength(0)
+  })
+
+  it('★ a tool that changes something outside is not offered here, even with the privilege', async () => {
+    const { client, seen } = recordingClient([okResult(undefined, [TC('materializeImportSession')]), okResult('done')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: grantAll }))
+
+    expect(seen[0].tools.map((t: any) => t.name)).not.toContain('materializeImportSession')
+    expect(ran.map(one => one.name)).not.toContain('materializeImportSession')
+  })
+
+  it('★ a tool behind a privilege the caller lacks is neither offered nor run when called by name', async () => {
+    const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: denyAll }))
+
+    expect(seen[0].tools.map((t: any) => t.name)).not.toContain('getImportSession')
+    expect(ran.map(one => one.name)).not.toContain('getImportSession')
+  })
+
+  it('★ with no access check at all, a tool behind a privilege stays closed', async () => {
+    const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['board-import'] }))
+
+    expect(seen[0].tools.map((t: any) => t.name)).not.toContain('getImportSession')
+    expect(ran.map(one => one.name)).not.toContain('getImportSession')
+  })
+
+  it('the access check is asked with the privilege the tool declares, and a grant opens the tool', async () => {
+    const asked: any[] = []
+    const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
+
+    await registryAssistantChat(
+      input({
+        client,
+        toolCategories: ['board-import'],
+        toolAccess: async (privilege: any) => {
+          asked.push(privilege)
+          return privilege.privilege === 'query'
+        }
+      })
+    )
+
+    expect(asked).toContainEqual({ category: 'board-import', privilege: 'query' })
+    expect(seen[0].tools.map((t: any) => t.name)).toContain('getImportSession')
+    expect(ran.map(one => one.name)).toContain('getImportSession')
+  })
+
+  it('guidance of a category whose every tool is withheld is not read to the model', async () => {
+    const { client, seen } = recordingClient()
+
+    await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: denyAll }))
+
+    expect(seen[0].options.systemPrompt).not.toContain('Create a board only after the user confirms.')
+  })
+})
+
 describe('a client that cannot call tools', () => {
   it('★ refuses instead of answering from nothing', async () => {
     await expect(registryAssistantChat(input({ client: {} as any }))).rejects.toThrow(/cannot call tools/)

package/server/service/assistant/registry-assistant.ts

@@ -9,28 +9,24 @@
  * operato-figure hit exactly that: the dock was mounted, the tools were registered, and the only
  * mutation that could run them lived in a package figure does not load.
  *
- * ── Read and external only ─────────────────────────────────────────────────────
+ * ── Read only ──────────────────────────────────────────────────────────────────
  * A registry category may also carry `write` and `action` tools. Those produce edit ops for a
  * document the host owns, and a host with no document cannot apply them. Offering them here would
  * declare a door with no road behind it — the model would call one and the call would go nowhere.
- * So this runner offers, and dispatches, `read` and `external` only. A host that owns a document
- * keeps assembling its own conversation, as board-ai does.
+ * `external` tools change something outside the conversation (board-import's
+ * `materializeImportSession` creates a Board) and this door has no confirm-and-apply step, so they
+ * are not offered either (A1, 2026-09-17). This runner offers, and dispatches, `read` only.
  *
  * The gate answers from the same list the definitions are built from, so what is offered and what
  * may be dispatched cannot drift apart.
  */
 import type { AIClient, AIMessage } from '../types.js'
-import { getCategoryGuidance, getToolSpecsFor, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'
+import { narrowToolScope, resolveToolScope, toolScopeGuidance, type ToolAccessCheck } from './tool-scope.js'
 import { assistantChat, type AssistantChatResult } from './assistant-chat.js'
 import { summarizeToolResult } from './summarize.js'
 import type { GroundingSources } from '../utils/index.js'
+import type { ToolCallContext } from '../tool-registry/types.js'
 
-/** What a registry tool is handed when it runs. `state` is the caller's koa state. */
-export interface RegistryToolCallContext {
-  state: any
-  /** What this surface is looking at — the host passes it through; tools read it as `host`. */
-  host?: any
-}
 
 export interface RegistryAssistantInput {
   /** Provider client. Must implement `chatWithTools`. */
@@ -40,12 +36,17 @@ export interface RegistryAssistantInput {
   /** Who the assistant is and what this surface is. The host owns this prose. */
   systemPrompt: string
   /**
-   * Categories this conversation may use. Omit to allow every registered category.
-   *
-   * An empty array is not the same as omitting: it allows nothing, and the conversation runs with
-   * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.
+   * Categories this conversation may use. **Omitting it allows nothing** — the same as an empty
+   * list, a plain conversation with no tools (A1, 2026-09-17). It used to mean every registered
+   * category, which is how a Board-creating tool reached any conversation.
    */
   toolCategories?: string[]
+  /**
+   * Answers whether the caller holds a tool's declared privilege. Without it, every tool that
+   * declares a privilege stays closed. The host builds it from the request — this package does
+   * not know auth.
+   */
+  toolAccess?: ToolAccessCheck
   /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
   hostContext?: any
   /** Caller's koa state (domain, user, tx). Tools that read the database need it. */
@@ -64,11 +65,6 @@ export interface RegistryAssistantResult extends AssistantChatResult<unknown> {
   offeredTools: string[]
 }
 
-/** `read` and `external` are the two kinds that answer a question without changing a document. */
-function answeringSpecs(filter: ToolCategoryFilter): ToolSpec[] {
-  return getToolSpecsFor(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external')
-}
-
 /**
  * Run one turn of a conversation whose only tools come from the registry.
  *
@@ -82,8 +78,17 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
     throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run')
   }
 
-  const filter: ToolCategoryFilter = toolCategories
-  const specs = answeringSpecs(filter)
+  /*
+   * Only `read` is offered here. `external` means the tool changes something outside the
+   * conversation (board-import's `materializeImportSession` creates a Board); this door answers
+   * questions and has no confirm-and-apply step, so a tool with an effect does not go through it
+   * even when the caller holds the privilege.
+   */
+  const scope = narrowToolScope(
+    await resolveToolScope(toolCategories, input.toolAccess),
+    spec => spec.kind === 'read'
+  )
+  const specs = scope.specs
   const byName = new Map(specs.map(spec => [spec.name, spec]))
 
   const tools = specs.map(spec => ({
@@ -96,12 +101,12 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
    * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so
    * a surface never reads instructions for a category it cannot call.
    */
-  const guidance = getCategoryGuidance(filter)
+  const guidance = toolScopeGuidance(scope)
   const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt
 
-  const toolContext: RegistryToolCallContext = { state, host: hostContext }
+  const toolContext: ToolCallContext = { state, host: hostContext ?? {} }
 
-  const result = await assistantChat<RegistryToolCallContext, unknown>({
+  const result = await assistantChat<ToolCallContext, unknown>({
     initialConversation: messages,
     tools,
     options: {

package/server/service/assistant/tool-scope.ts

@@ -0,0 +1,86 @@
+/*
+ * Which registered tools one conversation may use — decided once per request, before anything is
+ * offered, so offering and dispatch read the same list.
+ *
+ * ── Two questions, one list ───────────────────────────────────────────────────────
+ *   Which categories did this surface ask for?     `toolCategories`
+ *   Which of their tools may this caller use?      each spec's `privilege`, asked of `access`
+ *
+ * **Nothing asked means nothing offered.** Omitting the category list used to mean "every
+ * registered category"; that default is the one that opened board-import's Board-creating tool to
+ * any conversation. An absent answer leans to the closed side (ADR-0047 ② · ADR-0053).
+ *
+ * **No access check means privileged tools stay closed.** A caller that cannot say who is asking
+ * gets only the tools that need no privilege.
+ *
+ * The permission check itself belongs to auth, which this package does not depend on, so the host
+ * hands it in (`ai-assistant` builds it from the request state).
+ */
+import { getToolCategories, type ToolCategoryFilter } from '../tool-registry/index.js'
+import type { ToolPrivilege, ToolSpec } from '../tool-registry/types.js'
+
+/** Answers "may this caller use a door guarded by this privilege". */
+export type ToolAccessCheck = (privilege: ToolPrivilege) => Promise<boolean>
+
+export interface ScopedCategory {
+  readonly name: string
+  readonly guidance: string
+  /** The tools of this category this caller may use. Never empty — a category with none is left out. */
+  readonly specs: ReadonlyArray<ToolSpec>
+}
+
+export interface ToolScope {
+  /** Categories with at least one usable tool, in registration order. */
+  readonly categories: ReadonlyArray<ScopedCategory>
+  /** Every usable tool, flat. Offering and dispatch both read this. */
+  readonly specs: ReadonlyArray<ToolSpec>
+}
+
+export const EMPTY_TOOL_SCOPE: ToolScope = Object.freeze({ categories: [], specs: [] })
+
+const privilegeKey = (p: ToolPrivilege) => [p.category, p.privilege, !!p.owner, !!p.super].join('|')
+
+export async function resolveToolScope(requested: ToolCategoryFilter, access?: ToolAccessCheck): Promise<ToolScope> {
+  if (!requested || requested.length === 0) return EMPTY_TOOL_SCOPE
+
+  /* One check per distinct privilege — a category of ten read tools asks once. */
+  const answers = new Map<string, Promise<boolean>>()
+  const mayUse = (spec: ToolSpec): Promise<boolean> => {
+    const privilege = spec.privilege
+    if (!privilege) return Promise.resolve(true)
+    if (!access) return Promise.resolve(false)
+    const key = privilegeKey(privilege)
+    if (!answers.has(key)) answers.set(key, access(privilege).catch(() => false))
+    return answers.get(key)!
+  }
+
+  const categories: ScopedCategory[] = []
+  for (const category of getToolCategories()) {
+    if (!requested.includes(category.name)) continue
+    const allowed = await Promise.all(category.specs.map(mayUse))
+    const specs = category.specs.filter((_, i) => allowed[i])
+    if (specs.length > 0) categories.push({ name: category.name, guidance: String(category.guidance ?? '').trim(), specs })
+  }
+  return fromCategories(categories)
+}
+
+/**
+ * Keep only the tools a surface can run — e.g. a surface with no document keeps `read`. A category
+ * left with nothing drops out, so its guidance is not read to a model that cannot call it.
+ */
+export function narrowToolScope(scope: ToolScope, keep: (spec: ToolSpec) => boolean): ToolScope {
+  return fromCategories(
+    scope.categories
+      .map(category => ({ ...category, specs: category.specs.filter(keep) }))
+      .filter(category => category.specs.length > 0)
+  )
+}
+
+/** The rules of the categories in scope, for the system prompt. */
+export function toolScopeGuidance(scope: ToolScope): string[] {
+  return scope.categories.map(category => category.guidance).filter(Boolean)
+}
+
+function fromCategories(categories: ScopedCategory[]): ToolScope {
+  return { categories, specs: categories.flatMap(category => category.specs) }
+}

package/server/service/index.ts

@@ -6,3 +6,4 @@ export * from './tool-registry/index.js'
 export * from './agentic-loop/index.js'
 export * from './assistant/index.js'
 export * from './analysis-contract.js'
+export * from './testing/tool-call-context.js'

package/server/service/testing/tool-call-context.ts

@@ -0,0 +1,28 @@
+/*
+ * The one way a test builds what a registered tool is handed (A3, 2026-09-17).
+ *
+ * The twin's space tools read `ctx.state.host` while the door passed `ctx.host`, and their tests
+ * stayed green because each test wrote its own context in the shape the tool expected. A fixture
+ * owned by each test agrees with its tool by construction. This one is owned by the package that
+ * defines the neutral door, and that door's tests check it hands tools exactly this shape — so a tool
+ * test built on it fails when the tool reads a field no door fills.
+ */
+import type { ToolCallContext, ToolCallMode } from '../tool-registry/types.js'
+
+export interface ToolCallContextFixtureInput {
+  domainId?: string
+  userId?: string
+  /** Extra request-state fields a tool reads (e.g. `tx`). Merged after domain and user. */
+  state?: Record<string, any>
+  host?: Record<string, any>
+  mode?: ToolCallMode
+}
+
+export function toolCallContextFixture(input: ToolCallContextFixtureInput = {}): ToolCallContext {
+  const context: ToolCallContext = {
+    state: { domain: { id: input.domainId ?? 'domain-test' }, user: { id: input.userId ?? 'user-test' }, ...(input.state ?? {}) },
+    host: input.host ?? {}
+  }
+  if (input.mode) context.mode = input.mode
+  return context
+}

package/server/service/tool-registry/index.ts

@@ -13,15 +13,17 @@ export {
   getToolKind,
   hasTool,
   getCategorySpecs,
-  clearToolRegistry
+  clearToolRegistry,
+  getToolRegistryWarnings
 } from './registry'
 
 /* 대화별 노출 제한 타입은 registry 소유(정의가 거기 있다). */
-export type { ToolCategoryFilter } from './registry'
+export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'
 
 export type {
   ToolSpec,
   ToolSpecBase,
+  ToolPrivilege,
   ReadToolSpec,
   WriteToolSpec,
   ActionToolSpec,
@@ -33,5 +35,7 @@ export type {
   ExternalToolBuilder,
   ReadToolContext,
   WriteToolContext,
-  ExternalToolContext
+  ExternalToolContext,
+  ToolCallContext,
+  ToolCallMode
 } from './types'

package/server/service/tool-registry/registry.test.ts

@@ -14,7 +14,7 @@ import {
   getToolKind,
   hasTool,
   getCategorySpecs,
-  clearToolRegistry, getCategoryGuidance } from './registry'
+  clearToolRegistry, getCategoryGuidance, getToolRegistryWarnings } from './registry'
 import type { ToolCategory, ToolSpec } from './types'
 
 // 테스트 간 격리
@@ -34,6 +34,8 @@ function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
       description: 'desc',
       schema: {},
       builder: () => ({}),
+      /* A tool that changes something must name its door (A1). The fixture does, like guidance. */
+      ...(s.kind && s.kind !== 'read' ? { privilege: { category: 'fixture', privilege: 'mutation' } } : {}),
       ...s
     })) as ToolSpec[]
   }
@@ -174,6 +176,7 @@ describe('registry — spec 보존', () => {
           kind: 'write',
           name: 't1',
           description: 'main desc',
+          privilege: { category: 'fixture', privilege: 'mutation' },
           themeNote: '⚠ note',
           schema: { type: 'object' },
           builder: () => null
@@ -258,3 +261,49 @@ describe('registry — 지침 없는 카테고리는 등록되지 않는다', ()
     expect(getToolCategories()[0].guidance).toContain('fixture guidance')
   })
 })
+
+describe('registry — a tool that changes something names its door (A1, stage one: surface)', () => {
+  test.each(['write', 'action', 'external'] as const)(
+    '★ a %s tool without a privilege registers, and the omission is recorded as a code',
+    kind => {
+      registerToolCategory({
+        name: 'no-door',
+        guidance: '- fixture guidance for no-door',
+        specs: [{ kind, name: 'changesThings', description: 'd', schema: {}, builder: () => null } as any]
+      })
+      expect(getToolKind('changesThings')).toBe(kind)
+      expect(getToolRegistryWarnings()).toEqual([
+        expect.objectContaining({
+          code: 'tool-privilege-undeclared',
+          params: { category: 'no-door', tool: 'changesThings', kind }
+        })
+      ])
+    }
+  )
+
+  test('a privilege with no privilege name is recorded the same way', () => {
+    registerToolCategory({
+      name: 'half-door',
+      guidance: '- fixture guidance for half-door',
+      specs: [
+        { kind: 'external', name: 'halfDoor', description: 'd', schema: {}, builder: () => null, privilege: { category: 'board' } } as any
+      ]
+    })
+    expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
+  })
+
+  test('a declared tool and a read tool leave no warning', () => {
+    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }, { name: 'r1', kind: 'read' }]))
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+
+  test('re-registering a category replaces its warnings instead of piling them up', () => {
+    const undeclared = { kind: 'write', name: 'w9', description: 'd', schema: {}, builder: () => null } as any
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
+    expect(getToolRegistryWarnings()).toHaveLength(1)
+
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [{ ...undeclared, privilege: { category: 'c', privilege: 'mutation' } }] })
+    expect(getToolRegistryWarnings()).toEqual([])
+  })
+})

package/server/service/tool-registry/registry.ts

@@ -29,6 +29,24 @@ import type { ToolCategory, ToolSpec } from './types'
 
 const categories: Map<string, ToolCategory> = new Map()
 
+/** A registration that was accepted but is not yet what the contract requires. Code + params, not prose. */
+export interface ToolRegistryWarning {
+  code: 'tool-privilege-undeclared'
+  params: { category: string; tool: string; kind: ToolSpec['kind'] }
+  /** For a person reading it; the code and params are what callers act on. */
+  message: string
+}
+
+const warnings: ToolRegistryWarning[] = []
+
+/**
+ * What registration accepted but the contract does not yet allow. Stage one of A1 records these
+ * instead of refusing; a host shows them at boot, and when the list is empty the rule becomes a refusal.
+ */
+export function getToolRegistryWarnings(): ReadonlyArray<ToolRegistryWarning> {
+  return warnings.slice()
+}
+
 /**
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */
@@ -55,6 +73,34 @@ export function registerToolCategory(category: ToolCategory): void {
     )
   }
 
+  /*
+   * A tool that changes something must say which privilege it goes through (A1, 2026-09-17).
+   *
+   * The conversation door checks one privilege — may this person talk to the assistant. Without a
+   * privilege on the tool, that single check opened every tool behind it: a user holding only
+   * `ai-assistant:mutation` could reach board-import's `materializeImportSession` and create a
+   * Board.
+   *
+   * **This is stage one of two: surface, then refuse** (ADR-0037, "먼저 드러내고, 목록이 비면 막는다").
+   * Refusing now would stop every app whose tools predate the `privilege` field from booting, and
+   * those apps compile against an installed copy that does not have the field yet. So an undeclared
+   * tool still registers, and the omission is recorded as a code (`getToolRegistryWarnings`), not
+   * a log line — a warning only a log carries is not distinguishable from no warning. When the list
+   * is empty across the apps, this becomes a refusal.
+   */
+  warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name))
+  for (const spec of category.specs) {
+    if (spec.kind !== 'read' && !(spec.privilege?.category && spec.privilege?.privilege)) {
+      warnings.push({
+        code: 'tool-privilege-undeclared',
+        params: { category: category.name, tool: spec.name, kind: spec.kind },
+        message:
+          `tool '${spec.name}' in category '${category.name}' is '${spec.kind}' but declares no privilege — ` +
+          'declare the same { category, privilege } its GraphQL door uses'
+      })
+    }
+  }
+
   if (categories.has(category.name)) {
     console.warn(
       `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
@@ -180,4 +226,5 @@ export function getCategorySpecs(categoryName: string): ReadonlyArray<ToolSpec>
  */
 export function clearToolRegistry(): void {
   categories.clear()
+  warnings.length = 0
 }