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

package/server/service/assistant/abort-notice.ts

@@ -10,35 +10,57 @@
  * and the person acts on half of it. That failure is silent by construction, which is why the
  * notice belongs beside the loop rather than beside each product's prose.
  *
- * ── Known debt: the strings are Korean ─────────────────────────────────────────
- * They were Korean in board-ai and they still are. Moving them does not make that worse, but a
- * framework package is the wrong home for untranslated user-facing text. When this needs a second
- * locale, the shape is a caller-supplied translator, not a table in here — the notice is one line
- * appended to a reply the product already owns.
+ * ── The words are the reader's, and the caller owns the reader (2026-09-18) ────────
+ * These lines were Korean literals in a framework package, so every product said them in Korean
+ * whatever language the person was reading in (ADR-0049 ② · ADR-0054). The notice now names a key
+ * and carries an English default; a caller that has the request's translator hands it in and the
+ * person reads the line in their own language.
  */
 import type { AgenticLoopResult } from '../agentic-loop/index.js'
 import { isTransientAIError } from '../utils/index.js'
 
+/** Turns a key and its values into the reader's sentence. `ai-assistant` hands in the request's `context.t`. */
+export type TranslateNotice = (key: string, params?: Record<string, any>) => string
+
+/** The English sentence for each reason, used when the caller has no translator. */
+const NOTICE_DEFAULTS: Record<string, string> = {
+  'ai-assistant.notice.stopped': 'the request stopped partway, so only part of it was done.',
+  'ai-assistant.notice.provider-busy': 'the ai service did not answer just now. try again in a moment.',
+  'ai-assistant.notice.provider-error': 'something went wrong while handling this. tell an administrator if it keeps happening.',
+  'ai-assistant.notice.too-long': 'this ran long and stopped at step {iter}. try asking in smaller pieces.',
+  'ai-assistant.notice.tool-kept-failing': '{tool} failed {count} times in a row, so it stopped. try saying it differently.'
+}
+
+function line(key: string, params: Record<string, any>, t?: TranslateNotice): string {
+  const said = t
+    ? t(key, { defaultValue: NOTICE_DEFAULTS[key], ...params })
+    : Object.entries(params).reduce((text, [k, v]) => text.replaceAll(`{${k}}`, String(v)), NOTICE_DEFAULTS[key])
+  return `\n\n_(${said})_`
+}
+
 /**
  * 중단 이유 → 답에 덧붙일 한 줄. 정상 종료면 빈 문자열이다.
  *
  * 답을 고치지 않고 **뒤에 붙인다** — 모델이 한 말을 우리가 다시 쓰지 않는다.
  */
