ummaya 0.2.3 → 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",
@@ -188,6 +218,69 @@ _PRIMITIVE_ERROR_REASONS: Final[frozenset[str]] = frozenset(
         "verify_tool_choice_mismatch",
     }
 )
+_ROOT_PRIMITIVE_TOOL_NAMES: Final[frozenset[str]] = frozenset({"find", "locate", "check", "send"})
+_KMA_AIR_TOOL_IDS: Final[frozenset[str]] = frozenset(
+    {
+        "kma_apihub_url_air_amos_minute",
+        "kma_apihub_url_air_metar_decoded",
+    }
+)
+_KMA_ORDINARY_WEATHER_TOOL_IDS: Final[frozenset[str]] = frozenset(
+    {
+        "kma_current_observation",
+        "kma_ultra_short_term_forecast",
+        "kma_short_term_forecast",
+    }
+)
+_KMA_LOCATION_TOOL_IDS: Final[frozenset[str]] = frozenset(
+    {
+        "kakao_keyword_search",
+        "kakao_address_search",
+        "kakao_coord_to_region",
+    }
+)
+_KMA_AIRPORT_PLACE_RE: Final = re.compile(
+    r"(김해|김포|김해공항|김포공항|gimhae|gimpo|rkpk|rkss|\bairport\b|공항)",
+    re.IGNORECASE,
+)
+_KMA_AIRPORT_AVIATION_RE: Final = re.compile(
+    r"(비행기|항공편|비행편|운항|이륙|착륙|결항|지연|뜰\s*만|뜨나|뜰\s*수|"
+    r"flight|take\s*off|landing|delay|cancel|metar|speci|amos|rvr|활주로|"
+    r"시정|visibility|공항기상|항공기상)",
+    re.IGNORECASE,
+)
+_SYNTHETIC_USER_CONTEXT_RE: Final = re.compile(
+    r"<available_adapters\b|</available_adapters>|"
+    r"Pick a concrete adapter from <available_adapters>|"
+    r"Prefer concrete adapter function calls",
+    re.IGNORECASE,
+)
+_TOOL_RESULT_USER_CONTEXT_RE: Final = re.compile(
+    r"^\s*(?:<tool_use_error>|AdapterNotFound:|Permission delegation required:|Error:)"
+    r"|</tool_use_error>",
+    re.IGNORECASE,
+)
+
+
+def _is_citizen_user_utterance_text(content: object) -> bool:
+    if not isinstance(content, str):
+        return False
+    text = content.strip()
+    if not text:
+        return False
+    if _SYNTHETIC_USER_CONTEXT_RE.search(text):
+        return False
+    return _TOOL_RESULT_USER_CONTEXT_RE.search(text) is None
+
+
+def _latest_citizen_user_utterance(messages: Collection[Any]) -> str:
+    for message in reversed(list(messages)):
+        if getattr(message, "role", None) != "user":
+            continue
+        content = getattr(message, "content", None)
+        if _is_citizen_user_utterance_text(content):
+            return cast(str, content)
+    return ""
 
 
 def _should_append_tui_tool_to_llm_tools(
@@ -203,6 +296,48 @@ 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],
+) -> dict[str, object]:
+    """Normalize root primitive envelopes before strict adapter validation."""
+    if fname not in _ROOT_PRIMITIVE_TOOL_NAMES:
+        return args_obj
+    params_raw = args_obj.get("params")
+    if not isinstance(params_raw, dict):
+        return args_obj
+    nested_tool_id = params_raw.get("tool_id")
+    if not isinstance(nested_tool_id, str) or not nested_tool_id:
+        return args_obj
+    top_level_tool_id = args_obj.get("tool_id")
+    if top_level_tool_id == fname and nested_tool_id not in _ROOT_PRIMITIVE_TOOL_NAMES:
+        normalized = dict(args_obj)
+        normalized["tool_id"] = nested_tool_id
+        normalized["params"] = {key: value for key, value in params_raw.items() if key != "tool_id"}
+        return normalized
+    if nested_tool_id == top_level_tool_id:
+        normalized = dict(args_obj)
+        normalized["params"] = {key: value for key, value in params_raw.items() if key != "tool_id"}
+        return normalized
+    return args_obj
+
+
+def _function_tool_choice(tool_name: str) -> dict[str, object]:
+    """Return OpenAI-compatible forced function-call syntax."""
+    return {"type": "function", "function": {"name": tool_name}}
+
+
+def _tool_definition_names(tool_defs: list[Any] | None) -> set[str]:
+    if tool_defs is None:
+        return set()
+    return {tool.function.name for tool in tool_defs}
+
+
 _VERIFY_QUERY_REQUIREMENTS: Final[tuple[tuple[tuple[str, ...], dict[str, str]], ...]] = (
     (
         ("간편인증", "pass 인증", "kakao 인증", "naver 인증"),
@@ -259,6 +394,19 @@ _VERIFY_QUERY_REQUIREMENTS: Final[tuple[tuple[tuple[str, ...], dict[str, str]],
             "purpose_en": "Gov24 resident registration certificate civil petition",
         },
     ),
+    (
+        ("소득금액증명원", "소득금액증명"),
+        {
+            "verify_tool_id": "mock_verify_module_simple_auth",
+            "allowed_tool_ids": (
+                "mock_verify_module_simple_auth,mock_verify_mobile_id,mock_verify_ganpyeon_injeung"
+            ),
+            "scope": "check:ganpyeon.identity",
+            "allowed_scopes": "check:ganpyeon.identity,check:mobile_id.identity",
+            "purpose_ko": "소득금액증명원 발급 본인확인",
+            "purpose_en": "Income certificate identity verification",
+        },
+    ),
     (
         ("복지 급여 신청", "한부모가족", "아동양육비"),
         {
@@ -304,6 +452,8 @@ _LOCATION_INDEPENDENT_WORKFLOW_HINTS_KO: Final[frozenset[str]] = frozenset(
         "모바일신분증",
         "마이데이터",
         "공공마이데이터",
+        "소득금액증명원",
+        "소득금액증명",
         "과태료",
         "교통범칙금",
         "범칙금",
@@ -543,23 +693,44 @@ def _kma_observation_base_slot_hint(now_kst: datetime) -> tuple[str, str, str]:
 
 
 def _final_answer_looks_like_pending_tool_plan(text: str) -> bool:
-    """Return true when final prose says it will call tools after tools already ran."""
+    """Return true when final prose is still planning after tools already ran."""
     normalized = " ".join(text.strip().split())
     if not normalized:
         return False
     pending_markers = (
         "호출하겠습니다",
         "조회하겠습니다",
+        "조회해 보겠습니다",
         "찾아보겠습니다",
         "검색하겠습니다",
         "진행하겠습니다",
         "확인하겠습니다",
+        "확인해 보겠습니다",
         "will call",
         "i'll call",
         "i will call",
         "will look up",
     )
-    return any(marker in normalized.lower() for marker in pending_markers)
+    lowered = normalized.lower()
+    if any(marker in lowered for marker in pending_markers):
+        return True
+
+    meta_instruction_markers = (
+        "이제 응급 상황에 대한 지침을 제공해야 합니다",
+        "최종 답변은 다음과 같아야 합니다",
+        "도구 결과에서 그대로 가져와야 합니다",
+        "final answer should",
+        "the final answer should",
+        "should provide",
+        "should answer",
+    )
+    if any(marker in lowered for marker in meta_instruction_markers):
+        return True
+    return bool(
+        re.search(r"(?:답변|응답|최종 답변)[^.?!。]{0,40}해야 합니다", normalized)
+        or re.search(r"이제 [^.?!。]{0,60}(?:제공|안내|작성)해야 합니다", normalized)
+        or re.search(r"도구 결과[^.?!。]{0,60}가져와야 합니다", normalized)
+    )
 
 
 def _final_answer_looks_like_recursive_tool_message(text: str) -> bool:
@@ -675,6 +846,8 @@ def _final_answer_looks_like_tool_call_narration(text: str) -> bool:
     normalized = " ".join(text.strip().split())
     if not normalized:
         return False
+    if "<tool_call>" in normalized or "</tool_call>" in normalized:
+        return True
     head = normalized[:700]
     if "도구" not in head:
         return False
@@ -723,6 +896,244 @@ def _final_answer_looks_like_generic_retry_after_success(text: str) -> bool:
     return not bool(re.search(r"\d", normalized))
 
 
+_KMA_ANALYSIS_USER_QUERY_RE: Final = re.compile(
+    r"(분석자료|이미\s*분석|고해상도\s*격자|객관분석|AWS\s*객관|지도\s*자료|"
+    r"일기도|분석일기도|비구름|바람\s*흐름|synoptic|weather\s*chart|"
+    r"objective\s*analysis|high[-\s]?resolution|grid)",
+    re.IGNORECASE,
+)
+_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",
+        "kma_apihub_url_aws_objective_analysis_grid",
+        "kma_apihub_url_analysis_weather_chart_image",
+    }
+)
+_PPS_BID_USER_QUERY_RE: Final = re.compile(
+    r"(입찰|나라장터|조달청|공고|공사조회|전기공사|bid|procurement)",
+    re.IGNORECASE,
+)
+_AIRKOREA_USER_QUERY_RE: Final = re.compile(
+    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(
+    r"(버스|시내버스|정류장|정류소|노선|도착|언제\s*와|몇\s*분|bus|route|arrival|station)",
+    re.IGNORECASE,
+)
+_TAGO_ROUTE_NO_RE: Final = re.compile(r"(?:^|[^\d])(\d{1,4}(?:-\d)?)\s*번")
+_TAGO_TOOL_IDS: Final[frozenset[str]] = frozenset(
+    {
+        "tago_bus_station_search",
+        "tago_bus_arrival_search",
+        "tago_bus_route_search",
+        "tago_bus_route_station_search",
+        "tago_bus_location_search",
+    }
+)
+_AIRKOREA_TOOL_ID: Final = "airkorea_ctprvn_air_quality"
+_PPS_BID_TOOL_ID: Final = "pps_bid_public_info"
+_KMA_ANALYSIS_CHART_TOOL_ID: Final = "kma_apihub_url_analysis_weather_chart_image"
+
+
+def _initial_concrete_tool_choice_for_query(
+    user_query: str,
+    available_tool_names: Collection[str],
+) -> 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 (
+        _DOCUMENT_ARTIFACT_ID_RE.search(user_query)
+        and _DOCUMENT_REVIEW_REQUEST_RE.search(user_query)
+        and "document" in available
+    ):
+        return "document"
+    if is_document_harness_query(user_query) and "document" in available:
+        return "document"
+    return None
+
+
+def _final_answer_looks_like_kma_analysis_fabrication(text: str, user_query: str) -> bool:
+    """Detect KMA analysis answers that fill failed lookups with general knowledge."""
+    if not _KMA_ANALYSIS_USER_QUERY_RE.search(user_query):
+        return False
+    normalized = " ".join(text.strip().split())
+    if not normalized:
+        return False
+    failure_markers = (
+        "데이터가 비어",
+        "확인할 수 없",
+        "접근할 수 없",
+        "조회가 어려",
+        "직접 접근할 수 없는",
+        "전체 내용을 확인할 수 없",
+        "실패",
+    )
+    fabrication_markers = (
+        "일반적인 지식",
+        "일반적 정보",
+        "일반적으로",
+        "판단됩니다",
+        "특별한 기상 상황은 아닌",
+    )
+    return any(marker in normalized for marker in failure_markers) and any(
+        marker in normalized for marker in fabrication_markers
+    )
+
+
+def _conversation_has_kma_chart_upstream_failure(llm_messages: list[Any]) -> bool:
+    """Return True when a KMA analyzed weather-chart lookup failed upstream."""
+    for msg in reversed(llm_messages):
+        if getattr(msg, "role", None) != "tool":
+            continue
+        content = str(getattr(msg, "content", "") or "")
+        name = str(getattr(msg, "name", "") or "")
+        if (
+            "kma_apihub_url_analysis_weather_chart_image" not in content
+            and name != "kma_apihub_url_analysis_weather_chart_image"
+        ):
+            continue
+        normalized = " ".join(content.split())
+        return any(
+            marker in normalized
+            for marker in (
+                "활용신청",
+                "approval",
+                "upstream_error",
+                "403",
+                "error",
+                "failed",
+            )
+        )
+    return False
+
+
+def _final_answer_substitutes_after_kma_chart_failure(
+    text: str,
+    user_query: str,
+    llm_messages: list[Any],
+) -> bool:
+    """Detect map/chart answers that substitute other evidence after chart failure."""
+    if not _KMA_ANALYSIS_MAP_USER_QUERY_RE.search(user_query):
+        return False
+    if not _conversation_has_kma_chart_upstream_failure(llm_messages):
+        return False
+    normalized = " ".join(text.strip().split())
+    if not normalized:
+        return False
+    substitution_markers = (
+        "AWS 객관",
+        "고해상도",
+        "현재 관측망",
+        "관측값",
+        "기온",
+        "풍속",
+        "풍향",
+        "시정",
+        "강수량",
+        "상대습도",
+        "대안으로",
+        "일반적인",
+        "일반적",
+        "패턴상",
+        "가능성",
+        "추정",
+        "보입니다",
+        "서풍",
+        "남해안",
+    )
+    return any(marker in normalized for marker in substitution_markers)
+
+
 def _conversation_has_successful_any_primitive_result(llm_messages: list[Any]) -> bool:
     """Return True when the loop already has a successful primitive result."""
     return (
@@ -730,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")
     )
 
 
@@ -1347,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):
@@ -1359,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],
     *,
@@ -1402,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(
@@ -1485,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(
@@ -1517,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:
@@ -1548,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
 
 
@@ -1754,6 +2428,43 @@ def _latest_successful_primitive_result(
     return None
 
 
+def _latest_successful_locate_result_with_coords(
+    llm_messages: list[Any],
+    *,
+    registry: Any = None,
+) -> dict[str, object] | None:
+    """Return the most recent successful locate result that carries WGS-84 coords."""
+    if registry is not None:
+        matching_call_ids = _primitive_call_ids_for_tool(
+            llm_messages,
+            primitive="locate",
+            registry=registry,
+        )
+        for msg in reversed(llm_messages):
+            payload = _tool_result_payload_for_primitive_call(
+                msg,
+                primitive="locate",
+                matching_call_ids=matching_call_ids,
+            )
+            if payload is None or not _primitive_payload_is_success(
+                payload,
+                primitive="locate",
+            ):
+                continue
+            result = _primitive_payload_result_dict(payload)
+            if result is not None and _locate_result_coords(result) is not None:
+                return result
+
+    for msg in reversed(llm_messages):
+        payload = _tool_result_payload_for_primitive(msg, primitive="locate")
+        if payload is None or not _primitive_payload_is_success(payload, primitive="locate"):
+            continue
+        result = _primitive_payload_result_dict(payload)
+        if result is not None and _locate_result_coords(result) is not None:
+            return result
+    return None
+
+
 def _latest_successful_primitive_result_for_tool(
     llm_messages: list[Any],
     *,
@@ -1829,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:
@@ -1839,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:
@@ -1857,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,
@@ -1877,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"
@@ -1884,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 "
@@ -1950,6 +2849,38 @@ def _region_pair_from_address_text(text: object) -> tuple[str, str] | None:
     return q0, q1
 
 
+def _sido_name_from_user_query(user_query: str) -> str | None:
+    """Extract a Korean 시도 name when citizen wording contains one."""
+
+    for full_name in _KOREAN_SIDO_ABBREVIATIONS.values():
+        if full_name in user_query:
+            return full_name
+    for short_name, full_name in _KOREAN_SIDO_ABBREVIATIONS.items():
+        pattern = re.compile(
+            rf"{re.escape(short_name)}(?:시|도|특별시|광역시|특별자치시|특별자치도)?"
+        )
+        if pattern.search(user_query):
+            return full_name
+    return None
+
+
+def _pps_current_week_window(now: datetime | None = None) -> tuple[str, str]:
+    """Return PPS YYYYMMDDHHMM bounds for the current KST week through today."""
+
+    from zoneinfo import ZoneInfo  # noqa: PLC0415
+
+    kst = ZoneInfo("Asia/Seoul")
+    kst_now = datetime.now(kst) if now is None else now.astimezone(kst)
+    week_start = (kst_now - timedelta(days=kst_now.weekday())).replace(
+        hour=0,
+        minute=0,
+        second=0,
+        microsecond=0,
+    )
+    today_end = kst_now.replace(hour=23, minute=59, second=0, microsecond=0)
+    return week_start.strftime("%Y%m%d%H%M"), today_end.strftime("%Y%m%d%H%M")
+
+
 def _locate_result_region_pair(result: dict[str, object]) -> tuple[str, str] | None:  # noqa: C901
     """Extract NMC region-mode q0/q1 from a locate result."""
     for key in ("region", "coords"):
@@ -2060,6 +2991,13 @@ def _nmc_lookup_params_with_clean_qn(
     return raw_params, params
 
 
+def _nmc_origin_needs_locate_repair(params: dict[str, object]) -> bool:
+    """Return True when region-mode origin coords lost locate precision."""
+    if params.get("origin_lat") is None and params.get("origin_lon") is None:
+        return True
+    return _is_whole_degree_pair(params.get("origin_lat"), params.get("origin_lon"))
+
+
 def _is_whole_degree_pair(lat: object, lon: object) -> bool:
     """Return True for rounded whole-degree WGS-84 coordinate pairs."""
     if isinstance(lat, bool) or isinstance(lon, bool):
@@ -2084,10 +3022,15 @@ def _normalize_reverse_geocode_args_from_prior_locate(
     was already available in the prior locate result, keep the selected adapter
     and repair only this derived argument pair.
     """
-    if fname != "locate" or args_obj.get("tool_id") not in _REVERSE_GEOCODE_TOOL_IDS:
+    wraps_root_primitive = False
+    if fname == "locate" and args_obj.get("tool_id") in _REVERSE_GEOCODE_TOOL_IDS:
+        raw_params = args_obj.get("params")
+        wraps_root_primitive = True
+    elif fname in _REVERSE_GEOCODE_TOOL_IDS:
+        raw_params = args_obj
+    else:
         return args_obj
 
-    raw_params = args_obj.get("params")
     if not isinstance(raw_params, dict):
         return args_obj
 
@@ -2106,12 +3049,45 @@ def _normalize_reverse_geocode_args_from_prior_locate(
     if coords is None:
         return args_obj
 
+    next_params = dict(raw_params)
+    next_params["lat"], next_params["lon"] = coords
+    if wraps_root_primitive:
+        normalized = dict(args_obj)
+        normalized["params"] = next_params
+    else:
+        normalized = next_params
+    logger.info(
+        "locate: normalized %s rounded lat/lon from prior locate lat=%s lon=%s",
+        args_obj.get("tool_id") if wraps_root_primitive else fname,
+        coords[0],
+        coords[1],
+    )
+    return normalized
+
+
+def _normalize_reverse_geocode_args_from_locate_result(
+    args_obj: dict[str, object],
+    locate_result: dict[str, object],
+) -> dict[str, object]:
+    """Fill reverse-geocode lat/lon from an already observed locate result."""
+    if args_obj.get("tool_id") not in _REVERSE_GEOCODE_TOOL_IDS:
+        return args_obj
+    raw_params = args_obj.get("params")
+    if not isinstance(raw_params, dict):
+        return args_obj
+    if not _is_whole_degree_pair(raw_params.get("lat"), raw_params.get("lon")):
+        return args_obj
+
+    coords = _locate_result_coords(locate_result)
+    if coords is None:
+        return args_obj
+
     next_params = dict(raw_params)
     next_params["lat"], next_params["lon"] = coords
     normalized = dict(args_obj)
     normalized["params"] = next_params
     logger.info(
-        "locate: normalized %s rounded lat/lon from prior locate lat=%s lon=%s",
+        "locate: normalized cached %s rounded lat/lon from latest locate lat=%s lon=%s",
         args_obj.get("tool_id"),
         coords[0],
         coords[1],
@@ -2146,7 +3122,8 @@ def _normalize_nmc_lookup_args_from_prior_locate(
         and bool(_nonempty_str(params.get("q0")))
         and bool(_nonempty_str(params.get("q1")))
     )
-    if has_region_params and not needs_default_limit:
+    needs_origin_repair = _nmc_origin_needs_locate_repair(params)
+    if has_region_params and not needs_default_limit and not needs_origin_repair:
         if params != raw_params and isinstance(raw_params, dict):
             normalized = dict(args_obj)
             normalized["params"] = params
@@ -2159,13 +3136,24 @@ def _normalize_nmc_lookup_args_from_prior_locate(
         registry=registry,
     )
     if locate_result is None:
-        if has_region_params and needs_default_limit:
+        if has_region_params:
             normalized = dict(args_obj)
             next_params = dict(params)
-            next_params["limit"] = 5
-            normalized["params"] = next_params
-            return normalized
+            if needs_default_limit:
+                next_params["limit"] = 5
+            if next_params != raw_params and isinstance(raw_params, dict):
+                normalized["params"] = next_params
+                return normalized
         return args_obj
+    if _locate_result_coords(locate_result) is None:
+        locate_result_with_coords = _latest_successful_locate_result_with_coords(
+            llm_messages,
+            registry=registry,
+        )
+        if locate_result_with_coords is not None:
+            merged_locate_result = dict(locate_result_with_coords)
+            merged_locate_result.update(locate_result)
+            locate_result = merged_locate_result
 
     return _normalize_nmc_lookup_args_from_locate_result(args_obj, locate_result)
 
@@ -2185,10 +3173,18 @@ def _normalize_nmc_lookup_args_from_locate_result(
         and bool(_nonempty_str(params.get("q0")))
         and bool(_nonempty_str(params.get("q1")))
     )
-    if has_region_params and not needs_default_limit:
-        if params != raw_params and isinstance(raw_params, dict):
+    needs_origin_repair = _nmc_origin_needs_locate_repair(params)
+    if has_region_params:
+        origin_coords = _locate_result_coords(locate_result)
+        next_params = dict(params)
+        if needs_origin_repair and origin_coords is not None:
+            next_params["origin_lat"] = origin_coords[0]
+            next_params["origin_lon"] = origin_coords[1]
+        if needs_default_limit:
+            next_params["limit"] = 5
+        if next_params != params or (params != raw_params and isinstance(raw_params, dict)):
             normalized = dict(args_obj)
-            normalized["params"] = params
+            normalized["params"] = next_params
             return normalized
         return args_obj
 
@@ -2227,6 +3223,27 @@ def _normalize_nmc_lookup_args_from_locate_result(
     return normalized
 
 
+def _normalize_nmc_aed_args_from_locate_result(
+    args_obj: dict[str, object],
+    locate_result: dict[str, object],
+) -> dict[str, object]:
+    """Fill NMC AED origin coords for client-side distance sorting."""
+    raw_params = args_obj.get("params")
+    if not isinstance(raw_params, dict):
+        return args_obj
+    coords = _locate_result_coords(locate_result)
+    if coords is None:
+        return args_obj
+    if not _nmc_origin_needs_locate_repair(raw_params):
+        return args_obj
+    next_params = dict(raw_params)
+    next_params["origin_lat"] = coords[0]
+    next_params["origin_lon"] = coords[1]
+    normalized = dict(args_obj)
+    normalized["params"] = next_params
+    return normalized
+
+
 _HIRA_DEPARTMENT_HINTS: tuple[tuple[re.Pattern[str], str], ...] = (
     (re.compile(r"소아청소년과|소아과|pediatrics?", re.IGNORECASE), "소아청소년과"),
     (re.compile(r"이비인후과|ent\b", re.IGNORECASE), "이비인후과"),
@@ -2384,14 +3401,37 @@ def _normalize_lookup_args_from_cached_locate_result(
     args_obj: dict[str, object],
     locate_result: dict[str, object] | None,
     *,
+    coordinate_locate_result: dict[str, object] | None = None,
     user_query: str = "",
 ) -> dict[str, object]:
     """Apply locate-derived argument repair in inbound concrete tool dispatch."""
-    if fname != "find" or locate_result is None:
+    if locate_result is None:
+        return args_obj
+    if fname == "locate":
+        return _normalize_reverse_geocode_args_from_locate_result(args_obj, locate_result)
+    if fname != "find":
         return args_obj
     tool_id = args_obj.get("tool_id")
     if tool_id == "nmc_emergency_search":
+        if (
+            _locate_result_coords(locate_result) is None
+            and coordinate_locate_result is not None
+            and _locate_result_coords(coordinate_locate_result) is not None
+        ):
+            merged_locate_result = dict(coordinate_locate_result)
+            merged_locate_result.update(locate_result)
+            locate_result = merged_locate_result
         return _normalize_nmc_lookup_args_from_locate_result(args_obj, locate_result)
+    if tool_id == "nmc_aed_site_locate":
+        if (
+            _locate_result_coords(locate_result) is None
+            and coordinate_locate_result is not None
+            and _locate_result_coords(coordinate_locate_result) is not None
+        ):
+            merged_locate_result = dict(coordinate_locate_result)
+            merged_locate_result.update(locate_result)
+            locate_result = merged_locate_result
+        return _normalize_nmc_aed_args_from_locate_result(args_obj, locate_result)
     if tool_id == "hira_hospital_search":
         return _normalize_hira_lookup_args_from_locate_result(
             args_obj,
@@ -2588,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
@@ -2692,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."
         ),
     }
 
@@ -2795,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
@@ -2848,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)
@@ -2898,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,
@@ -2908,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(
@@ -2919,6 +3981,62 @@ def _canonicalize_lookup_tool_id_for_query(
     return normalized
 
 
+def _set_param_if_empty(
+    params: dict[str, object],
+    key: str,
+    value: object,
+) -> bool:
+    if params.get(key) in (None, ""):
+        params[key] = value
+        return True
+    return False
+
+
+def _set_param_if_changed(
+    params: dict[str, object],
+    key: str,
+    value: object,
+) -> bool:
+    if params.get(key) != value:
+        params[key] = value
+        return True
+    return False
+
+
+def _normalize_pps_bid_args_from_user_query(
+    fname: str,
+    args_obj: dict[str, object],
+    user_query: str,
+) -> dict[str, object]:
+    """Fill PPS search-condition fields that are explicit in citizen wording."""
+
+    if fname != "find" or args_obj.get("tool_id") != _PPS_BID_TOOL_ID:
+        return args_obj
+    raw_params = args_obj.get("params")
+    params: dict[str, object] = dict(raw_params) if isinstance(raw_params, dict) else {}
+    changed = not isinstance(raw_params, dict)
+
+    if re.search(r"이번\s*주", user_query):
+        start_dt, end_dt = _pps_current_week_window()
+        changed = _set_param_if_changed(params, "inqry_bgn_dt", start_dt) or changed
+        changed = _set_param_if_changed(params, "inqry_end_dt", end_dt) or changed
+
+    if re.search(r"전기\s*공사", user_query, re.IGNORECASE):
+        changed = _set_param_if_empty(params, "bid_ntce_nm", "전기공사") or changed
+        changed = _set_param_if_empty(params, "indstryty_nm", "전기공사업") or changed
+
+    region_name = _sido_name_from_user_query(user_query)
+    if region_name is not None:
+        changed = _set_param_if_empty(params, "region_name", region_name) or changed
+        changed = _set_param_if_empty(params, "prtcpt_lmt_rgn_nm", region_name) or changed
+
+    if not changed:
+        return args_obj
+    normalized = dict(args_obj)
+    normalized["params"] = params
+    return normalized
+
+
 def _normalize_lookup_args_for_query(
     fname: str,
     args_obj: dict[str, object],
@@ -2931,11 +4049,13 @@ 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,
         adapter_param_names=adapter_param_names,
     )
+    args_obj = _normalize_pps_bid_args_from_user_query(fname, args_obj, user_query)
     if args_obj.get("tool_id") != "mohw_welfare_eligibility_search":
         return args_obj
     if not _query_contains_any(user_query, ("한부모가족", "한부모", "아동양육비")):
@@ -2965,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,
@@ -3159,9 +4294,13 @@ def _check_verify_tool_choice_prerequisite(
     purpose_ko = requirement["purpose_ko"]
     purpose_en = requirement["purpose_en"]
     if fname != "check":
+        from ummaya.tools.verify_canonical_map import resolve_tool_id  # noqa: PLC0415
+
+        canonical_verify_alias = resolve_tool_id(tool_id)
         wrong_verify_tool = (
             tool_id == "check"
             or tool_id.startswith("mock_verify_")
+            or canonical_verify_alias is not None
             or tool_id in allowed_tool_ids
             or _verify_tool_matches_requirement(
                 args_obj,
@@ -3861,6 +5000,155 @@ def _check_chain_prerequisite(  # noqa: C901
     )
 
 
+def _check_kma_analysis_tool_choice_prerequisite(
+    fname: str,
+    args_obj: dict[str, object],
+    user_query: str,
+) -> str | None:
+    """Reject cross-contaminated KMA analysis tool choices for map/chart wording."""
+    if not _KMA_ANALYSIS_MAP_USER_QUERY_RE.search(user_query):
+        return None
+    tool_id = fname if fname in _KMA_ANALYSIS_TOOL_IDS else args_obj.get("tool_id")
+    if not isinstance(tool_id, str):
+        params = args_obj.get("params")
+        if isinstance(params, dict):
+            nested_tool_id = params.get("tool_id")
+            tool_id = nested_tool_id if isinstance(nested_tool_id, str) else None
+    if tool_id not in _KMA_ANALYSIS_TOOL_IDS:
+        return None
+    if tool_id == "kma_apihub_url_analysis_weather_chart_image":
+        return None
+    return (
+        "KMA analysis tool-choice mismatch: the latest citizen request asks for "
+        "analyzed weather charts/map evidence such as 일기도, 지도 자료, 비구름, "
+        "or 바람 흐름. Do not carry over a prior point/grid-analysis path. "
+        "RECOVERY: call find with tool_id "
+        "kma_apihub_url_analysis_weather_chart_image for the latest query. If "
+        "APIHub returns 403 approval-required or another upstream error, report "
+        "that failure directly and do not substitute point-grid data or prior "
+        "airport observations."
+    )
+
+
+def _emitted_tool_id(fname: str, args_obj: dict[str, object]) -> str | None:
+    """Return the concrete adapter id represented by a root or direct tool call."""
+    tool_id = fname if fname not in _ROOT_PRIMITIVE_TOOL_NAMES else args_obj.get("tool_id")
+    if isinstance(tool_id, str) and tool_id:
+        return tool_id
+    params = args_obj.get("params")
+    if isinstance(params, dict):
+        nested_tool_id = params.get("tool_id")
+        if isinstance(nested_tool_id, str) and nested_tool_id:
+            return nested_tool_id
+    return 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,
+            "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,
+            "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,
+            "air_quality",
+            "use AirKorea city/province air-quality evidence with sido_name such as '부산'.",
+        )
+    if _TAGO_BUS_USER_QUERY_RE.search(user_query):
+        preferred = (
+            "tago_bus_route_search"
+            if _TAGO_ROUTE_NO_RE.search(user_query)
+            else "tago_bus_station_search"
+        )
+        return (
+            _TAGO_TOOL_IDS,
+            preferred,
+            "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",
+            "current_weather",
+            "use location resolution first when coordinates are missing, then "
+            "KMA current observation evidence for rain/umbrella/current-weather values.",
+        )
+    return None
+
+
+def _check_direct_public_data_tool_choice_prerequisite(
+    fname: str,
+    args_obj: dict[str, object],
+    user_query: str,
+) -> tuple[str, str] | None:
+    """Reject concrete public-data adapters that do not match the latest citizen request."""
+    target = _direct_public_data_target_for_query(user_query)
+    if target is None:
+        return None
+    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: "
+        f"target={route_label}. The latest citizen request needs that route; "
+        f"the previous tool choice does not match. RECOVERY: {hint}",
+    )
+
+
+def _check_kma_aviation_tool_choice_prerequisite(
+    fname: str,
+    args_obj: dict[str, object],
+    user_query: str,
+) -> str | None:
+    """Reject ordinary weather/location tools for airport aviation wording."""
+    if not (
+        _KMA_AIRPORT_PLACE_RE.search(user_query) and _KMA_AIRPORT_AVIATION_RE.search(user_query)
+    ):
+        return None
+    tool_id = _emitted_tool_id(fname, args_obj)
+    if tool_id in _KMA_AIR_TOOL_IDS:
+        return None
+    if tool_id is None:
+        return None
+    return (
+        "KMA aviation tool-choice mismatch: the latest citizen request asks for "
+        "airport METAR/AMOS aviation evidence such as flight operation, wind, "
+        "runway, RVR, or visibility. RECOVERY: call find with tool_id "
+        "kma_apihub_url_air_metar_decoded for airport METAR/시정/풍향/풍속 "
+        "evidence, or kma_apihub_url_air_amos_minute for documented AMOS "
+        "runway-minute evidence. Do not call locate or ordinary KMA current "
+        "observation before the aviation adapter."
+    )
+
+
+def _preferred_kma_aviation_tool_id(user_query: str) -> str:
+    """Return the aviation adapter that best matches the airport wording."""
+    if re.search(r"(김포|gimpo|rkss)", user_query, re.IGNORECASE) and re.search(
+        r"(amos|활주로|rvr|runway|매분)", user_query, re.IGNORECASE
+    ):
+        return "kma_apihub_url_air_amos_minute"
+    return "kma_apihub_url_air_metar_decoded"
+
+
 _CURRENT_WEATHER_KEYWORDS_KO: frozenset[str] = frozenset(
     {"날씨", "기온", "온도", "습도", "강수", "바람", "풍속"}
 )
@@ -3918,6 +5206,17 @@ _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"숨[을 ]*(?:안|못)|호흡[이가은는 ]*없|자동심장|심장충격|제세동|"
+    r"\bAED\b|collapsed|unconscious|cardiac arrest|not breathing)",
+    re.IGNORECASE,
+)
+_CIVIL_SAFETY_CALL_BOX_RE: Final = re.compile(
+    r"(비상벨|안심벨|비상\s*호출|긴급\s*호출|emergency\s*bell|call\s*box)",
+    re.IGNORECASE,
+)
 
 
 def _latest_available_adapters_block(llm_messages: list[Any]) -> str:
@@ -3942,7 +5241,40 @@ 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:
+    """Return True when the latest dynamic adapter block surfaced tool_id."""
+    if not block or not tool_id:
+        return False
+    escaped = re.escape(tool_id)
+    line_re = re.compile(rf"^\s*-\s*{escaped}(?:\s|\(|:)", re.MULTILINE)
+    yaml_re = re.compile(rf"^\s*tool_id:\s*{escaped}\s*$", re.MULTILINE)
+    return bool(line_re.search(block) or yaml_re.search(block) or f"tool_id: {tool_id}" in block)
+
+
+def _query_implies_medical_collapse_aed(user_query: str) -> bool:
+    """Return True for medical collapse/cardiac-arrest wording that needs AED data."""
+    if not user_query:
+        return False
+    if _CIVIL_SAFETY_CALL_BOX_RE.search(user_query):
+        return False
+    return _MEDICAL_COLLAPSE_RE.search(user_query) is not None
 
 
 def _query_implies_current_weather_observation(user_query: str) -> bool:
@@ -4008,6 +5340,47 @@ def _check_current_weather_terminated_without_observation(
     )
 
 
+def _check_medical_emergency_terminated_without_aed(
+    llm_messages: list[Any],
+    user_query: str,
+    registry: Any = None,
+) -> str | None:
+    """Require AED search before final prose for collapse/cardiac-arrest wording."""
+    if not _query_implies_medical_collapse_aed(user_query):
+        return None
+    available_adapters_block = _latest_available_adapters_block(llm_messages)
+    if not _available_adapters_block_has_tool_id(
+        available_adapters_block,
+        "nmc_aed_site_locate",
+    ):
+        return None
+    if _conversation_has_primitive_call(
+        llm_messages,
+        primitive="find",
+        tool_id="nmc_aed_site_locate",
+    ):
+        return None
+    if not _conversation_has_successful_primitive(
+        llm_messages,
+        primitive="find",
+        tool_id="nmc_emergency_search",
+    ):
+        return None
+    return (
+        "Medical emergency chain incomplete: the citizen described a collapse, "
+        "unconsciousness, cardiac arrest, or AED-relevant situation. The "
+        "conversation already found emergency-room data but is about to answer "
+        "without attempting the AED adapter that was surfaced in "
+        "<available_adapters>. RECOVERY: call "
+        "nmc_aed_site_locate({q0:<region from locate or NMC context>, "
+        "q1:<district when available>, limit:5}) or the equivalent schema-valid "
+        "parameters before final prose. If the AED adapter returns no data or an "
+        "upstream error, report that result explicitly alongside 119/emergency-room "
+        "guidance. Do NOT substitute emergency-room data for AED data. Do NOT "
+        "produce a final answer this turn."
+    )
+
+
 def _weather_value_tokens(value: object) -> set[str]:
     """Return compact numeric strings a final weather answer may cite."""
     if isinstance(value, bool):
@@ -4401,8 +5774,8 @@ async def run(  # noqa: C901
 
     # ---- spec-multi-turn-contamination diagnostic — optional log file
     # The TUI bridge spawns this process with `stderr: 'pipe'` and never
-    # drains the pipe, so `logger.info(...)` lines are invisible to any
-    # external observer (tmux pane, asciinema cast). When the operator
+    # drains the pipe, so `logger.info(...)` lines are invisible to the
+    # normal terminal transcript. When the operator
     # sets UMMAYA_BACKEND_LOG_FILE=<path>, attach a FileHandler at INFO
     # so the diagnostic [CHAT_REQUEST_DUMP] / [LATEST_USER_UTT] /
     # [REASONING_PREVIEW] lines persist to disk for post-hoc analysis.
@@ -4423,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(
@@ -4555,6 +5929,8 @@ async def run(  # noqa: C901
     _session_auth_contexts: dict[str, object] = {}
     _session_auth_session_ids: dict[str, str] = {}
     _session_latest_locate_results: dict[str, dict[str, object]] = {}
+    _session_latest_locate_results_with_coords: dict[str, dict[str, object]] = {}
+    _session_latest_user_utterances: dict[str, str] = {}
 
     # Epic #2077 T010 — single ToolRegistry + ToolExecutor instance pair
     # reused across every chat_request. Adapter registration happens lazily
@@ -4634,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
@@ -4798,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 _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) -> str:  # noqa: C901
+    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.
@@ -4859,212 +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 ""
-        # 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 '(설명 없음)'}"
-            )
-            # 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 at most 300 chars — enough for the ORDERING RULE and
-                # worked example without blowing the per-turn token budget.
-                if len(desc_text) > 300:
-                    desc_text = desc_text[:297] + "..."
-                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는 이미 model-facing concrete function name입니다. "
-            "루트 wrapper find/locate/check/send 를 호출하지 말고, 해당 tool_id 이름의 "
-            "함수를 직접 호출하세요. 인자는 schema 의 필드명 그대로 전달합니다. "
-            "동일 tool_id 를 한 turn 안에서 반복 호출하지 마세요."
-        )
-        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 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
@@ -5514,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:
@@ -5547,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
@@ -5575,12 +6803,49 @@ 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,
                     )
                     from ummaya.tools.verify_canonical_map import (  # noqa: PLC0415
                         resolve_family,
+                        resolve_tool_id,
                     )
 
                     # Spec 2297 / Issue #C1 (2026-05-04) — translate
@@ -5595,7 +6860,11 @@ async def run(  # noqa: C901
                     # Accept both ``family`` (citizen-facing tool schema) and
                     # ``family_hint`` (primitive's internal arg name) for
                     # legacy / tools-bridge compatibility.
-                    tool_id = str(args_obj.get("tool_id") or "")
+                    raw_tool_id = str(args_obj.get("tool_id") or "")
+                    canonical_tool_id = resolve_tool_id(raw_tool_id) or raw_tool_id
+                    if canonical_tool_id != raw_tool_id:
+                        args_obj = {**args_obj, "tool_id": canonical_tool_id}
+                    tool_id = canonical_tool_id
                     if tool_id:
                         registry = _ensure_tool_registry()
                         try:
@@ -5643,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(
@@ -5656,7 +6933,8 @@ async def run(  # noqa: C901
                             message=(
                                 "find(mode='search') 는 백엔드 internal 기능입니다 — "
                                 "직접 호출하지 마십시오. 시스템 프롬프트의 "
-                                "<available_adapters> 에서 tool_id 를 골라 fetch 호출만 사용하세요."
+                                "<available_adapters> 에서 concrete adapter function을 "
+                                "골라 schema 필드로 직접 호출하세요."
                             ),
                             retryable=False,
                         )
@@ -5682,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),
@@ -5813,6 +7105,8 @@ async def run(  # noqa: C901
                 locate_result = result_payload.get("result")
                 if isinstance(locate_result, dict) and locate_result.get("kind") != "error":
                     _session_latest_locate_results[session_id] = locate_result
+                    if _locate_result_coords(locate_result) is not None:
+                        _session_latest_locate_results_with_coords[session_id] = locate_result
 
             # Drain the outbound HTTP trace buffer + attach to the envelope.
             outbound_traces = consume_outbound_capture(_outbound_trace_token)
@@ -5900,6 +7194,29 @@ async def run(  # noqa: C901
         if not isinstance(frame, ChatRequestFrame):
             return
 
+        async def _emit_progress_event(
+            phase: Literal[
+                "analysis",
+                "tool_selection",
+                "tool_call",
+                "tool_result",
+                "answer_synthesis",
+            ],
+            message_ko: str,
+            message_en: str,
+            *,
+            tool_id: str | None = None,
+            call_id: str | None = None,
+        ) -> None:
+            _ = (phase, message_ko, message_en, tool_id, call_id)
+            return
+
+        await _emit_progress_event(
+            "analysis",
+            "요청을 분석하고 있습니다.",
+            "Analyzing the request.",
+        )
+
         # ---- spec-multi-turn-contamination diagnostic emit (FR-001/FR-002)
         # Increment the per-session turn counter and dump the inbound
         # ChatRequestFrame.messages tail so we can prove which user turn
@@ -5942,11 +7259,9 @@ async def run(  # noqa: C901
             except Exception:  # noqa: BLE001 — diagnostic must never raise
                 logger.exception("[CHAT_REQUEST_DUMP] failed to serialise")
 
-        latest_user_utt = ""
-        for _msg in reversed(frame.messages):
-            if _msg.role == "user" and _msg.content:
-                latest_user_utt = _msg.content
-                break
+        latest_user_utt = _latest_citizen_user_utterance(frame.messages)
+        if latest_user_utt:
+            _session_latest_user_utterances[frame.session_id] = latest_user_utt
 
         # Tool inventory — backend ToolRegistry is the single source of
         # truth. CC exposes concrete Tool objects as model-facing functions:
@@ -5958,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):
@@ -5971,6 +7300,11 @@ async def run(  # noqa: C901
         llm_tools: list[LLMToolDefinition] = [
             LLMToolDefinition.model_validate(raw) for raw in backend_tools_raw
         ]
+        await _emit_progress_event(
+            "tool_selection",
+            "도구 후보와 질의 맥락을 정리하고 있습니다.",
+            "Preparing tool candidates and query context.",
+        )
         has_concrete_backend_tools = bool(backend_tools_raw)
         for t in frame.tools:
             tui_name = getattr(getattr(t, "function", None), "name", None)
@@ -6073,10 +7407,9 @@ async def run(  # noqa: C901
             # calls were the source of the "● find(search:)" phantom tool-UI
             # noise that user surfaced via Layer 5 frame capture.
             try:
-                for m in reversed(frame.messages):
-                    if m.role == "user" and m.content:
-                        latest_user_utt = m.content
-                        break
+                latest_user_utt = _latest_citizen_user_utterance(frame.messages)
+                if latest_user_utt:
+                    _session_latest_user_utterances[frame.session_id] = latest_user_utt
                 # spec-multi-turn-contamination diagnostic emit — log the
                 # extracted latest user utterance BEFORE the BM25 suffix
                 # builder runs. If this string disagrees with the wire-level
@@ -6090,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
@@ -6163,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
@@ -6170,6 +7508,10 @@ async def run(  # noqa: C901
         verify_choice_mismatch_count = 0
         empty_final_retry_count = 0
         duplicate_nonprogress_count = 0
+        initial_concrete_tool_choice = _initial_concrete_tool_choice_for_query(
+            latest_user_utt,
+            _tool_definition_names(llm_tools),
+        )
 
         for _turn in range(_AGENTIC_LOOP_MAX_TURNS):
             message_id = str(uuid.uuid4())
@@ -6274,29 +7616,88 @@ async def run(  # noqa: C901
                 stream_tools = None
                 no_tools_this_turn = True
                 force_no_tools_next_turn = False
+            elif (
+                initial_concrete_tool_choice is not None
+                and initial_concrete_tool_choice in _tool_definition_names(stream_tools)
+            ):
+                stream_tool_choice = _function_tool_choice(initial_concrete_tool_choice)
+                logger.warning(
+                    "_handle_chat_request: forcing initial concrete adapter %s "
+                    "for unambiguous query",
+                    initial_concrete_tool_choice,
+                )
+                initial_concrete_tool_choice = None
+            elif (
+                force_lookup_next_turn is not None
+                and force_lookup_next_turn in _tool_definition_names(stream_tools)
+            ):
+                stream_tool_choice = _function_tool_choice(force_lookup_next_turn)
+                logger.warning(
+                    "_handle_chat_request: forcing concrete find adapter %s after validation gate",
+                    force_lookup_next_turn,
+                )
+                force_lookup_next_turn = None
+            elif (
+                force_verify_next_turn is not None
+                and force_verify_next_turn in _tool_definition_names(stream_tools)
+            ):
+                stream_tool_choice = _function_tool_choice(force_verify_next_turn)
+                logger.warning(
+                    "_handle_chat_request: forcing concrete check adapter %s after validation gate",
+                    force_verify_next_turn,
+                )
+                force_verify_next_turn = None
+            elif (
+                force_submit_next_turn is not None
+                and force_submit_next_turn in _tool_definition_names(stream_tools)
+            ):
+                stream_tool_choice = _function_tool_choice(force_submit_next_turn)
+                logger.warning(
+                    "_handle_chat_request: forcing concrete send adapter %s after validation gate",
+                    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] = {
+                    "messages": llm_messages,
+                    "tools": stream_tools,
+                    "temperature": frame.temperature,
+                    "top_p": frame.top_p,
+                    "max_tokens": _effective_chat_max_tokens(frame.max_tokens),
+                    "tool_choice": stream_tool_choice,
+                }
+                if frame.reasoning_mode is not None:
+                    stream_kwargs["reasoning_mode"] = frame.reasoning_mode
                 async for event in client.stream(  # type: ignore[attr-defined]
-                    messages=llm_messages,
-                    tools=stream_tools,
-                    temperature=frame.temperature,
-                    top_p=frame.top_p,
-                    max_tokens=_effective_chat_max_tokens(frame.max_tokens),
-                    tool_choice=stream_tool_choice,
+                    **stream_kwargs,
                 ):
                     event_type = getattr(event, "type", None)
                     if event_type == "content_delta":
@@ -6553,6 +7954,19 @@ async def run(  # noqa: C901
                     buffered_visible.clear()
                     continue
 
+                medical_aed_followup_msg = _check_medical_emergency_terminated_without_aed(
+                    llm_messages,
+                    latest_user_utt,
+                    registry=_ensure_tool_registry(),
+                )
+                if medical_aed_followup_msg is not None:
+                    _append_tool_routing_observation(
+                        "rejected final-answer turn — collapse emergency missing AED lookup",
+                        medical_aed_followup_msg,
+                    )
+                    buffered_visible.clear()
+                    continue
+
                 current_weather_gate_msg = _check_current_weather_terminated_without_observation(
                     llm_messages,
                     latest_user_utt,
@@ -6566,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,
                 )
@@ -6579,9 +8024,106 @@ 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)
+                    and empty_final_retry_count < 2
+                ):
+                    empty_final_retry_count += 1
+                    _append_tool_routing_observation(
+                        "rejected textual tool-call final answer",
+                        (
+                            "The previous assistant turn printed <tool_call> or JSON "
+                            "tool-call text as citizen-facing prose. Never print tool "
+                            "calls. If another lookup is required, emit a structured "
+                            "function call from the current tools[] list. If enough "
+                            "evidence is already available, write a Korean prose final "
+                            "answer only."
+                        ),
+                    )
+                    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
@@ -6633,6 +8175,59 @@ async def run(  # noqa: C901
                     )
                     buffered_visible.clear()
                     continue
+                if (
+                    merged_prose.strip()
+                    and _final_answer_looks_like_kma_analysis_fabrication(
+                        merged_prose,
+                        latest_user_utt,
+                    )
+                    and empty_final_retry_count < 2
+                ):
+                    empty_final_retry_count += 1
+                    _append_final_answer_observation(
+                        "rejected KMA analysis final answer filled from general knowledge",
+                        (
+                            "The citizen asked for KMA analyzed-data evidence. The "
+                            "previous assistant turn described failed, empty, or "
+                            "unparseable KMA APIHub analysis lookups, then filled the "
+                            "weather answer with general knowledge. Do not fill gaps "
+                            "from prior knowledge. If the successful tool_results do "
+                            "not contain parseable analyzed values for the request, "
+                            "answer that the KMA APIHub lookup did not provide usable "
+                            "analyzed data in this run, cite the APIHub upstream/approval "
+                            "failure when present, and avoid weather-condition claims."
+                        ),
+                    )
+                    buffered_visible.clear()
+                    continue
+                if (
+                    merged_prose.strip()
+                    and _final_answer_substitutes_after_kma_chart_failure(
+                        merged_prose,
+                        latest_user_utt,
+                        llm_messages,
+                    )
+                    and empty_final_retry_count < 2
+                ):
+                    empty_final_retry_count += 1
+                    _append_final_answer_observation(
+                        (
+                            "rejected KMA chart answer substituted non-chart "
+                            "evidence after upstream failure"
+                        ),
+                        (
+                            "The citizen asked for analyzed weather-chart/map evidence. "
+                            "The KMA APIHub chart lookup failed or required approval, "
+                            "and the previous assistant answer substituted point-grid, "
+                            "AWS objective-analysis, or observation values. Do not "
+                            "substitute other evidence for this chart/map request. "
+                            "Answer that the KMA APIHub analyzed chart lookup could "
+                            "not be used in this run, cite the upstream approval/error "
+                            "state, and avoid weather-condition claims."
+                        ),
+                    )
+                    buffered_visible.clear()
+                    continue
                 if (
                     merged_prose.strip()
                     and has_successful_tool_result
@@ -6852,6 +8447,7 @@ async def run(  # noqa: C901
 
                 model_tool_name = slot["name"]
                 model_args_obj = dict(args_obj)
+                canonical_model_tool_name = model_tool_name
 
                 from ummaya.primitives import PRIMITIVE_REGISTRY  # noqa: PLC0415
 
@@ -6859,8 +8455,15 @@ async def run(  # noqa: C901
                     fname = model_tool_name
                     args_obj = dict(model_args_obj)
                 else:
+                    from ummaya.tools.verify_canonical_map import (  # noqa: PLC0415
+                        resolve_tool_id as _resolve_verify_tool_id,
+                    )
+
+                    canonical_model_tool_name = (
+                        _resolve_verify_tool_id(model_tool_name) or model_tool_name
+                    )
                     try:
-                        concrete_tool = registry.find(model_tool_name)
+                        concrete_tool = registry.find(canonical_model_tool_name)
                     except Exception:
                         await write_frame(
                             ErrorFrame(
@@ -6894,8 +8497,12 @@ async def run(  # noqa: C901
                         )
                         continue
                     fname = primitive_name
-                    args_obj = {"tool_id": model_tool_name, "params": dict(model_args_obj)}
+                    args_obj = {
+                        "tool_id": canonical_model_tool_name,
+                        "params": dict(model_args_obj),
+                    }
 
+                args_obj = _normalize_root_primitive_adapter_envelope(fname, args_obj)
                 raw_dispatch_args_obj = _copy_primitive_args(args_obj)
 
                 args_obj = _maybe_reroute_locate_admin_keyword_args(fname, args_obj)
@@ -6944,10 +8551,12 @@ async def run(  # noqa: C901
                         latest_user_utt,
                         adapter_param_names=adapter_param_names,
                     )
-                emit_tool_name = model_tool_name
+                emit_tool_name = (
+                    canonical_model_tool_name if model_tool_name != fname else model_tool_name
+                )
                 emit_args_obj = (
                     dict(cast("dict[str, object]", args_obj.get("params") or {}))
-                    if model_tool_name != fname
+                    if emit_tool_name != fname
                     else args_obj
                 )
 
@@ -6986,6 +8595,13 @@ async def run(  # noqa: C901
                     )
 
                     await _emit_buffered_visible_before_tool(message_id)
+                    await _emit_progress_event(
+                        "tool_call",
+                        "선택된 도구를 호출하고 있습니다.",
+                        "Calling the selected tool.",
+                        tool_id=emit_tool_name,
+                        call_id=call_id,
+                    )
                     await write_frame(
                         ToolCallFrame(
                             session_id=frame.session_id,
@@ -7114,6 +8730,43 @@ async def run(  # noqa: C901
                     continue_free_next_turn = True
                     continue
 
+                kma_aviation_choice_msg = _check_kma_aviation_tool_choice_prerequisite(
+                    fname,
+                    args_obj,
+                    latest_user_utt,
+                )
+                if kma_aviation_choice_msg is not None:
+                    force_lookup_next_turn = _preferred_kma_aviation_tool_id(latest_user_utt)
+                    _append_tool_routing_observation(
+                        f"rejected {fname} call_id={call_id[:12]} — KMA aviation tool mismatch",
+                        kma_aviation_choice_msg,
+                    )
+                    logger.warning(
+                        "_handle_chat_request: rejected %s call_id=%s — KMA aviation tool mismatch",
+                        fname,
+                        call_id[:12],
+                    )
+                    continue
+
+                direct_public_data_choice = _check_direct_public_data_tool_choice_prerequisite(
+                    fname,
+                    args_obj,
+                    latest_user_utt,
+                )
+                if direct_public_data_choice is not None:
+                    preferred_tool_id, direct_public_data_msg = direct_public_data_choice
+                    force_lookup_next_turn = preferred_tool_id
+                    _append_tool_routing_observation(
+                        f"rejected {fname} call_id={call_id[:12]} — public-data tool mismatch",
+                        direct_public_data_msg,
+                    )
+                    logger.warning(
+                        "_handle_chat_request: rejected %s call_id=%s — public-data tool mismatch",
+                        fname,
+                        call_id[:12],
+                    )
+                    continue
+
                 # Chain prerequisite gate — donga-univ-poi-bug Epic #2766.
                 # CC mirror: ``Tool.validateInput?(input, context)`` from
                 # ``.references/claude-code-sourcemap/restored-src/src/Tool.ts:489``
@@ -7132,11 +8785,9 @@ async def run(  # noqa: C901
                 # the coordinates AND no prior turn in llm_messages
                 # invoked locate, that means the LLM guessed
                 # the coordinates from prior knowledge instead of routing
-                # through the canonical resolver. Three live captures
-                # under specs/integration-verification/donga-univ-poi-bug/
-                # showed this exact pattern producing wrong-region
-                # hospital lists. Rejecting here forces the next turn
-                # through locate.
+                # through the canonical resolver. Historical live captures
+                # showed this exact pattern producing wrong-region hospital
+                # lists. Rejecting here forces the next turn through locate.
                 chain_error_msg = _check_chain_prerequisite(
                     fname,
                     args_obj,
@@ -7158,6 +8809,24 @@ async def run(  # noqa: C901
                     force_locate_next_turn = True
                     continue
 
+                kma_analysis_choice_msg = _check_kma_analysis_tool_choice_prerequisite(
+                    fname,
+                    args_obj,
+                    latest_user_utt,
+                )
+                if kma_analysis_choice_msg is not None:
+                    _append_tool_routing_observation(
+                        f"rejected {fname} call_id={call_id[:12]} — KMA analysis tool mismatch",
+                        kma_analysis_choice_msg,
+                    )
+                    logger.warning(
+                        "_handle_chat_request: rejected %s call_id=%s — KMA analysis tool mismatch",
+                        fname,
+                        call_id[:12],
+                    )
+                    continue_free_next_turn = True
+                    continue
+
                 verify_choice_gate = _check_verify_tool_choice_prerequisite(
                     fname,
                     args_obj,
@@ -7170,6 +8839,13 @@ async def run(  # noqa: C901
                     )
 
                     await _emit_buffered_visible_before_tool(message_id)
+                    await _emit_progress_event(
+                        "tool_call",
+                        "선택된 도구를 호출하고 있습니다.",
+                        "Calling the selected tool.",
+                        tool_id=emit_tool_name,
+                        call_id=call_id,
+                    )
                     await write_frame(
                         ToolCallFrame(
                             session_id=frame.session_id,
@@ -7326,6 +9002,13 @@ async def run(  # noqa: C901
                     )
 
                     await _emit_buffered_visible_before_tool(message_id)
+                    await _emit_progress_event(
+                        "tool_call",
+                        "선택된 도구를 호출하고 있습니다.",
+                        "Calling the selected tool.",
+                        tool_id=emit_tool_name,
+                        call_id=call_id,
+                    )
                     await write_frame(
                         ToolCallFrame(
                             session_id=frame.session_id,
@@ -7404,6 +9087,13 @@ async def run(  # noqa: C901
                     continue
 
                 await _emit_buffered_visible_before_tool(message_id)
+                await _emit_progress_event(
+                    "tool_call",
+                    "선택된 도구를 호출하고 있습니다.",
+                    "Calling the selected tool.",
+                    tool_id=emit_tool_name,
+                    call_id=call_id,
+                )
                 await write_frame(
                     ToolCallFrame(
                         session_id=frame.session_id,
@@ -7429,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:
@@ -7730,7 +9421,7 @@ async def run(  # noqa: C901
         if not fut.done():
             fut.set_result(frame)
 
-    async def _handle_tool_call(frame: IPCFrame) -> None:
+    async def _handle_tool_call(frame: IPCFrame) -> None:  # noqa: C901
         """Execute a TUI-owned Tool.call request and emit a tool_result frame.
 
         Claude Code's query loop, not the provider, owns tool execution. The
@@ -7754,8 +9445,13 @@ async def run(  # noqa: C901
         dispatch_name = frame.name
         dispatch_args = args_obj
         if dispatch_name not in PRIMITIVE_REGISTRY:
+            from ummaya.tools.verify_canonical_map import (  # noqa: PLC0415
+                resolve_tool_id as _resolve_verify_tool_id,
+            )
+
+            canonical_dispatch_name = _resolve_verify_tool_id(dispatch_name) or dispatch_name
             try:
-                concrete_tool = _ensure_tool_registry().find(dispatch_name)
+                concrete_tool = _ensure_tool_registry().find(canonical_dispatch_name)
             except Exception:
                 from ummaya.ipc.frame_schema import (  # noqa: PLC0415
                     ToolResultEnvelope,
@@ -7811,13 +9507,153 @@ async def run(  # noqa: C901
                 )
                 return
             dispatch_name = primitive_name
-            dispatch_args = {"tool_id": frame.name, "params": dict(args_obj)}
+            dispatch_args = {"tool_id": canonical_dispatch_name, "params": dict(args_obj)}
 
         dispatch_args = _normalize_lookup_args_from_cached_locate_result(
             dispatch_name,
             dispatch_args,
             _session_latest_locate_results.get(frame.session_id),
+            coordinate_locate_result=_session_latest_locate_results_with_coords.get(
+                frame.session_id
+            ),
+            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,
+            lookup_context,
+        )
+
+        kma_aviation_choice_msg = _check_kma_aviation_tool_choice_prerequisite(
+            dispatch_name,
+            dispatch_args,
+            _session_latest_user_utterances.get(frame.session_id, ""),
+        )
+        if kma_aviation_choice_msg is not None:
+            from ummaya.ipc.frame_schema import (  # noqa: PLC0415
+                ToolResultEnvelope,
+                ToolResultFrame,
+            )
+
+            envelope = ToolResultEnvelope.model_validate(
+                {
+                    "kind": cast("Any", dispatch_name),
+                    "result": {
+                        "kind": "error",
+                        "reason": "kma_aviation_tool_choice_mismatch",
+                        "message": kma_aviation_choice_msg,
+                        "retryable": False,
+                    },
+                }
+            )
+            result_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=envelope,
+            )
+            await write_frame(result_frame)
+            fut = _pending_calls.pop(frame.call_id, None)
+            if fut is not None and not fut.done():
+                fut.set_result(result_frame)
+            logger.warning(
+                "_handle_tool_call: rejected %s call_id=%s — KMA aviation tool mismatch",
+                dispatch_name,
+                frame.call_id[:12],
+            )
+            return
+
+        direct_public_data_choice = _check_direct_public_data_tool_choice_prerequisite(
+            dispatch_name,
+            dispatch_args,
+            _session_latest_user_utterances.get(frame.session_id, ""),
+        )
+        if direct_public_data_choice is not None:
+            from ummaya.ipc.frame_schema import (  # noqa: PLC0415
+                ToolResultEnvelope,
+                ToolResultFrame,
+            )
+
+            _preferred_tool_id, direct_public_data_msg = direct_public_data_choice
+            envelope = ToolResultEnvelope.model_validate(
+                {
+                    "kind": cast("Any", dispatch_name),
+                    "result": {
+                        "kind": "error",
+                        "reason": "public_data_tool_choice_mismatch",
+                        "message": direct_public_data_msg,
+                        "retryable": False,
+                    },
+                }
+            )
+            result_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=envelope,
+            )
+            await write_frame(result_frame)
+            fut = _pending_calls.pop(frame.call_id, None)
+            if fut is not None and not fut.done():
+                fut.set_result(result_frame)
+            logger.warning(
+                "_handle_tool_call: rejected %s call_id=%s — public-data tool mismatch",
+                dispatch_name,
+                frame.call_id[:12],
+            )
+            return
+
+        kma_analysis_choice_msg = _check_kma_analysis_tool_choice_prerequisite(
+            dispatch_name,
+            dispatch_args,
+            _session_latest_user_utterances.get(frame.session_id, ""),
         )
+        if kma_analysis_choice_msg is not None:
+            from ummaya.ipc.frame_schema import (  # noqa: PLC0415
+                ToolResultEnvelope,
+                ToolResultFrame,
+            )
+
+            envelope = ToolResultEnvelope.model_validate(
+                {
+                    "kind": cast("Any", dispatch_name),
+                    "result": {
+                        "kind": "error",
+                        "reason": "kma_analysis_tool_choice_mismatch",
+                        "message": kma_analysis_choice_msg,
+                        "retryable": False,
+                    },
+                }
+            )
+            result_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=envelope,
+            )
+            await write_frame(result_frame)
+            fut = _pending_calls.pop(frame.call_id, None)
+            if fut is not None and not fut.done():
+                fut.set_result(result_frame)
+            logger.warning(
+                "_handle_tool_call: rejected %s call_id=%s — KMA analysis tool mismatch",
+                dispatch_name,
+                frame.call_id[:12],
+            )
+            return
 
         await _dispatch_primitive(
             frame.call_id,
@@ -7912,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.