ummaya 0.2.4 → 0.2.5

package/src/ummaya/ipc/stdio.py

@@ -33,7 +33,7 @@ import signal
 import sys
 import time
 import uuid
-from collections.abc import Callable, Collection
+from collections.abc import Callable, Collection, Iterable
 from datetime import UTC, datetime, timedelta
 from types import FrameType
 from typing import TYPE_CHECKING, Any, Final, Literal, cast
@@ -42,6 +42,10 @@ from opentelemetry import trace
 from opentelemetry.trace import Status, StatusCode
 from pydantic import TypeAdapter, ValidationError
 
+from ummaya.evidence.source_provenance_redaction import redact_source_text
+from ummaya.ipc.document_intent_normalization import (
+    _normalize_document_root_call_for_user_intent,
+)
 from ummaya.ipc.envelope import attach_envelope_span_attributes
 from ummaya.ipc.frame_schema import (
     ErrorFrame,
@@ -53,6 +57,7 @@ if TYPE_CHECKING:
     from ummaya.session.manager import SessionManager
     from ummaya.tools.executor import ToolExecutor
     from ummaya.tools.registry import ToolRegistry
+    from ummaya.tools.routing import RouteDecision
 
 logger = logging.getLogger(__name__)
 
@@ -74,6 +79,31 @@ _LEGACY_SCOPE_VERB_ALIASES: Final[dict[str, str]] = {
     "submit": "send",
     "verify": "check",
 }
+
+
+class _BackendSecretRedactionFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = self._redact_log_value(record.msg)
+        if isinstance(record.args, tuple):
+            record.args = tuple(self._redact_log_value(arg) for arg in record.args)
+        elif isinstance(record.args, dict):
+            record.args = {key: self._redact_log_value(value) for key, value in record.args.items()}
+        return True
+
+    @staticmethod
+    def _redact_log_value(value: object) -> object:
+        if isinstance(value, str):
+            redacted, _categories = redact_source_text(value)
+            return redacted if redacted is not None else ""
+        if isinstance(value, (bool, int, float)) or value is None:
+            return value
+        text = str(value)
+        redacted, categories = redact_source_text(text)
+        if categories or redacted != text:
+            return redacted if redacted is not None else ""
+        return value
+
+
 _CANONICAL_SCOPE_ALIASES: Final[dict[str, str]] = {
     "find:mock_lookup_module_hometax_simplified": "find:hometax.simplified",
     "find:mock.lookup_module_hometax_simplified": "find:hometax.simplified",
@@ -266,6 +296,11 @@ def _should_append_tui_tool_to_llm_tools(
     return True
 
 
+def _is_local_document_harness_tool(tool: object) -> bool:
+    endpoint = getattr(tool, "endpoint", "")
+    return isinstance(endpoint, str) and endpoint.startswith("local://document-harness/")
+
+
 def _normalize_root_primitive_adapter_envelope(
     fname: str,
     args_obj: dict[str, object],
@@ -871,6 +906,80 @@ _KMA_ANALYSIS_MAP_USER_QUERY_RE: Final = re.compile(
     r"(일기도|분석일기도|지도\s*자료|비구름|바람\s*흐름|synoptic|weather\s*chart)",
     re.IGNORECASE,
 )
+_DOCUMENT_WRITE_REQUEST_RE: Final = re.compile(
+    r"(작성|수정|편집|채우|채워|입력|변경|저장|write|edit|fill|apply|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_REVIEW_REQUEST_RE: Final = re.compile(
+    r"(diff|compact|변경사항|렌더|미리보기|render|viewport|page)",
+    re.IGNORECASE,
+)
+_DOCUMENT_DIFF_ONLY_FINAL_REQUEST_RE: Final = re.compile(
+    r"(실제(?:로)?\s*바뀐\s*내용만|바뀐\s*내용만|변경된\s*부분만|변경사항만|"
+    r"actual\s+changed\s+content\s+only|only\s+changed)",
+    re.IGNORECASE,
+)
+_DOCUMENT_ARTIFACT_ID_RE: Final = re.compile(
+    r"(?:^|[\s\"'`(])(?:artifact_id|artifact\s*id|artifact|아티팩트)?\s*"
+    r"((?:source|working|derivative|render|export|viewport)-[A-Za-z0-9][A-Za-z0-9_.-]{0,127})"
+    r"(?=$|[^A-Za-z0-9_.-])",
+    re.IGNORECASE,
+)
+_DOCUMENT_MUTATION_TOOL_IDS: Final[frozenset[str]] = frozenset(
+    {"document_apply_fill", "document_apply_style"}
+)
+_DOCUMENT_FINAL_ANSWER_OVERCLAIM_MARKERS: Final[frozenset[str]] = frozenset(
+    {
+        "활동 내용",
+        "주요 성과",
+        "문제점",
+        "개선사항",
+        "다음 주 계획",
+        "향후 계획",
+        "개발 활동",
+        "시각적 비교 기능",
+        "구현 완료",
+        "UMMAYA Phase",
+        "도구 결과",
+        "작성하겠습니다",
+        "작성해 드리겠습니다",
+        "보여드리겠습니다",
+        "확인해보겠습니다",
+        "구성하고",
+        "작성하여",
+        "활동일지로 작성",
+        "주간 활동일지",
+        "다음 주차 활동일지",
+        "다음 주 활동 계획",
+        "활동 계획",
+        "주요 일정",
+        "주요 변경사항",
+        "변경 요약",
+        "도큐먼트 하네스",
+        "CLI 툴 체인",
+        "품질 검증",
+        "파이프라인 최적화",
+        "시각적 diff",
+        "시각적 차이 비교",
+        "렌더링 아티팩트",
+        "아티팩트도 생성",
+        "아티팩트 생성",
+        "저장되었습니다",
+        "저장 완료",
+        "성공적으로 저장",
+        "업데이트가 완료되었습니다",
+        "표시되어 있습니다",
+        "표시하겠습니다",
+        "확인하실 수 있습니다",
+        "changes in the TUI",
+        "준비되었습니다",
+        "📋",
+        "📅",
+        "🔄",
+        "📊",
+        "| 항목 |",
+    }
+)
 _KMA_ANALYSIS_TOOL_IDS: Final[frozenset[str]] = frozenset(
     {
         "kma_apihub_url_high_resolution_grid_point",
@@ -883,7 +992,8 @@ _PPS_BID_USER_QUERY_RE: Final = re.compile(
     re.IGNORECASE,
 )
 _AIRKOREA_USER_QUERY_RE: Final = re.compile(
-    r"(미세먼지|초미세먼지|대기질|대기오염|마스크|pm\s*2\.?5|pm\s*10|air\s*korea|airkorea)",
+    r"(미세먼지|초미세먼지|초미세|대기질|대기오염|공기질|마스크|"
+    r"pm\s*2\.?5|pm\s*10|air\s*korea|airkorea|air\s*quality|airquality)",
     re.IGNORECASE,
 )
 _TAGO_BUS_USER_QUERY_RE: Final = re.compile(
@@ -911,29 +1021,24 @@ def _initial_concrete_tool_choice_for_query(
 ) -> str | None:
     """Force direct first calls only for unambiguous single-adapter lookups."""
     available = set(available_tool_names)
+    return _document_tool_choice_for_query(user_query, available)
+
+
+def _document_tool_choice_for_query(
+    user_query: str,
+    available: set[str],
+) -> str | None:
+    """Force unambiguous local document turns through the single document primitive."""
+    from ummaya.tools.search import is_document_harness_query  # noqa: PLC0415
+
     if (
-        _KMA_ANALYSIS_MAP_USER_QUERY_RE.search(user_query)
-        and _KMA_ANALYSIS_CHART_TOOL_ID in available
+        _DOCUMENT_ARTIFACT_ID_RE.search(user_query)
+        and _DOCUMENT_REVIEW_REQUEST_RE.search(user_query)
+        and "document" in available
     ):
-        return _KMA_ANALYSIS_CHART_TOOL_ID
-    if _KMA_AIRPORT_PLACE_RE.search(user_query) and _KMA_AIRPORT_AVIATION_RE.search(user_query):
-        if (
-            re.search(r"(김포|gimpo|rkss)", user_query, re.IGNORECASE)
-            and re.search(r"(amos|활주로|rvr|runway|매분)", user_query, re.IGNORECASE)
-            and "kma_apihub_url_air_amos_minute" in available
-        ):
-            return "kma_apihub_url_air_amos_minute"
-        if "kma_apihub_url_air_metar_decoded" in available:
-            return "kma_apihub_url_air_metar_decoded"
-    if _PPS_BID_USER_QUERY_RE.search(user_query) and _PPS_BID_TOOL_ID in available:
-        return _PPS_BID_TOOL_ID
-    if _AIRKOREA_USER_QUERY_RE.search(user_query) and _AIRKOREA_TOOL_ID in available:
-        return _AIRKOREA_TOOL_ID
-    if _TAGO_BUS_USER_QUERY_RE.search(user_query):
-        if _TAGO_ROUTE_NO_RE.search(user_query) and "tago_bus_route_search" in available:
-            return "tago_bus_route_search"
-        if "tago_bus_station_search" in available:
-            return "tago_bus_station_search"
+        return "document"
+    if is_document_harness_query(user_query) and "document" in available:
+        return "document"
     return None
 
 
@@ -1036,6 +1141,7 @@ def _conversation_has_successful_any_primitive_result(llm_messages: list[Any]) -
         or _conversation_has_successful_primitive_any_tool(llm_messages, primitive="locate")
         or _conversation_has_successful_primitive_any_tool(llm_messages, primitive="check")
         or _conversation_has_successful_primitive_any_tool(llm_messages, primitive="send")
+        or _conversation_has_successful_primitive_any_tool(llm_messages, primitive="document")
     )
 
 
@@ -1653,6 +1759,80 @@ def _payload_dict_is_error_like(payload: dict[str, object]) -> bool:
     return isinstance(error, str) and bool(error)
 
 
+def _message_role(msg: Any) -> object:
+    """Return a transcript message role across SDK and dict shapes."""
+    return getattr(msg, "role", None) or (msg.get("role") if isinstance(msg, dict) else None)
+
+
+def _message_content(msg: Any) -> object:
+    """Return a transcript message content across SDK and dict shapes."""
+    content = getattr(msg, "content", None)
+    if content is None and isinstance(msg, dict):
+        content = msg.get("content")
+    return content
+
+
+def _decode_tool_result_payload_content(content: object) -> object | None:
+    """Decode the payload stored inside a tool_result message/content part."""
+    if isinstance(content, str):
+        try:
+            payload: object = _stdlib_json.loads(content)
+            return payload
+        except _stdlib_json.JSONDecodeError:
+            return None
+    if isinstance(content, (dict, list)):
+        return content
+    return None
+
+
+def _iter_tool_result_payloads(msg: Any) -> list[tuple[str | None, str | None, object]]:
+    """Return tool_result payloads from OpenAI tool-role or CC user-role shapes."""
+    role = _message_role(msg)
+    if role == "tool":
+        content = _message_content(msg)
+        payload = _decode_tool_result_payload_content(content)
+        if payload is None:
+            return []
+        call_id = getattr(msg, "tool_call_id", None) or (
+            msg.get("tool_call_id") if isinstance(msg, dict) else None
+        )
+        name = getattr(msg, "name", None) or (msg.get("name") if isinstance(msg, dict) else None)
+        return [
+            (
+                call_id if isinstance(call_id, str) else None,
+                name if isinstance(name, str) else None,
+                payload,
+            )
+        ]
+    if role != "user":
+        return []
+    content = _message_content(msg)
+    if not isinstance(content, list):
+        return []
+    payloads: list[tuple[str | None, str | None, object]] = []
+    for item in content:
+        if not isinstance(item, dict) or item.get("type") != "tool_result":
+            continue
+        payload = _decode_tool_result_payload_content(item.get("content"))
+        if payload is None:
+            continue
+        call_id = item.get("tool_use_id")
+        payloads.append((call_id if isinstance(call_id, str) else None, None, payload))
+    return payloads
+
+
+def _message_is_tool_result_only(msg: Any) -> bool:
+    """Return True for CC-style user messages that only carry tool_result blocks."""
+    if _message_role(msg) != "user":
+        return False
+    content = _message_content(msg)
+    return (
+        isinstance(content, list)
+        and bool(content)
+        and all(isinstance(item, dict) and item.get("type") == "tool_result" for item in content)
+    )
+
+
 def _tool_result_payload_is_error(payload: object) -> bool:
     """Return True for structured tool-result payloads that are errors."""
     if not isinstance(payload, dict):
@@ -1665,6 +1845,224 @@ def _tool_result_payload_is_error(payload: object) -> bool:
     )
 
 
+def _payload_has_successful_document_tool_id(
+    payload: object,
+    tool_ids: frozenset[str],
+) -> bool:
+    """Return True when a structured tool result contains a successful document tool."""
+    if isinstance(payload, list):
+        return any(_payload_has_successful_document_tool_id(item, tool_ids) for item in payload)
+    if not isinstance(payload, dict):
+        return False
+    tool_id = payload.get("tool_id")
+    if isinstance(tool_id, str) and tool_id in tool_ids:
+        status = payload.get("status")
+        status_text = str(status).lower() if status is not None else "ok"
+        if status_text in {"ok", "succeeded", "completed", "ready"} and not (
+            _tool_result_payload_is_error(payload)
+        ):
+            return True
+    return any(
+        _payload_has_successful_document_tool_id(value, tool_ids) for value in payload.values()
+    )
+
+
+def _conversation_has_successful_document_tool_result(
+    llm_messages: list[Any],
+    *,
+    tool_ids: frozenset[str],
+) -> bool:
+    """Return True when a concrete document tool has a successful tool_result."""
+    return _conversation_has_successful_document_tool_result_after(
+        llm_messages,
+        tool_ids=tool_ids,
+        after_index=-1,
+    )
+
+
+def _conversation_has_successful_document_tool_result_after(
+    llm_messages: list[Any],
+    *,
+    tool_ids: frozenset[str],
+    after_index: int,
+) -> bool:
+    """Return True when a successful document tool_result appears after an index."""
+    start_index = max(0, after_index + 1)
+    for msg in llm_messages[start_index:]:
+        for _, _, payload in _iter_tool_result_payloads(msg):
+            if _payload_has_successful_document_tool_id(payload, tool_ids):
+                return True
+    return False
+
+
+def _conversation_has_successful_document_diff_result_after(
+    llm_messages: list[Any],
+    *,
+    after_index: int,
+) -> bool:
+    """Return True when a successful document mutation/render diff appears."""
+    start_index = max(0, after_index + 1)
+    for msg in llm_messages[start_index:]:
+        for _, _, payload in _iter_tool_result_payloads(msg):
+            document_result = _extract_successful_document_result_payload(payload)
+            if document_result is not None and _document_diff_changes(document_result):
+                return True
+    return False
+
+
+def _conversation_has_successful_document_completion_result_after(
+    llm_messages: list[Any],
+    *,
+    after_index: int,
+) -> bool:
+    """Return True when the latest turn has a completed document/review result."""
+    start_index = max(0, after_index + 1)
+    for msg in llm_messages[start_index:]:
+        for _, _, payload in _iter_tool_result_payloads(msg):
+            if _extract_successful_document_completion_payload(payload) is not None:
+                return True
+    return False
+
+
+def _extract_successful_document_completion_payload(payload: object) -> dict[str, object] | None:
+    """Return a successful document completion payload, excluding inspect-only results."""
+    if isinstance(payload, list):
+        return _extract_successful_document_completion_from_sequence(payload)
+    if isinstance(payload, dict):
+        return _extract_successful_document_completion_from_dict(payload)
+    return None
+
+
+def _extract_successful_document_completion_from_sequence(
+    payload: list[object],
+) -> dict[str, object] | None:
+    for item in reversed(payload):
+        result = _extract_successful_document_completion_payload(item)
+        if result is not None:
+            return result
+    return None
+
+
+def _extract_successful_document_completion_from_dict(
+    payload: dict[str, object],
+) -> dict[str, object] | None:
+    if _tool_result_payload_is_error(payload):
+        return None
+
+    direct = _direct_successful_document_completion_payload(payload)
+    if direct is not None:
+        return direct
+
+    result = payload.get("result")
+    if isinstance(result, dict):
+        nested = _extract_successful_document_completion_payload(result)
+        if nested is not None:
+            return nested
+    return _extract_successful_document_completion_from_sequence(list(payload.values()))
+
+
+def _direct_successful_document_completion_payload(
+    payload: dict[str, object],
+) -> dict[str, object] | None:
+    tool_id = payload.get("tool_id")
+    if not isinstance(tool_id, str) or tool_id not in {"document", "document_render"}:
+        return None
+    status = payload.get("status")
+    status_text = str(status).lower() if status is not None else "ok"
+    if status_text not in {"ok", "succeeded", "completed", "ready"}:
+        return None
+    if tool_id == "document" and _document_result_is_inspect_only(payload):
+        return None
+    return payload
+
+
+def _document_result_is_inspect_only(payload: dict[str, object]) -> bool:
+    """Return True for document primitive results that only inspected a file."""
+    if _document_diff_changes(payload):
+        return False
+    diff = payload.get("diff")
+    if diff is None and isinstance(payload.get("extraction"), dict):
+        return True
+    if diff is None and payload.get("render_artifacts") == []:
+        artifact_refs = payload.get("artifact_refs")
+        if isinstance(artifact_refs, list) and artifact_refs:
+            has_only_source_refs = all(
+                isinstance(ref, str) and ref.startswith("source-") for ref in artifact_refs
+            )
+            if has_only_source_refs:
+                return True
+    summary = str(payload.get("text_summary") or "").casefold()
+    return (
+        "inspection completed through the document primitive" in summary
+        or "document inspection completed" in summary
+        or "document extraction completed" in summary
+    )
+
+
+def _latest_user_message_index(llm_messages: list[Any]) -> int:
+    """Return the latest user-message index in the LLM transcript."""
+    for index in range(len(llm_messages) - 1, -1, -1):
+        msg = llm_messages[index]
+        if _message_role(msg) == "user" and not _message_is_tool_result_only(msg):
+            return index
+    return -1
+
+
+def _check_document_workflow_terminated_without_required_tool(
+    llm_messages: list[Any],
+    latest_user_utt: str,
+    *,
+    candidate_final_answer: str = "",
+) -> dict[str, str] | None:
+    """Return the missing document tool when a document workflow tries to stop early."""
+    from ummaya.tools.search import is_document_harness_query  # noqa: PLC0415
+
+    text_for_intent = f"{latest_user_utt}\n{candidate_final_answer}"
+    latest_user_index = _latest_user_message_index(llm_messages)
+    has_document_workflow_activity = _conversation_has_successful_document_tool_result(
+        llm_messages,
+        tool_ids=frozenset(
+            {
+                "document",
+                "document_render",
+                "document_inspect",
+                "document_extract",
+                "document_form_schema",
+                "document_copy_for_edit",
+                "document_apply_fill",
+                "document_apply_style",
+                "document_validate_public_form",
+                "document_save",
+            }
+        ),
+    )
+    if not is_document_harness_query(latest_user_utt) and not has_document_workflow_activity:
+        return None
+    wants_write = bool(_DOCUMENT_WRITE_REQUEST_RE.search(text_for_intent))
+    wants_review = bool(_DOCUMENT_REVIEW_REQUEST_RE.search(text_for_intent))
+    if not wants_write and not wants_review:
+        return None
+    has_document_result_for_latest_request = (
+        _conversation_has_successful_document_completion_result_after(
+            llm_messages,
+            after_index=latest_user_index,
+        )
+    )
+    if has_document_result_for_latest_request:
+        return None
+    return {
+        "tool_id": "document",
+        "message": (
+            "Document workflow request has no successful document primitive result "
+            "for the latest user turn. Do NOT answer from intended edits or "
+            "fabricate compact diff text. Call document once with the document "
+            "locator, requested operation, instruction, and any inferred patches; "
+            "the runtime will inspect, copy, mutate, render, and return the "
+            "automatic compact diff."
+        ),
+    }
+
+
 def _lookup_call_ids_for_tool(
     llm_messages: list[Any],
     *,
@@ -1708,24 +2106,10 @@ def _tool_result_payload_for_call(
     matching_call_ids: set[str],
 ) -> object | None:
     """Parse a lookup tool-result message when it matches one of call IDs."""
-    role = getattr(msg, "role", None) or (msg.get("role") if isinstance(msg, dict) else None)
-    if role != "tool":
-        return None
-    call_id = getattr(msg, "tool_call_id", None) or (
-        msg.get("tool_call_id") if isinstance(msg, dict) else None
-    )
-    if not isinstance(call_id, str) or call_id not in matching_call_ids:
-        return None
-    content = getattr(msg, "content", None) or (
-        msg.get("content") if isinstance(msg, dict) else None
-    )
-    if not isinstance(content, str):
-        return None
-    try:
-        payload: object = _stdlib_json.loads(content)
-        return payload
-    except _stdlib_json.JSONDecodeError:
-        return None
+    for call_id, _, payload in _iter_tool_result_payloads(msg):
+        if isinstance(call_id, str) and call_id in matching_call_ids:
+            return payload
+    return None
 
 
 def _conversation_has_successful_lookup(
@@ -1791,24 +2175,11 @@ def _tool_result_payload_for_primitive_call(
     matching_call_ids: set[str],
 ) -> object | None:
     """Parse a primitive tool-result message when it matches one of call IDs."""
-    role = getattr(msg, "role", None) or (msg.get("role") if isinstance(msg, dict) else None)
-    if role != "tool":
-        return None
-    call_id = getattr(msg, "tool_call_id", None) or (
-        msg.get("tool_call_id") if isinstance(msg, dict) else None
-    )
-    if not isinstance(call_id, str) or call_id not in matching_call_ids:
-        return None
-    content = getattr(msg, "content", None) or (
-        msg.get("content") if isinstance(msg, dict) else None
-    )
-    if not isinstance(content, str):
-        return None
-    try:
-        payload: object = _stdlib_json.loads(content)
-        return payload
-    except _stdlib_json.JSONDecodeError:
-        return None
+    _ = primitive
+    for call_id, _, payload in _iter_tool_result_payloads(msg):
+        if isinstance(call_id, str) and call_id in matching_call_ids:
+            return payload
+    return None
 
 
 def _tool_result_payload_for_primitive(
@@ -1823,24 +2194,17 @@ def _tool_result_payload_for_primitive(
     resolved state of the most recent primitive invocation, not a specific
     call handle.
     """
-    role = getattr(msg, "role", None) or (msg.get("role") if isinstance(msg, dict) else None)
-    if role != "tool":
-        return None
-    name = getattr(msg, "name", None) or (msg.get("name") if isinstance(msg, dict) else None)
-    content = getattr(msg, "content", None) or (
-        msg.get("content") if isinstance(msg, dict) else None
-    )
-    if not isinstance(content, str):
-        return None
-    try:
-        payload: object = _stdlib_json.loads(content)
+    for _, name, payload in _iter_tool_result_payloads(msg):
         if name == primitive:
             return payload
         if isinstance(payload, dict) and payload.get("kind") == primitive:
             return payload
-        return None
-    except _stdlib_json.JSONDecodeError:
-        return None
+        result = _primitive_payload_result_dict(payload)
+        if primitive == "document" and result is not None:
+            tool_id = result.get("tool_id")
+            if tool_id in {"document", "document_render"}:
+                return payload
+    return None
 
 
 def _primitive_payload_is_success(payload: object, *, primitive: str) -> bool:
@@ -1854,6 +2218,10 @@ def _primitive_payload_is_success(payload: object, *, primitive: str) -> bool:
         if isinstance(result, dict) and result.get("status") == "succeeded":
             return True
         return payload.get("status") == "succeeded"
+    if primitive == "document":
+        if isinstance(result, dict):
+            return result.get("status") == "ok"
+        return payload.get("status") == "ok"
     return True
 
 
@@ -2172,7 +2540,7 @@ def _latest_successful_primitive_observation(
         )
         primitive: object = tool_message_name
         payload: object | None = None
-        if primitive not in {"find", "locate", "check", "send"}:
+        if primitive not in {"find", "locate", "check", "send", "document"}:
             if not isinstance(content, str):
                 continue
             try:
@@ -2182,7 +2550,7 @@ def _latest_successful_primitive_observation(
             if not isinstance(parsed_payload, dict):
                 continue
             primitive = parsed_payload.get("kind")
-            if primitive not in {"find", "locate", "check", "send"}:
+            if primitive not in {"find", "locate", "check", "send", "document"}:
                 continue
             payload = parsed_payload
         if payload is None:
@@ -2200,6 +2568,183 @@ def _latest_successful_primitive_observation(
     return None
 
 
+def _latest_successful_document_result(llm_messages: list[Any]) -> dict[str, object] | None:
+    """Return the latest successful document primitive result payload."""
+    for msg in reversed(llm_messages):
+        payload = _tool_result_payload_for_primitive(msg, primitive="document")
+        if payload is not None and _primitive_payload_is_success(payload, primitive="document"):
+            result = _primitive_payload_result_dict(payload)
+            if result is not None:
+                return result
+            if isinstance(payload, dict):
+                return cast("dict[str, object]", payload)
+        role = getattr(msg, "role", None) or (msg.get("role") if isinstance(msg, dict) else None)
+        if role != "tool":
+            continue
+        content = getattr(msg, "content", None)
+        if content is None and isinstance(msg, dict):
+            content = msg.get("content")
+        parsed_payload: object = None
+        if isinstance(content, str):
+            try:
+                parsed_payload = _stdlib_json.loads(content)
+            except _stdlib_json.JSONDecodeError:
+                continue
+        else:
+            parsed_payload = content
+        document_result = _extract_successful_document_result_payload(parsed_payload)
+        if document_result is not None:
+            return document_result
+    return None
+
+
+def _extract_successful_document_result_payload(payload: object) -> dict[str, object] | None:
+    """Return a successful document result from direct, wrapped, or nested payloads."""
+    if isinstance(payload, list):
+        return _extract_successful_document_result_from_sequence(payload)
+    if isinstance(payload, dict):
+        return _extract_successful_document_result_from_dict(payload)
+    return None
+
+
+def _extract_successful_document_result_from_sequence(
+    payload: list[object],
+) -> dict[str, object] | None:
+    """Return the last successful document result from a payload sequence."""
+    for item in reversed(payload):
+        document_result = _extract_successful_document_result_payload(item)
+        if document_result is not None:
+            return document_result
+    return None
+
+
+def _extract_successful_document_result_from_dict(
+    payload: dict[str, object],
+) -> dict[str, object] | None:
+    """Return a successful document result from a payload mapping."""
+    if _tool_result_payload_is_error(payload):
+        return None
+    result = payload.get("result")
+    if isinstance(result, dict):
+        document_result = _extract_successful_document_result_payload(result)
+        if document_result is not None:
+            return document_result
+    if _payload_is_document_result_with_diff(payload):
+        return payload
+    for nested in reversed(list(payload.values())):
+        document_result = _extract_successful_document_result_payload(nested)
+        if document_result is not None:
+            return document_result
+    return None
+
+
+def _payload_is_document_result_with_diff(payload: dict[str, object]) -> bool:
+    """Return True when a payload has the user-visible document diff contract."""
+    diff = payload.get("diff")
+    status = str(payload.get("status") or "ok").lower()
+    return (
+        isinstance(diff, dict)
+        and isinstance(diff.get("changes"), list)
+        and status in {"ok", "succeeded", "completed", "ready"}
+    )
+
+
+def _document_diff_changes(result: dict[str, object]) -> list[dict[str, object]]:
+    """Return structured document diff changes from a document result."""
+    diff = result.get("diff")
+    if not isinstance(diff, dict):
+        return []
+    changes = diff.get("changes")
+    if not isinstance(changes, list):
+        return []
+    return [change for change in changes if isinstance(change, dict)]
+
+
+def _document_result_allowed_claim_text(result: dict[str, object]) -> str:
+    """Build the bounded document-result text a final answer may claim from."""
+    parts: list[str] = []
+    for key in ("tool_id", "status", "text_summary"):
+        value = result.get(key)
+        if value is not None:
+            parts.append(str(value))
+    for change in _document_diff_changes(result):
+        for key in (
+            "change_id",
+            "change_type",
+            "display_label",
+            "target_path",
+            "before_value",
+            "after_value",
+        ):
+            value = change.get(key)
+            if value is not None:
+                parts.append(str(value))
+    return "\n".join(parts)
+
+
+def _document_diff_only_final_answer(
+    latest_user_utt: str,
+    llm_messages: list[Any],
+) -> str | None:
+    """Build a diff-only final answer when the citizen explicitly asks for it."""
+    if not _DOCUMENT_DIFF_ONLY_FINAL_REQUEST_RE.search(latest_user_utt):
+        return None
+    result = _latest_successful_document_result(llm_messages)
+    if result is None:
+        return None
+    changes = _document_diff_changes(result)
+    if not changes:
+        return None
+    lines = ["실제 변경된 내용:"]
+    for change in changes:
+        target_path = str(change.get("display_label") or change.get("target_path") or "document")
+        before = str(change.get("before_value") or "")
+        after = str(change.get("after_value") or "")
+        lines.append(f"- {target_path}: {before} -> {after}")
+    return "\n".join(lines)
+
+
+def _compact_claim_text(text: str) -> str:
+    """Normalize claim text for marker comparison without losing Korean terms."""
+    return re.sub(r"\s+", "", text).casefold()
+
+
+def _final_answer_overclaims_document_edit(
+    text: str,
+    llm_messages: list[Any],
+) -> bool:
+    """Return True when a document final answer adds content absent from the diff."""
+    if not text.strip():
+        return False
+    result = _latest_successful_document_result(llm_messages)
+    if result is None:
+        return False
+    changes = _document_diff_changes(result)
+    if not changes:
+        return False
+    nonempty_lines = [line.strip() for line in text.splitlines() if line.strip()]
+    max_expected_lines = max(8, len(changes) * 4)
+    if len(nonempty_lines) > max_expected_lines:
+        return True
+    allowed = _compact_claim_text(_document_result_allowed_claim_text(result))
+    answer = _compact_claim_text(text)
+    for change in changes:
+        display_label = str(change.get("display_label") or "").strip()
+        target_path = str(change.get("target_path") or "").strip()
+        if not display_label or not target_path:
+            continue
+        if (
+            _compact_claim_text(target_path) in answer
+            and _compact_claim_text(display_label) not in answer
+        ):
+            return True
+    for marker in _DOCUMENT_FINAL_ANSWER_OVERCLAIM_MARKERS:
+        marker_text = _compact_claim_text(marker)
+        if marker_text in answer and marker_text not in allowed:
+            return True
+    return False
+
+
 def _final_answer_observation_message(
     *,
     message: str,
@@ -2220,6 +2765,16 @@ def _final_answer_observation_message(
                 observation_json[:_FINAL_ANSWER_OBSERVATION_JSON_LIMIT] + "...[truncated]"
             )
 
+    document_guidance = ""
+    if observation is not None and observation.get("primitive") == "document":
+        document_guidance = (
+            "\nDocument diff changes are the only approved edit claims. "
+            "For document results, mention only result.status, text_summary, "
+            "and diff.changes display_label/target_path/before_value/after_value. Do not add "
+            "activity contents, achievements, plans, problems, improvements, "
+            "or saved fields that are absent from diff.changes.\n"
+        )
+
     return (
         "[UMMAYA FINAL ANSWER OBSERVATION]\n"
         f"{message}\n\n"
@@ -2227,6 +2782,7 @@ def _final_answer_observation_message(
         f"{latest_user_utt}\n\n"
         "Latest successful primitive tool_result JSON:\n"
         f"{observation_json}\n\n"
+        f"{document_guidance}"
         "Use only the observed tool_result data above and the prior tool_result "
         "messages. Do not call another tool. Do not invent names, addresses, "
         "phone numbers, timestamps, weather values, receipt IDs, or source "
@@ -3072,82 +3628,47 @@ def _submit_requirement_for_query(user_query: str) -> dict[str, str] | None:
         and _query_contains_any(user_query, ("신고", "신고서", "제출"))
     )
     if asks_submit and asks_hometax_tax_return:
-        session_id = _extract_session_id(user_query, "HOMETAX-TAXRETURN-SESSION-001")
-        params = {
-            "tax_year": _extract_tax_year(user_query),
-            "income_type": "종합소득",
-            "total_income_krw": 42_000_000,
-            "session_id": session_id,
-        }
         return {
             "tool_id": "mock_submit_module_hometax_taxreturn",
             "verify_tool_id": "mock_verify_module_modid",
             "scope": "send:hometax.tax-return",
             "pre_submit_lookup_tool_id": "mock_lookup_module_hometax_simplified",
-            "params_json": _stdlib_json.dumps(params, ensure_ascii=False),
+            "params_json": "{}",
         }
 
     if asks_submit and _query_contains_any(user_query, ("정부24", "주민등록등본", "등본", "민원")):
-        session_id = _extract_session_id(user_query, "GOV24-MINWON-SESSION-001")
-        params = {
-            "minwon_type": "주민등록등본",
-            "applicant_name": "홍길동" if "홍길동" in user_query else "MOCK_APPLICANT",
-            "delivery_method": "online",
-            "session_id": session_id,
-        }
         return {
             "tool_id": "mock_submit_module_gov24_minwon",
             "verify_tool_id": "mock_verify_module_simple_auth",
             "scope": "send:gov24.minwon",
-            "params_json": _stdlib_json.dumps(params, ensure_ascii=False),
+            "params_json": "{}",
         }
 
     if asks_submit and _query_contains_any(
         user_query,
         ("복지 급여", "복지신청", "한부모가족", "한부모", "아동양육비"),
     ):
-        applicant_match = re.search(r"DI-[A-Z0-9-]+", user_query)
-        household_match = re.search(r"(\d+)\s*명", user_query)
-        params = {
-            "applicant_id": applicant_match.group(0)
-            if applicant_match
-            else "DI-MOCK-WELFARE-APPLICANT",
-            "benefit_code": "WLF00001068",
-            "application_type": "new",
-            "household_size": int(household_match.group(1)) if household_match else 1,
-        }
         return {
             "tool_id": "mock_welfare_application_submit_v1",
             "verify_tool_id": "mock_verify_mydata",
             "scope": "send:mydata.welfare_application",
-            "params_json": _stdlib_json.dumps(params, ensure_ascii=False),
+            "params_json": "{}",
         }
 
     if asks_submit and _query_contains_any(user_query, ("과태료", "교통범칙금", "범칙금")):
-        params = {
-            "fine_reference": "MOCK-FINE-2026-001",
-            "payment_method": "virtual_account",
-        }
         return {
             "tool_id": "mock_traffic_fine_pay_v1",
             "verify_tool_id": "mock_verify_ganpyeon_injeung",
             "scope": "send:traffic.fine-pay",
-            "params_json": _stdlib_json.dumps(params, ensure_ascii=False),
+            "params_json": "{}",
         }
 
     if asks_submit and _query_contains_any(user_query, ("마이데이터", "공공마이데이터")):
-        session_id = _extract_session_id(user_query, "MYDATA-ACTION-SESSION-001")
-        params = {
-            "action_type": "transfer_consent",
-            "target_institution_code": "PUBLIC-MYDATA-MOCK",
-            "applicant_di": "DI-MOCK-MYDATA-001",
-            "session_id": session_id,
-        }
         return {
             "tool_id": "mock_submit_module_public_mydata_action",
             "verify_tool_id": "mock_verify_mydata",
             "scope": "send:public_mydata.action",
-            "params_json": _stdlib_json.dumps(params, ensure_ascii=False),
+            "params_json": "{}",
         }
 
     return None
@@ -3176,17 +3697,18 @@ def _check_submit_terminated_without_submit(
         tool_id=pre_submit_lookup_tool_id,
     ):
         return None
-    params_json = requirement["params_json"]
     tool_id = requirement["tool_id"]
+    scope = requirement["scope"]
     return {
         **requirement,
         "message": (
             "Send follow-up missing: the citizen asked to complete a write, "
             "payment, consent, or filing flow and verification has already run, "
             f"but {tool_id!r} has not succeeded. RECOVERY: in the next turn call "
-            f"send(tool_id={tool_id!r}, params={params_json}). The backend will "
-            "inject the cached DelegationContext. Do NOT ask for additional mock "
-            "fields and do NOT end with guidance-only prose."
+            f"send using tool_id {tool_id!r}, the verified {scope!r} delegation "
+            "context, and params that satisfy the registered adapter schema. "
+            "The backend will inject the cached DelegationContext. Do NOT invent "
+            "mock fixture fields and do NOT end with guidance-only prose."
         ),
     }
 
@@ -3279,17 +3801,10 @@ def _canonicalize_submit_tool_id(
 def _apply_submit_canonical_params(
     params: dict[str, object],
     canonical: dict[str, object],
-    tool_id: str,
+    _tool_id: str,
 ) -> bool:
-    """Apply submit fixture defaults, overwriting Hometax mock guesses."""
     changed = False
-    overwrite = tool_id == "mock_submit_module_hometax_taxreturn"
     for key, value in canonical.items():
-        if overwrite:
-            if params.get(key) != value:
-                params[key] = value
-                changed = True
-            continue
         if key not in params or params.get(key) in (None, ""):
             params[key] = value
             changed = True
@@ -3332,11 +3847,14 @@ def _normalize_submit_args_for_query(
 
 def _strip_hometax_lookup_context_noise(params: dict[str, object]) -> bool:
     """Remove model-invented lookup fields from delegation_context."""
+    changed = False
+    if "query" in params:
+        params.pop("query", None)
+        changed = True
     delegation_context = params.get("delegation_context")
     if not isinstance(delegation_context, dict):
-        return False
+        return changed
     cleaned = dict(delegation_context)
-    changed = False
     for key in ("year", "resident_id_prefix"):
         if key in cleaned:
             cleaned.pop(key, None)
@@ -3382,6 +3900,58 @@ def _normalize_hometax_lookup_args_for_query(
     return normalized
 
 
+def _gov24_certificate_type_from_query(user_query: str) -> str | None:
+    if _query_contains_any(user_query, ("가족관계증명서", "가족 관계")):
+        return "family_relations"
+    if _query_contains_any(user_query, ("사업자등록증", "사업자 등록")):
+        return "business_registration"
+    if _query_contains_any(user_query, ("주민등록등본", "등본")):
+        return "resident_registration"
+    return None
+
+
+def _gov24_certificate_purpose_from_query(user_query: str, certificate_type: str) -> str:
+    if certificate_type == "resident_registration" and _query_contains_any(
+        user_query,
+        ("가능 여부", "준비물", "확인", "알려", "방법"),
+    ):
+        return "주민등록등본 발급 가능 여부와 준비물 확인"
+    if certificate_type == "family_relations":
+        return "가족관계증명서 발급 정보 확인"
+    if certificate_type == "business_registration":
+        return "사업자등록증 발급 정보 확인"
+    return "정부24 증명서 발급 정보 확인"
+
+
+def _normalize_gov24_certificate_lookup_args_for_query(
+    args_obj: dict[str, object],
+    user_query: str,
+) -> dict[str, object]:
+    if args_obj.get("tool_id") != "mock_lookup_module_gov24_certificate":
+        return args_obj
+    if not _query_contains_any(
+        user_query, ("정부24", "주민등록등본", "등본", "가족관계증명서", "사업자등록증")
+    ):
+        return args_obj
+    certificate_type = _gov24_certificate_type_from_query(user_query)
+    if certificate_type is None:
+        return args_obj
+    raw_params = args_obj.get("params")
+    params = dict(raw_params) if isinstance(raw_params, dict) else {}
+    changed = not isinstance(raw_params, dict)
+    if params.get("certificate_type") in (None, ""):
+        params["certificate_type"] = certificate_type
+        changed = True
+    if params.get("purpose") in (None, ""):
+        params["purpose"] = _gov24_certificate_purpose_from_query(user_query, certificate_type)
+        changed = True
+    if not changed:
+        return args_obj
+    normalized = dict(args_obj)
+    normalized["params"] = params
+    return normalized
+
+
 def _canonicalize_lookup_tool_id_for_query(
     args_obj: dict[str, object],
     user_query: str,
@@ -3392,7 +3962,15 @@ def _canonicalize_lookup_tool_id_for_query(
         return args_obj
     sensitive_lookup = _sensitive_lookup_requirement_for_query(user_query)
     if sensitive_lookup is None:
-        return args_obj
+        if not _query_contains_any(
+            user_query,
+            ("홈택스", "연말정산", "간소화", "종합소득세", "소득세 신고", "세금 신고"),
+        ):
+            return args_obj
+        sensitive_lookup = {
+            **_SENSITIVE_LOOKUP_AUTH_REQUIREMENTS["mock_lookup_module_hometax_simplified"],
+            "tool_id": "mock_lookup_module_hometax_simplified",
+        }
     normalized = dict(args_obj)
     normalized["tool_id"] = sensitive_lookup["tool_id"]
     logger.info(
@@ -3471,6 +4049,7 @@ def _normalize_lookup_args_for_query(
         return args_obj
     args_obj = _canonicalize_lookup_tool_id_for_query(args_obj, user_query)
     args_obj = _normalize_hometax_lookup_args_for_query(args_obj, user_query)
+    args_obj = _normalize_gov24_certificate_lookup_args_for_query(args_obj, user_query)
     args_obj = _normalize_lookup_result_count_args(
         args_obj,
         user_query,
@@ -3506,6 +4085,21 @@ def _normalize_lookup_args_for_query(
     return normalized
 
 
+def _lookup_context_from_args(args_obj: dict[str, object]) -> str:
+    chunks: list[str] = []
+    for key in ("query", "request", "instruction", "purpose_ko"):
+        value = args_obj.get(key)
+        if isinstance(value, str) and value.strip():
+            chunks.append(value.strip())
+    raw_params = args_obj.get("params")
+    if isinstance(raw_params, dict):
+        for key in ("query", "request", "instruction", "purpose_ko"):
+            value = raw_params.get(key)
+            if isinstance(value, str) and value.strip():
+                chunks.append(value.strip())
+    return " ".join(chunks)
+
+
 _KOREAN_COUNT_WORDS: Final[dict[str, int]] = {
     "한": 1,
     "두": 2,
@@ -4449,26 +5043,31 @@ def _emitted_tool_id(fname: str, args_obj: dict[str, object]) -> str | None:
     return None
 
 
-def _direct_public_data_target_for_query(user_query: str) -> tuple[frozenset[str], str, str] | None:
+def _direct_public_data_target_for_query(
+    user_query: str,
+) -> tuple[frozenset[str], str, str, str] | None:
     """Return target adapter family for public-data wording that should not use substitutes."""
     if _KMA_ANALYSIS_MAP_USER_QUERY_RE.search(user_query):
         return (
             frozenset({_KMA_ANALYSIS_CHART_TOOL_ID}),
             _KMA_ANALYSIS_CHART_TOOL_ID,
-            "call the KMA APIHub analyzed weather-chart adapter and do not "
-            "substitute location, AirKorea, or ordinary weather tools.",
+            "weather_chart",
+            "use official KMA APIHub analyzed weather-chart evidence and do not "
+            "substitute location, AirKorea, or ordinary weather evidence.",
         )
     if _PPS_BID_USER_QUERY_RE.search(user_query):
         return (
             frozenset({_PPS_BID_TOOL_ID}),
             _PPS_BID_TOOL_ID,
-            "call the PPS/NaraJangteo bid adapter with its bid notice date fields.",
+            "procurement_bid",
+            "use PPS/NaraJangteo bid notice date fields.",
         )
     if _AIRKOREA_USER_QUERY_RE.search(user_query):
         return (
             frozenset({_AIRKOREA_TOOL_ID}),
             _AIRKOREA_TOOL_ID,
-            "call the AirKorea city/province air-quality adapter with sido_name such as '부산'.",
+            "air_quality",
+            "use AirKorea city/province air-quality evidence with sido_name such as '부산'.",
         )
     if _TAGO_BUS_USER_QUERY_RE.search(user_query):
         preferred = (
@@ -4479,15 +5078,17 @@ def _direct_public_data_target_for_query(user_query: str) -> tuple[frozenset[str
         return (
             _TAGO_TOOL_IDS,
             preferred,
-            "use TAGO bus schemas; for a route number, start with "
-            "tago_bus_route_search, then route_station and arrival.",
+            "bus_realtime",
+            "use TAGO bus evidence; for a route number, start with route search, "
+            "then route-station and arrival evidence.",
         )
     if _query_implies_current_weather_observation(user_query):
         return (
             _KMA_ORDINARY_WEATHER_TOOL_IDS | _KMA_LOCATION_TOOL_IDS,
             "kakao_keyword_search",
-            "use a location adapter first when coordinates are missing, then "
-            "KMA current observation for rain/umbrella/current-weather values.",
+            "current_weather",
+            "use location resolution first when coordinates are missing, then "
+            "KMA current observation evidence for rain/umbrella/current-weather values.",
         )
     return None
 
@@ -4501,15 +5102,15 @@ def _check_direct_public_data_tool_choice_prerequisite(
     target = _direct_public_data_target_for_query(user_query)
     if target is None:
         return None
-    allowed_tool_ids, preferred_tool_id, hint = target
+    allowed_tool_ids, preferred_tool_id, route_label, hint = target
     emitted_tool_id = _emitted_tool_id(fname, args_obj)
     if emitted_tool_id is None or emitted_tool_id in allowed_tool_ids:
         return None
     return (
         preferred_tool_id,
-        "Public-data tool-choice mismatch: the latest citizen request matches "
-        f"{preferred_tool_id}. The model emitted {emitted_tool_id} instead. "
-        f"RECOVERY: {hint}",
+        "Public-data tool-choice mismatch: "
+        f"target={route_label}. The latest citizen request needs that route; "
+        f"the previous tool choice does not match. RECOVERY: {hint}",
     )
 
 
@@ -4605,6 +5206,7 @@ _AVAILABLE_ADAPTER_FIND_LINE_RE: Final = re.compile(
     r"^\s*-\s+[A-Za-z0-9_.:-]+\s+\(primitive=find\)",
     re.MULTILINE,
 )
+_AVAILABLE_ADAPTER_TOOL_ID_LINE_RE: Final = re.compile(r"^\s*-\s*tool_id:\s*[A-Za-z0-9_.:-]+\s*$")
 _MEDICAL_COLLAPSE_RE: Final = re.compile(
     r"(사람[이가은는 ]*쓰러|쓰러졌|쓰러져|의식[을 ]*(?:잃|없)|심정지|"
     r"숨[을 ]*(?:안|못)|호흡[이가은는 ]*없|자동심장|심장충격|제세동|"
@@ -4639,7 +5241,21 @@ def _latest_available_adapters_block(llm_messages: list[Any]) -> str:
 
 def _available_adapters_block_has_find_candidate(block: str) -> bool:
     """Return True when retrieval surfaced a non-locate follow-up adapter."""
-    return bool(block and _AVAILABLE_ADAPTER_FIND_LINE_RE.search(block))
+    if not block:
+        return False
+    if _AVAILABLE_ADAPTER_FIND_LINE_RE.search(block):
+        return True
+    in_projected_candidate = False
+    for line in block.splitlines():
+        stripped = line.strip()
+        if _AVAILABLE_ADAPTER_TOOL_ID_LINE_RE.match(line):
+            in_projected_candidate = True
+            continue
+        if stripped.startswith("- "):
+            in_projected_candidate = False
+        if in_projected_candidate and stripped == "primitive: find":
+            return True
+    return False
 
 
 def _available_adapters_block_has_tool_id(block: str, tool_id: str) -> bool:
@@ -5180,6 +5796,7 @@ async def run(  # noqa: C901
                 _fh.setFormatter(
                     logging.Formatter("%(asctime)s %(levelname)s %(name)s %(message)s")
                 )
+                _fh.addFilter(_BackendSecretRedactionFilter())
                 _root.addHandler(_fh)
                 _root.setLevel(min(_root.level or logging.INFO, logging.INFO))
                 logger.info(
@@ -5393,6 +6010,19 @@ async def run(  # noqa: C901
             _ensure_tool_registry()  # populates both refs in one shot
         return _tool_executor_ref[0]
 
+    def _is_local_document_harness_root_call(
+        fname: str,
+        args_obj: dict[str, object],
+    ) -> bool:
+        tool_id = str(args_obj.get("tool_id") or "")
+        if not tool_id:
+            return False
+        try:
+            tool = _ensure_tool_registry().find(tool_id)
+        except Exception:
+            return False
+        return tool.primitive == fname and _is_local_document_harness_tool(tool)
+
     async def _ensure_llm_client() -> object:
         if not _llm_client_ref:
             from ummaya.llm.client import LLMClient  # noqa: PLC0415
@@ -5557,54 +6187,50 @@ async def run(  # noqa: C901
     )
     _root_primitive_tool_ids = _ROOT_PRIMITIVE_TOOL_IDS
 
-    def _select_concrete_adapter_tools_for_turn(user_query: str) -> list[Any]:
-        """Return concrete, non-core adapter tools for this citizen turn.
-
-        CC exposes concrete Tool objects to the model; UMMAYA keeps the same
-        model-facing shape and uses BM25/dense retrieval only as a loading
-        optimization so the tool list stays small.
-        """
+    def _route_decision_for_turn(user_query: str) -> RouteDecision | None:
         q = (user_query or "").strip()
         if not q:
-            return []
+            return None
         registry = _ensure_tool_registry()
-        selected: dict[str, Any] = {}
-        for tool in registry.all_tools():
-            if tool.id in _root_primitive_tool_ids:
-                continue
-            if tool.id in q:
-                selected[tool.id] = tool
         try:
-            from ummaya.tools.search import search  # noqa: PLC0415
+            from ummaya.tools.routing import RouteDecisionService  # noqa: PLC0415
 
             raw_top_k = max(_AVAILABLE_ADAPTERS_TOP_K * 3, _AVAILABLE_ADAPTERS_TOP_K)
-            candidates = search(
-                query=q,
-                bm25_index=registry.bm25_index,
-                registry=registry,
+            return RouteDecisionService(registry).select_adapters(
+                q,
                 top_k=min(raw_top_k, 20),
+                max_selected=_AVAILABLE_ADAPTERS_TOP_K,
             )
         except Exception:
-            logger.exception("adapter tool retrieval failed for '%s'", q[:80])
-            candidates = []
-        for candidate in candidates:
-            try:
-                tool = registry.find(candidate.tool_id)
-            except Exception:
-                logger.debug(
-                    "Skipping unavailable adapter candidate %s",
-                    candidate.tool_id,
-                    exc_info=True,
-                )
-                continue
-            if tool.id in _root_primitive_tool_ids:
-                continue
-            selected.setdefault(tool.id, tool)
-            if len(selected) >= _AVAILABLE_ADAPTERS_TOP_K:
-                break
-        return list(selected.values())[:_AVAILABLE_ADAPTERS_TOP_K]
+            logger.exception("route decision failed for '%s'", q[:80])
+            return None
 
-    def _build_available_adapters_suffix(user_query: str) -> str:  # noqa: C901
+    def _select_concrete_adapter_tools_for_turn(
+        user_query: str, route_decision: RouteDecision | None = None
+    ) -> list[Any]:
+        q = (user_query or "").strip()
+        if not q:
+            return []
+        registry = _ensure_tool_registry()
+        decision = route_decision or _route_decision_for_turn(q)
+        if decision is None:
+            return []
+        from ummaya.tools.routing import selected_concrete_adapter_tools  # noqa: PLC0415
+
+        return list(
+            selected_concrete_adapter_tools(
+                decision,
+                registry,
+                exclude_tool_ids=_root_primitive_tool_ids,
+                max_tools=_AVAILABLE_ADAPTERS_TOP_K,
+            )
+        )
+
+    def _build_available_adapters_suffix(
+        user_query: str,
+        route_decision: RouteDecision | None = None,
+        visible_tool_ids: Iterable[str] | None = None,
+    ) -> str:  # noqa: C901
         """Run BM25 against the live registry and emit the citizen-turn
         ``<available_adapters>`` XML block for the dynamic system-prompt
         suffix.
@@ -5618,281 +6244,32 @@ async def run(  # noqa: C901
         q = (user_query or "").strip()
         if not q:
             return ""
+        route_decision = route_decision or _route_decision_for_turn(q)
+        if route_decision is None:
+            return ""
         try:
-            from ummaya.tools.search import search  # noqa: PLC0415
+            from ummaya.tools.routing import build_available_adapters_projection  # noqa: PLC0415
 
-            registry = _ensure_tool_registry()
-            raw_top_k = max(_AVAILABLE_ADAPTERS_TOP_K * 3, _AVAILABLE_ADAPTERS_TOP_K)
-            candidates = search(
+            visible_tool_ids_tuple = None if visible_tool_ids is None else tuple(visible_tool_ids)
+            projection_level = (
+                route_decision.schema_projection_level
+                if route_decision.selected_tools or not visible_tool_ids_tuple
+                else "summary"
+            )
+            projection = build_available_adapters_projection(
+                route_decision,
+                _ensure_tool_registry(),
                 query=q,
-                bm25_index=registry.bm25_index,
-                registry=registry,
-                top_k=min(raw_top_k, 20),
+                projection_level=projection_level,
+                max_visible=_AVAILABLE_ADAPTERS_TOP_K
+                if visible_tool_ids_tuple is None
+                else len(visible_tool_ids_tuple),
+                visible_tool_ids=visible_tool_ids_tuple,
             )
+            return projection.content or ""
         except Exception:
-            logger.exception("BM25 retrieval failed for '%s'", q[:80])
-            return ""
-        filtered_candidates = []
-        for candidate in candidates:
-            try:
-                tool = registry.find(candidate.tool_id)
-            except Exception:
-                logger.debug(
-                    "Skipping unavailable adapter candidate %s",
-                    candidate.tool_id,
-                    exc_info=True,
-                )
-                continue
-            if tool.id in _root_primitive_tool_ids:
-                continue
-            filtered_candidates.append(candidate)
-            if len(filtered_candidates) >= _AVAILABLE_ADAPTERS_TOP_K:
-                break
-        candidates = filtered_candidates
-        if not candidates:
+            logger.exception("route decision projection failed for '%s'", q[:80])
             return ""
-        candidate_ids = tuple(candidate.tool_id for candidate in candidates)
-        first_candidate_id = candidate_ids[0]
-        has_amos_candidate = "kma_apihub_url_air_amos_minute" in candidate_ids
-        has_metar_candidate = "kma_apihub_url_air_metar_decoded" in candidate_ids
-        has_analysis_candidate = any(
-            candidate_id
-            in {
-                "kma_apihub_url_high_resolution_grid_point",
-                "kma_apihub_url_aws_objective_analysis_grid",
-                "kma_apihub_url_analysis_weather_chart_image",
-            }
-            for candidate_id in candidate_ids
-        )
-        is_gimpo_runway_query = bool(
-            re.search(r"(김포공항|Gimpo|RKSS)", q, re.IGNORECASE)
-            and re.search(
-                r"(AMOS|활주로|RVR|runway|시정|visibility|공항기상관측|매분)",
-                q,
-                re.IGNORECASE,
-            )
-        )
-        # Build a compact, LLM-readable block.
-        #
-        # Spec 2521 (2026-05-02) — emit per-field schema signatures so the
-        # LLM can fill ``params`` against each adapter's actual REST shape.
-        # The previous suffix only carried ``search_hint`` and assumed the
-        # LLM could "infer params from search_hint" — K-EXAONE on FriendliAI
-        # consistently invented ``{"location": "...", "date": "..."}`` style
-        # payloads which fail every adapter's pydantic validation
-        # (``Invalid parameters for tool``). Rendering each field with its
-        # type + required flag + truncated description gives K-EXAONE
-        # enough signal to call e.g. ``{"lat": 37.5, "lon": 129.0,
-        # "base_date": "20260502", "base_time": "0500"}`` correctly.
-        lines: list[str] = [
-            f'<available_adapters query="{q[:120]}">',
-            f"백엔드 BM25 후보 (top {len(candidates)}, 점수 내림차순):",
-            "",
-        ]
-        for c in candidates:
-            hint = (c.search_hint or "").strip()
-            if len(hint) > 90:
-                hint = hint[:87] + "..."
-            primitive = c.primitive or "find"
-            lines.append(
-                f"- {c.tool_id} (primitive={primitive}) [{c.score:.2f}] — {hint or '(설명 없음)'}"
-            )
-            lines.append(f"  호출: {c.tool_id}({{...schema fields...}})")
-            # Render the adapter's llm_description (usage prose, ORDERING RULE,
-            # prerequisites, worked examples) so the LLM sees the complete
-            # "먼저 locate 호출" ordering rule.
-            # Bug: without this, the per-field description for nx is truncated
-            # and K-EXAONE skips locate, producing invalid_params.
-            if c.llm_description:
-                desc_text = c.llm_description.strip().replace("\n", " ")
-                # Emit enough text for adapter-specific negative routing and
-                # output-use rules. KMA METAR/AMOS descriptions carry critical
-                # "Gimhae is not AMOS" and "safe_weather only" instructions
-                # after the purpose sentence; truncating them makes the TUI
-                # path claim no METAR tool exists.
-                if len(desc_text) > 900:
-                    desc_text = desc_text[:897] + "..."
-                lines.append(f"  설명: {desc_text}")
-            # Render input schema signature so the LLM sees exact field
-            # names + types + required flags + (truncated) descriptions.
-            # Field desc limit raised 80→120 so nx/ny examples fit untruncated.
-            schema = c.input_schema_json or {}
-            properties = schema.get("properties") if isinstance(schema, dict) else None
-            required: set[str] = set()
-            raw_required = schema.get("required") if isinstance(schema, dict) else None
-            if isinstance(raw_required, list):
-                required = {str(item) for item in raw_required if isinstance(item, str)}
-            # Spec 2522 T010 — ORDERING directive removed.
-            # The Spec 2521 ORDERING block ("nx/ny 는 KMA 격자 좌표 — 반드시
-            # locate 을 먼저 호출") forced a cross-domain chain that
-            # contradicts both the user directive ("chain X / UMMAYA does not
-            # force cross-domain chain") and v4 description 5-section
-            # self_contained_decl ("이 도구 단독 호출로 완결. locate 등
-            # cross-domain chain 불필요"). With both signals present K-EXAONE
-            # ignored both and hallucinated nx/ny → Spec 2521 regression.
-            # Each adapter's description (섹션 4 domain_quirk + 섹션 5
-            # self_contained_decl + 섹션 3 short_reference 17 광역시도 표) is now
-            # self-sufficient. The model decides chain vs single-tool autonomously.
-            # Reference: research-stdio-ordering.md, frames-busan-weather/ T042 evidence.
-            # Spec 2522 T047 fix — resolve $ref to $defs and inline enum values.
-            # KOROAD KoroadAccidentSearchInput.search_year_cd uses
-            # `$ref: #/$defs/SearchYearCd` (20 values). The previous renderer
-            # only inlined `properties.<f>.enum` and gave up on $ref, leaving
-            # K-EXAONE to guess plain '2024' (invalid). Spec 2522 frames-gangnam-
-            # accident-fix2 evidence: invalid_params persisted after T042 fix.
-            # Fix: resolve $ref against schema['$defs'] + raise threshold 8→25.
-            defs_raw = schema.get("$defs") if isinstance(schema, dict) else None
-            defs: dict[str, Any] | None = defs_raw if isinstance(defs_raw, dict) else None
-
-            def _resolve_enum(
-                meta: dict[str, Any], defs: dict[str, Any] | None
-            ) -> list[Any] | None:
-                # direct enum
-                e = meta.get("enum")
-                if isinstance(e, list):
-                    return e
-                # $ref → $defs/<name>
-                ref = meta.get("$ref")
-                if isinstance(ref, str) and ref.startswith("#/$defs/") and isinstance(defs, dict):
-                    name = ref.removeprefix("#/$defs/")
-                    target = defs.get(name)
-                    if isinstance(target, dict):
-                        target_enum = target.get("enum")
-                        if isinstance(target_enum, list):
-                            return target_enum
-                return None
-
-            def _resolve_enum_with_names(
-                meta: dict[str, Any], defs: dict[str, Any] | None
-            ) -> list[tuple[Any, str]] | None:
-                """Spec 2522 — agency 자체 코드체계 (KOROAD GugunCode SEOUL_GANGNAM=680
-                등) 의 IntEnum name 을 의미 매핑으로 노출. pydantic JSON schema 의
-                $defs 안 IntEnum 의 'enum' (값) + 'x-enum-varnames' (name) 또는
-                'description' (docstring) 을 묶어서 LLM 에 보여줌.
-                """
-                ref = meta.get("$ref")
-                if not (isinstance(ref, str) and ref.startswith("#/$defs/")):
-                    return None
-                if not isinstance(defs, dict):
-                    return None
-                name = ref.removeprefix("#/$defs/")
-                target = defs.get(name)
-                if not isinstance(target, dict):
-                    return None
-                values = target.get("enum")
-                if not isinstance(values, list):
-                    return None
-                # IntEnum name 추출 — pydantic v2 가 'x-enum-varnames' 또는
-                # 'enumNames' 로 export 하지 않음. 대신 module-level dict 조회.
-                varnames = target.get("x-enum-varnames")
-                if isinstance(varnames, list) and len(varnames) == len(values):
-                    return list(zip(values, varnames, strict=False))
-                return None
-
-            if isinstance(properties, dict) and properties:
-                for fname, fmeta in properties.items():
-                    if not isinstance(fmeta, dict):
-                        continue
-                    ftype = fmeta.get("type") or fmeta.get("anyOf") or "any"
-                    if isinstance(ftype, list):
-                        ftype = "|".join(str(t) for t in ftype)
-                    fdesc = str(fmeta.get("description", "")).strip().replace("\n", " ")
-                    # Spec 2522 — agency 자체 코드체계 (KOROAD 68 시군구 매핑 ≈ 1600
-                    # chars + 기존 description ≈ 600 chars = ~2200 chars / KMA 156
-                    # station 등) 인라인 허용. 일반 도구는 100자 미만이라 영향 X.
-                    if len(fdesc) > 5000:
-                        fdesc = fdesc[:4997] + "..."
-                    pat = fmeta.get("pattern")
-                    pat_part = f" pattern={pat!r}" if isinstance(pat, str) else ""
-                    enum = _resolve_enum(fmeta, defs)
-                    # Spec 2522 T047 — threshold 25→200 — KOROAD GugunCode (115) /
-                    # SearchYearCd (20) / SidoCode (17) 등 모두 노출. 의미 매핑은
-                    # field description 에 따로 인라인 (Pydantic IntEnum 의 name
-                    # 은 JSON schema 표준 export 안 됨).
-                    if isinstance(enum, list) and len(enum) <= 200:
-                        enum_part = f" enum={enum}"
-                    else:
-                        enum_part = ""
-                    flag = "필수" if fname in required else "선택"
-                    lines.append(
-                        f"    · {fname} ({ftype}, {flag}{pat_part}{enum_part})"
-                        + (f" — {fdesc}" if fdesc else "")
-                    )
-        lines.append("")
-        lines.append(
-            "규칙: 위 목록의 tool_id는 concrete adapter id입니다. model-facing "
-            "함수명도 tools[]에 로드된 concrete tool_id입니다. concrete adapter "
-            "function은 schema 필드만 받으므로 tool_id/params envelope를 그 안에 "
-            "넣지 마세요. concrete function이 로드되지 않고 root primitive만 "
-            '있을 때만 legacy envelope 예: find({"tool_id":"...", "params":{...}}) '
-            "형식을 사용합니다. 동일 tool_id 를 한 turn 안에서 반복 호출하지 "
-            "마세요. 위 목록에 요청과 일치하는 adapter가 있으면 도구가 없다고 "
-            "답하지 마세요."
-        )
-        if has_analysis_candidate:
-            lines.append(
-                "분석자료 특수 규칙: 위 후보에 고해상도 격자자료, AWS 객관분석, "
-                "분석일기도 이미지가 있으면 기상청이 이미 분석한 자료 도구가 있는 "
-                "것입니다. 공항 관측값/METAR/AMOS/일반 예보가 아니라 시민이 말한 "
-                "분석자료 계열 후보를 호출하세요. 지도/일기도/비구름/바람 흐름 "
-                "질의는 kma_apihub_url_analysis_weather_chart_image 를 우선 호출하고, "
-                "특정 지점 주변 값은 locate 뒤 "
-                "kma_apihub_url_high_resolution_grid_point 또는 "
-                "kma_apihub_url_aws_objective_analysis_grid 를 호출하세요. 공항/랜드마크 "
-                "주변 좌표는 kakao_keyword_search 를 kakao_address_search 보다 먼저 "
-                "사용하세요. locate 가 실패하면 다른 후보 위치 도구를 시도하고, 도구 "
-                "결과 없이 좌표를 추정하지 마세요. APIHub 승인 대기나 upstream 오류가 "
-                "나면 그 실패를 그대로 설명하고, 도구 결과 없이 지도 기반 내용을 "
-                "추정하지 마세요."
-            )
-        if has_amos_candidate and (
-            is_gimpo_runway_query or first_candidate_id == "kma_apihub_url_air_amos_minute"
-        ):
-            lines.append(
-                "AMOS 특수 규칙: kma_apihub_url_air_amos_minute 가 김포공항 "
-                "활주로/시정/RVR/매분 관측 후보이면 AMOS 공항기상관측 도구가 "
-                "있는 것입니다. 김포공항은 stn=110 을 사용하세요. 이 후보는 "
-                "좌표를 요구하지 않으므로 locate/kma_current_observation 을 먼저 "
-                '호출하지 말고 즉시 kma_apihub_url_air_amos_minute({"stn":"110",'
-                '"help":1}) 를 호출하세요. METAR 는 '
-                "보조 확인이 필요할 때만 추가로 사용하세요."
-            )
-        if has_metar_candidate and not (has_amos_candidate and is_gimpo_runway_query):
-            lines.append(
-                "METAR 특수 규칙: kma_apihub_url_air_metar_decoded 가 후보에 있으면 "
-                "공항 METAR 해독자료 조회 도구가 있는 것입니다. 김해공항/RKPK는 "
-                "decoded_records 의 station 153 Gimhae Airport / RKPK record를 "
-                "사용하고, 날씨 값은 decoded_records[].safe_weather 만 사용하세요. "
-                "raw_fields/raw_report에서 별도 값을 만들지 마세요. 이 후보는 좌표를 "
-                "요구하지 않으므로 locate/kma_current_observation 을 먼저 호출하지 "
-                '말고 즉시 kma_apihub_url_air_metar_decoded({"org":"K","help":1}) '
-                "를 호출하세요."
-            )
-        listed_primitives = {str(candidate.primitive or "find") for candidate in candidates}
-        if listed_primitives == {"find"}:
-            lines.append(
-                "공개자료 조회 규칙: 위 후보가 모두 primitive=find 이면 시민이 "
-                "인증/본인확인/동의/신청/제출/납부/신고를 명시하지 않은 한 "
-                "check/send 계열 adapter를 호출하지 마세요. 성공한 find 결과가 있으면 "
-                "다음 turn 은 최종 답변입니다."
-            )
-        lines.append(
-            "호출 전 검증: 시민 발화의 명시 조건(개수, 반경/거리, 날짜/시간, 종류, "
-            "카테고리, 진료과/분야, 키워드, 행정구역 등)이 아래 schema 의 선택 "
-            "필드와 대응하면 그 필드를 반드시 params 에 포함하세요. 더 좁은 요청을 "
-            "넓은 무필터 조회로 실행하지 마세요."
-        )
-        lines.append(
-            'params 는 위에 표시된 정확한 필드명만 사용하세요 — 일반적인 "location"/'
-            '"date" 같은 추측 키는 모든 어댑터에서 invalid_params 로 거부됩니다.'
-        )
-        lines.append(
-            "BM25 도구 발견은 백엔드 internal 기능입니다. 모델은 검색 함수를 호출하지 "
-            "않고, backend가 tools[]에 실어준 concrete adapter function을 우선 "
-            "호출합니다."
-        )
-        lines.append("</available_adapters>")
-        return "\n".join(lines)
 
     # Spec 1978 T053 — eager-import the Mock adapter tree so every adapter
     # self-registers with its primitive dispatcher before the first chat
@@ -6342,9 +6719,28 @@ async def run(  # noqa: C901
             span.set_attribute("ummaya.tool.dispatched", fname)
             span.set_attribute("ummaya.session.id", session_id)
 
+            if fname == "document" and "tool_id" not in args_obj:
+                args_obj = {
+                    "tool_id": "document",
+                    "params": dict(args_obj),
+                }
+            normalized_document_args = _normalize_document_root_call_for_user_intent(
+                fname,
+                args_obj,
+                _session_latest_user_utterances.get(session_id, ""),
+            )
+            if normalized_document_args is not args_obj:
+                span.set_attribute("ummaya.document.intent_normalized", True)
+                logger.warning(
+                    "_dispatch_primitive: normalized document root call to match latest "
+                    "citizen write/save intent."
+                )
+                args_obj = normalized_document_args
+
+            local_document_harness_call = _is_local_document_harness_root_call(fname, args_obj)
             invalid_gated_tool_id = (
                 _invalid_gated_primitive_tool_id_result(fname, args_obj)
-                if fname in _PERMISSION_GATED_PRIMITIVES
+                if fname in _PERMISSION_GATED_PRIMITIVES and not local_document_harness_call
                 else None
             )
             if invalid_gated_tool_id is not None:
@@ -6375,13 +6771,17 @@ async def run(  # noqa: C901
                 return
 
             # ----- Permission gate (T043-T049) -----
-            allowed = await _check_permission_gate(
-                call_id, fname, args_obj, session_id, correlation_id
-            )
-            if not allowed:
-                # Gate already resolved the Future with an error envelope.
-                span.set_attribute("ummaya.permission.decision", "deny")
-                return
+            if not local_document_harness_call:
+                allowed = await _check_permission_gate(
+                    call_id, fname, args_obj, session_id, correlation_id
+                )
+                if not allowed:
+                    # Gate already resolved the Future with an error envelope.
+                    span.set_attribute("ummaya.permission.decision", "deny")
+                    return
+            else:
+                span.set_attribute("ummaya.permission.mode", "local_document_harness")
+                span.set_attribute("ummaya.permission.decision", "allow_once")
 
             result_payload: dict[str, object] = {}
             dispatch_error: str | None = None
@@ -6403,7 +6803,43 @@ async def run(  # noqa: C901
             _outbound_trace_token = start_outbound_capture()
 
             try:
-                if fname == "check":
+                document_harness_dispatched = False
+                document_tool_id = str(args_obj.get("tool_id") or "")
+                if document_tool_id:
+                    registry = _ensure_tool_registry()
+                    try:
+                        document_tool = registry.find(document_tool_id)
+                    except Exception:
+                        document_tool = None
+                    if document_tool is not None and _is_local_document_harness_tool(document_tool):
+                        document_harness_dispatched = True
+                        if document_tool.primitive != fname:
+                            dispatch_error = (
+                                f"Adapter {document_tool_id!r} is "
+                                f"primitive={document_tool.primitive!r}, "
+                                f"but was called through {fname}."
+                            )
+                        else:
+                            executor = _ensure_tool_executor()
+                            document_params = cast(
+                                "dict[str, object]",
+                                args_obj.get("params") or {},
+                            )
+                            raw = await executor.invoke_raw(
+                                tool_id=document_tool_id,
+                                params=document_params,
+                                request_id=str(uuid.uuid4()),
+                                session_identity=session_id,
+                            )
+                            result_payload = {
+                                "kind": fname,
+                                "result": _serialize_primitive_result(raw),
+                            }
+
+                if document_harness_dispatched:
+                    pass
+
+                elif fname == "check":
                     from ummaya.primitives.verify import (  # noqa: PLC0415
                         verify,
                     )
@@ -6476,6 +6912,14 @@ async def run(  # noqa: C901
                         LookupFetchInput,
                     )
 
+                    lookup_context = _session_latest_user_utterances.get(
+                        session_id, ""
+                    ) or _lookup_context_from_args(args_obj)
+                    args_obj = _normalize_lookup_args_for_query(
+                        fname,
+                        args_obj,
+                        lookup_context,
+                    )
                     requested_mode = args_obj.get("mode")
                     if requested_mode is not None and str(requested_mode) != "fetch":
                         logger.warning(
@@ -6516,17 +6960,31 @@ async def run(  # noqa: C901
                                 lookup_params,
                                 auth_context,
                             )
-                        inp_lk = LookupFetchInput(
-                            mode="fetch",
-                            tool_id=str(args_obj.get("tool_id", "")),
-                            params=lookup_params,
-                        )
-                        raw = await find(
-                            inp_lk,
-                            registry=registry,
-                            executor=executor,
-                            session_identity=session_id,
-                        )
+                        lookup_tool_id = str(args_obj.get("tool_id") or "").strip()
+                        if not lookup_tool_id or lookup_tool_id in _ROOT_PRIMITIVE_TOOL_IDS:
+                            raw = LookupError(
+                                kind="error",
+                                reason=LookupErrorReason.invalid_params,
+                                message=(
+                                    "find(mode='fetch') requires a concrete adapter tool_id "
+                                    "from the current available adapter set. No concrete "
+                                    "adapter was selected, so UMMAYA stopped this malformed "
+                                    "tool call instead of retrying it."
+                                ),
+                                retryable=False,
+                            )
+                        else:
+                            inp_lk = LookupFetchInput(
+                                mode="fetch",
+                                tool_id=lookup_tool_id,
+                                params=lookup_params,
+                            )
+                            raw = await find(
+                                inp_lk,
+                                registry=registry,
+                                executor=executor,
+                                session_identity=session_id,
+                            )
                         result_payload = {
                             "kind": "find",
                             "result": _serialize_primitive_result(raw),
@@ -6815,9 +7273,23 @@ async def run(  # noqa: C901
         # CC-style loop contract: the model can paint progress prose, then call
         # a primitive dispatcher with a concrete adapter in `tool_id`.
         registry = cast("Any", _ensure_tool_registry())
-        backend_tools_raw = [
-            t.to_openai_tool() for t in _select_concrete_adapter_tools_for_turn(latest_user_utt)
-        ]
+        turn_route_decision = _route_decision_for_turn(latest_user_utt)
+        from ummaya.ipc.route_diagnostics import (  # noqa: PLC0415
+            log_route_decision_diagnostic,
+        )
+
+        log_route_decision_diagnostic(
+            logger=logger,
+            turn_index=_diag_turn_idx,
+            session_id=frame.session_id,
+            correlation_id=frame.correlation_id,
+            decision=turn_route_decision,
+        )
+        turn_concrete_adapter_tools = _select_concrete_adapter_tools_for_turn(
+            latest_user_utt, route_decision=turn_route_decision
+        )
+        turn_concrete_adapter_tool_ids = tuple(t.id for t in turn_concrete_adapter_tools)
+        backend_tools_raw = [t.to_openai_tool() for t in turn_concrete_adapter_tools]
         backend_tool_names: set[object] = set()
         for raw_tool in backend_tools_raw:
             if not isinstance(raw_tool, dict):
@@ -6951,7 +7423,11 @@ async def run(  # noqa: C901
                         (latest_user_utt or "")[:256],
                     )
                 if latest_user_utt:
-                    suffix_block = _build_available_adapters_suffix(latest_user_utt)
+                    suffix_block = _build_available_adapters_suffix(
+                        latest_user_utt,
+                        route_decision=turn_route_decision,
+                        visible_tool_ids=turn_concrete_adapter_tool_ids,
+                    )
                     if suffix_block:
                         augmented_system = augmented_system + "\n\n" + suffix_block + "\n"
             except Exception:  # noqa: BLE001 — fail-open per FR-002
@@ -7024,6 +7500,7 @@ async def run(  # noqa: C901
         force_verify_next_turn: str | None = None
         force_lookup_next_turn: str | None = None
         force_submit_next_turn: str | None = None
+        force_document_next_turn: str | None = None
         force_no_tools_next_turn = False
         continue_free_next_turn = False
         mock_disclosure_required = False
@@ -7180,20 +7657,33 @@ async def run(  # noqa: C901
                     force_submit_next_turn,
                 )
                 force_submit_next_turn = None
+            elif (
+                force_document_next_turn is not None
+                and force_document_next_turn in _tool_definition_names(stream_tools)
+            ):
+                stream_tool_choice = _function_tool_choice(force_document_next_turn)
+                logger.warning(
+                    "_handle_chat_request: forcing concrete document adapter %s "
+                    "after validation gate",
+                    force_document_next_turn,
+                )
+                force_document_next_turn = None
             elif (
                 force_locate_next_turn
                 or force_verify_next_turn is not None
                 or force_lookup_next_turn is not None
                 or force_submit_next_turn is not None
+                or force_document_next_turn is not None
             ):
                 logger.warning(
                     "_handle_chat_request: continuing turn %d with free tool_choice "
-                    "after validation gate hint (locate=%s check=%s find=%s send=%s)",
+                    "after validation gate hint (locate=%s check=%s find=%s send=%s document=%s)",
                     _turn,
                     force_locate_next_turn,
                     force_verify_next_turn,
                     force_lookup_next_turn,
                     force_submit_next_turn,
+                    force_document_next_turn,
                 )
             try:
                 stream_kwargs: dict[str, object] = {
@@ -7490,6 +7980,37 @@ async def run(  # noqa: C901
                     buffered_visible.clear()
                     continue
 
+                document_followup_gate = _check_document_workflow_terminated_without_required_tool(
+                    llm_messages,
+                    latest_user_utt,
+                )
+                if document_followup_gate is not None:
+                    document_tool_id = document_followup_gate["tool_id"]
+                    try:
+                        document_tool = _ensure_tool_registry().find(document_tool_id)
+                        document_primitive = str(getattr(document_tool, "primitive", "") or "")
+                    except Exception:  # noqa: BLE001
+                        document_primitive = ""
+                    if document_primitive == "find":
+                        force_lookup_next_turn = document_tool_id
+                    elif document_primitive == "send":
+                        force_submit_next_turn = document_tool_id
+                    elif document_primitive == "check":
+                        force_verify_next_turn = document_tool_id
+                    elif document_primitive == "document":
+                        force_document_next_turn = document_tool_id
+                    else:
+                        continue_free_next_turn = True
+                    _append_tool_routing_observation(
+                        (
+                            "rejected final-answer turn — document workflow "
+                            f"missing {document_tool_id}"
+                        ),
+                        document_followup_gate["message"],
+                    )
+                    buffered_visible.clear()
+                    continue
+
                 from ummaya.llm.tool_call_parser import (  # noqa: PLC0415
                     strip_leaked_thinking_markers,
                 )
@@ -7503,9 +8024,46 @@ async def run(  # noqa: C901
                 else:
                     merged_prose = _remove_unneeded_mock_disclosure(merged_prose)
                     merged_prose = _remove_unneeded_live_meta_disclosure(merged_prose)
+                document_followup_gate = _check_document_workflow_terminated_without_required_tool(
+                    llm_messages,
+                    latest_user_utt,
+                    candidate_final_answer=merged_prose,
+                )
+                if document_followup_gate is not None:
+                    document_tool_id = document_followup_gate["tool_id"]
+                    try:
+                        document_tool = _ensure_tool_registry().find(document_tool_id)
+                        document_primitive = str(getattr(document_tool, "primitive", "") or "")
+                    except Exception:  # noqa: BLE001
+                        document_primitive = ""
+                    if document_primitive == "find":
+                        force_lookup_next_turn = document_tool_id
+                    elif document_primitive == "send":
+                        force_submit_next_turn = document_tool_id
+                    elif document_primitive == "check":
+                        force_verify_next_turn = document_tool_id
+                    elif document_primitive == "document":
+                        force_document_next_turn = document_tool_id
+                    else:
+                        continue_free_next_turn = True
+                    _append_tool_routing_observation(
+                        (
+                            "rejected final-answer turn — document workflow "
+                            f"missing {document_tool_id}"
+                        ),
+                        document_followup_gate["message"],
+                    )
+                    buffered_visible.clear()
+                    continue
                 has_successful_tool_result = _conversation_has_successful_any_primitive_result(
                     llm_messages
                 )
+                diff_only_document_answer = _document_diff_only_final_answer(
+                    latest_user_utt,
+                    llm_messages,
+                )
+                if diff_only_document_answer is not None:
+                    merged_prose = diff_only_document_answer
                 if (
                     merged_prose.strip()
                     and _final_answer_looks_like_tool_call_narration(merged_prose)
@@ -7525,6 +8083,47 @@ async def run(  # noqa: C901
                     )
                     buffered_visible.clear()
                     continue
+                if (
+                    merged_prose.strip()
+                    and has_successful_tool_result
+                    and _final_answer_overclaims_document_edit(merged_prose, llm_messages)
+                ):
+                    if empty_final_retry_count < 2:
+                        empty_final_retry_count += 1
+                        _append_final_answer_observation(
+                            "rejected document final answer overclaimed observed diff",
+                            (
+                                "The previous assistant turn claimed document content or "
+                                "work sections not present in the latest document diff. "
+                                "Document diff changes are the only approved edit claims. "
+                                "Produce a concise Korean final answer using only "
+                                "result.status, text_summary, and diff.changes "
+                                "display_label/target_path/before_value/after_value from "
+                                "the latest document tool_result. Do not add activity content, "
+                                "achievements, next plans, problems, improvements, render "
+                                "artifacts, or document sections unless they appear in "
+                                "diff.changes."
+                            ),
+                        )
+                        buffered_visible.clear()
+                        continue
+                    await write_frame(
+                        ErrorFrame(
+                            session_id=frame.session_id,
+                            correlation_id=frame.correlation_id or str(uuid.uuid4()),
+                            role="backend",
+                            ts=_utcnow(),
+                            kind="error",
+                            code="document_final_answer_overclaim",
+                            message=(
+                                "Model returned an ungrounded document final answer "
+                                "after successful document diff results. No synthetic "
+                                "answer was generated."
+                            ),
+                            details={"retry_count": empty_final_retry_count},
+                        )
+                    )
+                    return
                 if not merged_prose.strip() and has_successful_tool_result:
                     if empty_final_retry_count < 2:
                         empty_final_retry_count += 1
@@ -8520,6 +9119,7 @@ async def run(  # noqa: C901
                     or force_verify_next_turn is not None
                     or force_lookup_next_turn is not None
                     or force_submit_next_turn is not None
+                    or force_document_next_turn is not None
                     or continue_free_next_turn
                 ):
                     if continue_free_next_turn:
@@ -8919,10 +9519,13 @@ async def run(  # noqa: C901
             user_query=_session_latest_user_utterances.get(frame.session_id, ""),
         )
         dispatch_args = _normalize_root_primitive_adapter_envelope(dispatch_name, dispatch_args)
+        lookup_context = _session_latest_user_utterances.get(
+            frame.session_id, ""
+        ) or _lookup_context_from_args(dispatch_args)
         dispatch_args = _normalize_lookup_args_for_query(
             dispatch_name,
             dispatch_args,
-            _session_latest_user_utterances.get(frame.session_id, ""),
+            lookup_context,
         )
 
         kma_aviation_choice_msg = _check_kma_aviation_tool_choice_prerequisite(
@@ -9145,6 +9748,35 @@ async def run(  # noqa: C901
                     await _handle_tool_call(frame)
                 except Exception as exc:  # noqa: BLE001
                     logger.exception("tool_call handler failed: %s", exc)
+                    try:
+                        from ummaya.ipc.frame_schema import (  # noqa: PLC0415
+                            ToolCallFrame,
+                            ToolResultEnvelope,
+                            ToolResultFrame,
+                        )
+                        from ummaya.primitives import PRIMITIVE_REGISTRY  # noqa: PLC0415
+
+                        if isinstance(frame, ToolCallFrame):
+                            error_kind = frame.name if frame.name in PRIMITIVE_REGISTRY else "find"
+                            await write_frame(
+                                ToolResultFrame(
+                                    session_id=frame.session_id,
+                                    correlation_id=frame.correlation_id,
+                                    role="backend",
+                                    ts=_utcnow(),
+                                    kind="tool_result",
+                                    call_id=frame.call_id,
+                                    envelope=ToolResultEnvelope.model_validate(
+                                        {
+                                            "kind": error_kind,
+                                            "error": f"tool_call handler failed: {exc}",
+                                            "tool_id": frame.name,
+                                        }
+                                    ),
+                                )
+                            )
+                    except Exception:  # noqa: BLE001
+                        logger.exception("failed to emit tool_call failure result")
 
             elif frame.kind == "permission_response":
                 # Spec 1978 T047 — resolve pending permission Future.