-export function formatAbortNotice(abortReason: AgenticLoopResult<any>['abortReason']): string {
+export function formatAbortNotice(
+  abortReason: AgenticLoopResult<any>['abortReason'],
+  t?: TranslateNotice
+): string {
   if (!abortReason) return ''
   switch (abortReason.type) {
     case 'aborted':
-      return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_'
+      return line('ai-assistant.notice.stopped', {}, t)
     case 'provider_error':
       /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
        * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
        * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
       return isTransientAIError({ message: abortReason.message })
-        ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
-        : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_'
+        ? line('ai-assistant.notice.provider-busy', {}, t)
+        : line('ai-assistant.notice.provider-error', {}, t)
     case 'max_iterations':
-      return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`
+      return line('ai-assistant.notice.too-long', { iter: abortReason.iter }, t)
     case 'repeated_validation_failure':
-      return `\n\n_(\`${abortReason.toolName}\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`
+      return line('ai-assistant.notice.tool-kept-failing', { tool: abortReason.toolName, count: abortReason.consecutive }, t)
   }
 }

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

@@ -76,7 +76,7 @@ describe('assistantChat — ① 중단 이유가 답에 닿는다', () => {
       })
     )
     expect(r.loop.abortReason?.type).toBe('provider_error')
-    expect(r.reply).toMatch(/다시/)
+    expect(r.reply).toMatch(/try again in a moment/)
     /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다. */
     expect(r.reply).not.toMatch(/503/)
     expect(r.reply).not.toMatch(/Error fetching/)
@@ -94,7 +94,29 @@ describe('assistantChat — ① 중단 이유가 답에 닿는다', () => {
       )
     )
     expect(r.loop.abortReason?.type).toBe('max_iterations')
-    expect(r.reply).toMatch(/중단/)
+    /* No translator was handed in, so the line falls back to English. */
+    expect(r.reply).toMatch(/stopped at step 2/)
+  })
+
+  it('★ 통지의 말은 읽는 사람의 것이다 — 번역기를 주면 그것이 쓴 문장이 붙는다', async () => {
+    const asked: any[] = []
+    const r = await assistantChat(
+      input(
+        {
+          options: { systemPrompt: 's', maxIterations: 2 },
+          chat: async () => okResult(undefined, [TC('read1')]),
+          t: (key: string, params: any) => {
+            asked.push({ key, params })
+            return `멈췄습니다(${params.iter}단계)`
+          }
+        },
+        { isReadTool: () => true }
+      )
+    )
+    expect(asked[0].key).toBe('ai-assistant.notice.too-long')
+    expect(asked[0].params.iter).toBe(2)
+    expect(asked[0].params.defaultValue).toMatch(/stopped at step/)
+    expect(r.reply).toContain('멈췄습니다(2단계)')
   })
 
   it('통지는 답을 고치지 않고 뒤에 붙는다', async () => {

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

@@ -36,9 +36,14 @@
  */
 import { runAgenticLoop, type AgenticLoopInput, type AgenticLoopResult } from '../agentic-loop/index.js'
 import { buildGroundedCorpus, groundingWarnings, type GroundingSources } from '../utils/index.js'
-import { formatAbortNotice } from './abort-notice.js'
+import { formatAbortNotice, type TranslateNotice } from './abort-notice.js'
 
 export interface AssistantChatInput<TCtx = unknown, TOp = unknown> extends AgenticLoopInput<TCtx, TOp> {
+  /**
+   * The request's translator, so a notice this function appends is in the reader's language
+   * (ADR-0054). Without it the notice falls back to English.
+   */
+  t?: TranslateNotice
   /**
    * 이 턴에 모델이 본 것 — **도구 결과 말고** 전부. 도구 결과는 이 함수가 루프에서 받아 더한다.
    *
@@ -86,7 +91,7 @@ export async function assistantChat<TCtx = unknown, TOp = unknown>(
   const loop = await runAgenticLoop<TCtx, TOp>(loopInput)
 
   const baseText = loop.lastText ?? ''
-  const reply = baseText + formatAbortNotice(loop.abortReason)
+  const reply = baseText + formatAbortNotice(loop.abortReason, input.t)
 
   let warnings: string[] | undefined
   if (!skipGrounding && baseText) {

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

@@ -307,3 +307,46 @@ describe('a client that cannot call tools', () => {
     await expect(registryAssistantChat(input({ client: {} as any }))).rejects.toThrow(/cannot call tools/)
   })
 })
+
+/*
+ * 도구가 「어느 대화에서 불렸나」를 안다 — ADR-0061 결정 3.
+ *
+ * 이 칸은 A2(모드를 서버가 등록한다)가 서기 전까지 비어 있었고 주석만 「A2 가 서면」이라고 적혀 있었다.
+ * A2 가 선 뒤에도 채우는 쪽이 없어서 도구는 계속 `host` 만 봤다 — 그것은 클라이언트가 채우는 칸이다.
+ */
+describe('the tool context carries the conversation', () => {
+  it('★ 부르는 쪽이 준 mode 가 도구에게 간다 — 서버의 값이다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({ client, toolCategories: ['figure-authoring'], mode: { kind: 'twin.space', target: 'SITE-1' } })
+    )
+
+    expect(ran[0].context.mode).toEqual({ kind: 'twin.space', target: 'SITE-1' })
+  })
+
+  it('★ 그 값은 `host` 와 섞이지 않는다 — 하나는 서버가, 하나는 클라이언트가 채운다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({
+        client,
+        toolCategories: ['figure-authoring'],
+        hostContext: { figureId: 'fig-1' },
+        mode: { kind: 'figure.modeller' }
+      })
+    )
+
+    expect(ran[0].context).toEqual(
+      toolCallContextFixture({ domainId: 'dom-1', userId: 'u-1', host: { figureId: 'fig-1' }, mode: { kind: 'figure.modeller' } })
+    )
+  })
+
+  it('mode 를 안 주면 그 칸은 없다 — 빈 값을 지어내지 않는다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(ran[0].context).not.toHaveProperty('mode')
+  })
+})

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

@@ -49,6 +49,14 @@ export interface RegistryAssistantInput {
   toolAccess?: ToolAccessCheck
   /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
   hostContext?: any
+  /**
+   * Which conversation this is — `{ kind, target }` from the registered mode (ADR-0061 decision 3).
+   *
+   * Tools see it as `context.mode`. It is the server's value, resolved from the registry before the
+   * turn runs, so a tool that behaves differently in two conversations reads it here and not from
+   * `host`, which the client fills.
+   */
+  mode?: { kind: string; target?: string }
   /** Caller's koa state (domain, user, tx). Tools that read the database need it. */
   state: any
   model?: string
@@ -56,6 +64,8 @@ export interface RegistryAssistantInput {
   maxTokens?: number
   /** Make the model call a tool before it may answer. For surfaces that report live state. */
   requireToolOnFirstTurn?: boolean
+  /** The request's translator — the stop notice is then in the reader's language. */
+  t?: (key: string, params?: Record<string, any>) => string
   /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
   groundingSources?: Omit<GroundingSources, 'toolResults'>
 }
@@ -104,7 +114,11 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
   const guidance = toolScopeGuidance(scope)
   const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt
 
-  const toolContext: ToolCallContext = { state, host: hostContext ?? {} }
+  /*
+   * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기
+   * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.
+   */
+  const toolContext: ToolCallContext = { state, host: hostContext ?? {}, ...(input.mode ? { mode: input.mode } : {}) }
 
   const result = await assistantChat<ToolCallContext, unknown>({
     initialConversation: messages,
@@ -135,7 +149,8 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
       toolCallToOp: () => null,
       summarizeToolResult
     },
-    groundingSources: input.groundingSources
+    groundingSources: input.groundingSources,
+    t: input.t
   })
 
   return { ...result, offeredTools: tools.map(tool => tool.name) }

package/server/service/capability.test.ts

@@ -0,0 +1,52 @@
+/*
+ * What this guards: a screen can ask whether this deployment has an AI, instead of finding out by
+ * pressing a button that fails.
+ *
+ * The defect this replaces: twin decided the same question from whether a mutation had thrown once.
+ * The mutation stopped being called, the flag stayed true, and deployments with no provider showed
+ * the button anyway (standard A7-a).
+ */
+const mockConfigGet = jest.fn()
+jest.mock('@things-factory/env', () => ({ config: { get: (...args: any[]) => mockConfigGet(...args) } }))
+
+import { aiCapability } from './capability'
+import { registerAIProvider, setDefaultAIClient } from './factory'
+
+beforeEach(() => {
+  mockConfigGet.mockReset()
+  setDefaultAIClient(undefined as any)
+})
+
+it('★ a configured deployment says so, and names what answers', () => {
+  mockConfigGet.mockReturnValue(null)
+  setDefaultAIClient({ id: 'anthropic:claude-sonnet-5' } as any)
+
+  expect(aiCapability()).toEqual({ state: 'configured', provider: 'anthropic', model: 'claude-sonnet-5' })
+})
+
+it('★ no configuration at all is "not configured", with the reason — never silence', () => {
+  mockConfigGet.mockReturnValue(null)
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-config' })
+})
+
+it('a configuration naming a provider nobody registered says which one', () => {
+  mockConfigGet.mockReturnValue({ provider: 'nonesuch', model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'nonesuch', reason: 'unknown-provider' })
+})
+
+it('a configuration with no provider field is its own reason', () => {
+  mockConfigGet.mockReturnValue({ model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-provider' })
+})
+
+it('★ a provider whose adapter throws is not configured — it does not throw at the caller', () => {
+  registerAIProvider('explodes', () => {
+    throw new Error('no api key')
+  })
+  mockConfigGet.mockReturnValue({ provider: 'explodes', model: 'x' })
+
+  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'explodes', model: 'x', reason: 'no-adapter' })
+})

package/server/service/capability.ts

@@ -0,0 +1,58 @@
+/**
+ * Is there an AI on this deployment, and what is missing — asked before anything is tried.
+ *
+ * The twin had a button that asked the assistant, and whether to show it was decided by whether a
+ * now-dead mutation had failed once. When the dock moved to the neutral door nothing called that
+ * mutation any more, so the answer was "configured" forever: the button appeared on deployments
+ * with no provider at all and failed when pressed (standard A7-a).
+ *
+ * A capability is read, not discovered by failing (ADR-0042 decision ②). It lives here because the
+ * provider configuration does, and the answer has three states — the third is the one a screen
+ * must not fold away: **not asked yet** is not "configured".
+ */
+import { config as envConfig } from '@things-factory/env'
+
+import { getDefaultAIClient, listRegisteredProviders } from './factory.js'
+
+export type AiCapabilityState = 'configured' | 'not-configured'
+
+export interface AiCapability {
+  state: AiCapabilityState
+  /** Which provider answers, when one does — for the person reading a boot log, not for a screen. */
+  provider?: string
+  /** The default model this deployment would use. */
+  model?: string
+  /** Why it is not configured, as a code: no-config · no-provider · unknown-provider · no-adapter. */
+  reason?: string
+}
+
+/**
+ * What this server can do, as of now.
+ *
+ * Creating the client is what proves a provider adapter is loaded and the configuration parses, so
+ * this asks for it. It never throws: a deployment with no AI is a normal deployment.
+ */
+export function aiCapability(): AiCapability {
+  const client = safeDefaultClient()
+  if (client) {
+    const [provider, model] = String(client.id ?? '').split(':')
+    return { state: 'configured', provider: provider || undefined, model: model || undefined }
+  }
+
+  const cfg = envConfig.get('aiClient', null) as { provider?: string; model?: string } | null
+  if (!cfg) return { state: 'not-configured', reason: 'no-config' }
+  if (!cfg.provider) return { state: 'not-configured', reason: 'no-provider' }
+  if (!listRegisteredProviders().includes(cfg.provider)) {
+    return { state: 'not-configured', provider: cfg.provider, reason: 'unknown-provider' }
+  }
+  return { state: 'not-configured', provider: cfg.provider, model: cfg.model, reason: 'no-adapter' }
+}
+
+function safeDefaultClient() {
+  try {
+    return getDefaultAIClient()
+  } catch {
+    /* A broken configuration is "not configured", and it is the reason below that says which. */
+    return undefined
+  }
+}

package/server/service/index.ts

@@ -6,4 +6,6 @@ export * from './tool-registry/index.js'
 export * from './agentic-loop/index.js'
 export * from './assistant/index.js'
 export * from './analysis-contract.js'
+/* 「이 배포에 AI 가 있나」 — 시도해서 알아내지 않고 먼저 읽는다(표준 A7-a). */
+export * from './capability.js'
 export * from './testing/tool-call-context.js'

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

@@ -23,6 +23,16 @@ afterEach(() => {
 })
 
 // 헬퍼 — 카테고리 fixture
+/**
+ * 권한 축의 경고만 — 문 축(`tool-doors-undeclared`)은 자기 시험이 따로 본다.
+ *
+ * 한 시험이 두 축을 함께 세면, 한 축에 코드가 하나 늘 때마다 다른 축의 시험이 빨개진다. 그러면 고치는
+ * 사람은 자기가 건드리지 않은 시험을 고치게 되고, 그 손질이 시험을 무디게 만든다.
+ */
+function privilegeWarnings() {
+  return getToolRegistryWarnings().filter(w => w.code !== 'tool-doors-undeclared')
+}
+
 function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
   return {
     name,
@@ -272,7 +282,7 @@ describe('registry — a tool that changes something names its door (A1, stage o
         specs: [{ kind, name: 'changesThings', description: 'd', schema: {}, builder: () => null } as any]
       })
       expect(getToolKind('changesThings')).toBe(kind)
-      expect(getToolRegistryWarnings()).toEqual([
+      expect(privilegeWarnings()).toEqual([
         expect.objectContaining({
           code: 'tool-privilege-undeclared',
           params: { category: 'no-door', tool: 'changesThings', kind }
@@ -289,21 +299,92 @@ describe('registry — a tool that changes something names its door (A1, stage o
         { kind: 'external', name: 'halfDoor', description: 'd', schema: {}, builder: () => null, privilege: { category: 'board' } } as any
       ]
     })
-    expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
+    expect(privilegeWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
+  })
+
+  test('a declared tool leaves no warning', () => {
+    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }]))
+    expect(privilegeWarnings()).toEqual([])
+  })
+
+  /*
+   * 읽는 도구도 자기가 닿는 문을 말한다(ADR-0071 결정 2). 그전까지 업무 권한을 스스로 확인하는 것은
+   * plant 뿐이었고, twin · figure 의 읽는 도구는 테넌트만 봤다 — 대화 문 권한만 있으면 그 자료를 읽었다.
+   */
+  test('★ a read tool that says nothing about its door is recorded too', () => {
+    registerToolCategory(makeCategory('reads', [{ name: 'r1', kind: 'read' }]))
+
+    expect(privilegeWarnings()).toEqual([
+      expect.objectContaining({ code: 'tool-privilege-undeclared', params: { category: 'reads', tool: 'r1', kind: 'read' } })
+    ])
   })
 
-  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('★ `doors: []` is an answer — a tool that reaches no door has nothing to gate', () => {
+    registerToolCategory({
+      name: 'surface-only',
+      guidance: '- fixture guidance for surface-only',
+      specs: [
+        { kind: 'read', name: 'getOpenScene', description: 'd', schema: {}, builder: () => null, doors: [] } as any
+      ]
+    })
+
+    expect(privilegeWarnings()).toEqual([])
+  })
+
+  test('★ a named door with no privilege of its own is its own fact, not an omission', () => {
+    registerToolCategory({
+      name: 'waiting',
+      guidance: '- fixture guidance for waiting',
+      specs: [
+        { kind: 'read', name: 'twinNowTool', description: 'd', schema: {}, builder: () => null, doors: ['Query.twinNow'] } as any
+      ]
+    })
+
+    expect(privilegeWarnings()).toEqual([
+      expect.objectContaining({
+        code: 'tool-door-has-no-privilege',
+        params: { category: 'waiting', tool: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }
+      })
+    ])
+  })
+
+  /*
+   * 문을 안 적은 도구는 그 답을 **아무도 못 읽게 만든다** — 쓴 사람 본인까지.
+   *
+   * ADR-0073 뒤로 답 행에 도구가 지난 문이 적히고, 선언이 없는 도구는 `unresolved:<도구>` 로 적혀
+   * 아무도 못 지난다. 2026-09-18 트윈 모델러에서 저작 대화의 답이 새로 고친 뒤 작성자에게
+   * 「이 답을 볼 권한이 없습니다」로 보였다.
+   *
+   * 부팅은 그때 아무 말도 안 했다. 권한 검사가 `privilege` 가 있으면 건너뛰는 자리에서 문 검사까지
+   * 함께 건너뛰었기 때문이다 — 트윈의 저작 도구 넷이 정확히 그 모양이었다(권한 있음, 문 없음).
+   */
+  test('★ a tool that declares no doors is reported even when it declares a privilege', () => {
+    registerToolCategory(
+      makeCategory('authoring', [
+        { name: 'proposeSceneEdit', kind: 'write', privilege: { category: 'board', privilege: 'mutation' } }
+      ])
+    )
+
+    const doors = getToolRegistryWarnings().filter(w => w.code === 'tool-doors-undeclared')
+    expect(doors.map(w => w.params.tool)).toEqual(['proposeSceneEdit'])
+  })
+
+  test('★ `doors: []` is a declaration — it says this tool reaches none', () => {
+    registerToolCategory(makeCategory('surface', [{ name: 'getOpenScene', kind: 'read', doors: [] }]))
+
+    expect(getToolRegistryWarnings().filter(w => w.code === 'tool-doors-undeclared')).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] })
+    const once = getToolRegistryWarnings().map(w => w.code).sort()
+
     registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
-    expect(getToolRegistryWarnings()).toHaveLength(1)
+    /* 두 번 등록해도 한 번 등록한 것과 같아야 한다 — 축이 몇이든. */
+    expect(getToolRegistryWarnings().map(w => w.code).sort()).toEqual(once)
 
     registerToolCategory({ name: 'again', guidance: '- g', specs: [{ ...undeclared, privilege: { category: 'c', privilege: 'mutation' } }] })
-    expect(getToolRegistryWarnings()).toEqual([])
+    expect(privilegeWarnings()).toEqual([])
   })
 })

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

@@ -31,8 +31,14 @@ 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'] }
+  /**
+   * `tool-privilege-undeclared` — nothing said which door this tool reaches.
+   * `tool-door-has-no-privilege` — the door was named and it declares no privilege of its own yet
+   *   (twin's queries, waiting on AUTH stage two). The tool cannot be stricter than its door, so
+   *   this is a different fact from saying nothing, and the report keeps the two apart.
+   */
+  code: 'tool-privilege-undeclared' | 'tool-door-has-no-privilege' | 'tool-doors-undeclared'
+  params: { category: string; tool: string; kind: ToolSpec['kind']; doors?: string[] }
   /** For a person reading it; the code and params are what callers act on. */
   message: string
 }
@@ -89,22 +95,71 @@ export function registerToolCategory(category: ToolCategory): void {
    * is empty across the apps, this becomes a refusal.
    */
   warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name))
+
+  /*
+   * ── 문을 안 적은 도구는 그 답을 **아무도 못 읽게 만든다** ─────────────────
+   *
+   * ADR-0073 뒤로 어시스턴트의 답 행에는 그 답을 만든 도구들이 지난 문이 적힌다. 선언이 없는 도구는
+   * `unresolved:<도구>` 로 적히고 그 이름은 아무도 못 지난다 — **답을 쓴 본인도** 새로 고치면
+   * 「이 답을 볼 권한이 없습니다」를 본다. 2026-09-18 트윈 모델러에서 그렇게 나왔다.
+   *
+   * 이 검사를 권한 검사와 따로 도는 이유가 그것이다. 아래 고리는 `privilege` 가 있으면 건너뛰는데,
+   * 문을 안 적은 해는 권한을 적었는지와 상관이 없다. 트윈의 저작 도구 넷이 정확히 그 자리였다 —
+   * 권한은 있고 문은 없어서 부팅이 아무 말도 안 했다.
+   */
   for (const spec of category.specs) {
-    if (spec.kind !== 'read' && !(spec.privilege?.category && spec.privilege?.privilege)) {
+    if (Array.isArray(spec.doors)) continue
+
+    warnings.push({
+      code: 'tool-doors-undeclared',
+      params: { category: category.name, tool: spec.name, kind: spec.kind },
+      message:
+        `tool '${spec.name}' in category '${category.name}' declares no doors, so answers built with it ` +
+        'are hidden from every reader including their author — declare `doors`, or `doors: []` when it reaches none'
+    })
+  }
+
+  for (const spec of category.specs) {
+    const declared = Boolean(spec.privilege?.category && spec.privilege?.privilege)
+    if (declared) continue
+
+    /*
+     * An empty list says this tool reaches no door — the ones that hand back what the surface sent
+     * are that. Nothing to gate, nothing to report.
+     */
+    if (Array.isArray(spec.doors) && spec.doors.length === 0) continue
+
+    if (spec.doors?.length) {
+      /*
+       * The door is named and carries no privilege yet. The tool cannot be stricter than the door
+       * it reaches, so this is not an omission by whoever wrote the tool — it is the door's turn
+       * (ADR-0071 decision 2). Reported under its own code so the two are not read as one list.
+       */
       warnings.push({
-        code: 'tool-privilege-undeclared',
-        params: { category: category.name, tool: spec.name, kind: spec.kind },
+        code: 'tool-door-has-no-privilege',
+        params: { category: category.name, tool: spec.name, kind: spec.kind, doors: spec.doors },
         message:
-          `tool '${spec.name}' in category '${category.name}' is '${spec.kind}' but declares no privilege — ` +
-          'declare the same { category, privilege } its GraphQL door uses'
+          `tool '${spec.name}' reaches ${spec.doors.join(' + ')} and declares no privilege of its own — ` +
+          'whether those doors require anything is asked at boot, against the schema, not copied here ' +
+          '(ADR-0072 decision 5)'
       })
+      continue
     }
+
+    warnings.push({
+      code: 'tool-privilege-undeclared',
+      params: { category: category.name, tool: spec.name, kind: spec.kind },
+      message:
+        `tool '${spec.name}' in category '${category.name}' declares no privilege of its own — ` +
+        'a tool that changes something says who may run it. What the doors it reaches require is a ' +
+        "separate question, answered at boot against the schema (`tool-door-not-in-schema`)."
+    })
   }
 
   if (categories.has(category.name)) {
     console.warn(
       `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
-        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`
+        '(normal on a dev hot reload; in production it means the same category is registered twice)'
     )
   }
 

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

@@ -155,10 +155,35 @@ export interface ToolSpecBase {
    * The privilege a caller needs before this tool is offered or run. See `ToolPrivilege`.
    *
    * Expected for `write`, `action` and `external` — registration records a
-   * `tool-privilege-undeclared` warning for one without it (A1 stage one). A `read` tool without it is
-   * offered on domain membership alone, and its builder must check what it reads.
+   * `tool-privilege-undeclared` warning for one without it (A1 stage one).
    */
   privilege?: ToolPrivilege
+
+  /**
+   * Which GraphQL doors this tool reaches — `['Query.twinNow']`,
+   * `['Query.productionSummary', 'Query.pendingSummary']`.
+   *
+   * **A read tool names its doors too** (ADR-0071 decision 2, shaped by ADR-0072). Before that,
+   * only plant's tools asked whether the caller may read what they read; twin's and figure's
+   * checked the tenant and nothing else, so holding the conversation's own privilege was enough to
+   * reach their business data.
+   *
+   * **Always a list, even for one** — one shape to read. A tool that answers from several doors
+   * needs the caller to hold **all** of them (AND, the same reading as AUTH's `requiresAll`):
+   * plant's factory overview answers from two, and asking for only one of them would hand back
+   * half of what the caller may not see.
+   *
+   * Three states, and the boot report keeps them apart:
+   *   - doors and a privilege — the gate checks it
+   *   - `doors: []` — this tool reaches no door at all. The ones that hand back what the surface
+   *     sent (`getOpenScene`, `getStationScreen`) are this: there is nothing behind them to gate.
+   *   - doors with no privilege — the doors themselves declare none yet (twin's queries, waiting
+   *     on AUTH stage two). A tool cannot be stricter than the door it reaches.
+   *
+   * The privilege is **the door's**, copied, and a test in each app compares the copy with the
+   * directive on that field. When the schema can be read at boot, the copy goes away.
+   */
+  doors?: string[]
 }
 
 export interface ReadToolSpec extends ToolSpecBase {