ummaya 0.2.4 → 0.2.5

package/src/ummaya/evidence/source_provenance_redaction.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Literal
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+RedactionCategory = Literal[
+    "auth_header",
+    "cookie",
+    "service_key",
+    "token",
+    "pii",
+    "private_document",
+]
+PromptInjectionState = Literal["detected", "not_detected"]
+
+_AUTH_HEADER_PATTERN = re.compile(r"\bAuthorization\s*:\s*[^\n\r;]+", re.IGNORECASE)
+_AUTH_ASSIGNMENT_PATTERN = re.compile(
+    r"\bauthorization\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_COOKIE_PATTERN = re.compile(r"\bCookie\s*:\s*[^;\n\r]+;?\s*", re.IGNORECASE)
+_COOKIE_ASSIGNMENT_PATTERN = re.compile(
+    r"\bcookie\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_SERVICE_KEY_PATTERN = re.compile(
+    r"\b(?:serviceKey|authKey)\s*=\s*[^\s&]+",
+    re.IGNORECASE,
+)
+_TOKEN_PATTERN = re.compile(
+    r"\b(?:UMMAYA_[A-Z0-9_]*TOKEN|"
+    r"[A-Z0-9_]*(?:API|AUTH|ACCESS|REFRESH|SESSION)[_-]?KEY|"
+    r"(?:session|access|refresh|id)[_-]?token)\s*=\s*[^\s&]+|"
+    r"\bBearer\s+[A-Za-z0-9._~+/=-]+",
+    re.IGNORECASE,
+)
+_GENERIC_TOKEN_ASSIGNMENT_PATTERN = re.compile(
+    r"\b(?:token|secret|api[_-]?key|access[_-]?token|session[_-]?token|"
+    r"refresh[_-]?token|id[_-]?token|client[_-]?secret)\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_EMAIL_PATTERN = re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE)
+_KOREAN_RRN_PATTERN = re.compile(r"\b\d{6}-[1-4]\d{6}\b")
+_PHONE_PATTERN = re.compile(r"\b01[016789]-?\d{3,4}-?\d{4}\b")
+_PRIVATE_DOCUMENT_PATTERN = re.compile(
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----|raw private document|private document bytes",
+    re.IGNORECASE,
+)
+_PROMPT_INJECTION_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"ignore\s+(?:all\s+)?previous\s+instructions", re.IGNORECASE),
+    re.compile(r"change\s+(?:the\s+)?permission\s+policy", re.IGNORECASE),
+    re.compile(r"bypass\s+(?:permissions?|approval|policy)", re.IGNORECASE),
+    re.compile(r"treat\s+this\s+as\s+(?:a\s+)?system\s+instruction", re.IGNORECASE),
+)
+_SECRET_QUERY_KEYS = frozenset(
+    {
+        "access_token",
+        "api_key",
+        "apikey",
+        "auth",
+        "authkey",
+        "authorization",
+        "cookie",
+        "id_token",
+        "key",
+        "refresh_token",
+        "servicekey",
+        "session",
+        "session_token",
+        "token",
+    }
+)
+
+
+def redact_source_url(value: str | None) -> tuple[str | None, tuple[RedactionCategory, ...]]:
+    if value is None:
+        return None, ()
+    categories: list[RedactionCategory] = []
+    try:
+        parsed = urlsplit(value)
+    except ValueError:
+        return redact_source_text(value)
+    query_items: list[tuple[str, str]] = []
+    for key, item_value in parse_qsl(parsed.query, keep_blank_values=True):
+        lowered_key = key.lower()
+        if lowered_key in _SECRET_QUERY_KEYS:
+            categories.append(
+                "service_key" if lowered_key in {"authkey", "servicekey"} else "token"
+            )
+            continue
+        redacted_value, item_categories = redact_source_text(item_value)
+        categories.extend(item_categories)
+        query_items.append((key, redacted_value or ""))
+    rebuilt = urlunsplit(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            urlencode(query_items),
+            parsed.fragment,
+        )
+    )
+    redacted_text, text_categories = redact_source_text(rebuilt)
+    categories.extend(text_categories)
+    return redacted_text, ordered_redaction_categories(categories)
+
+
+def redact_source_text(value: str | None) -> tuple[str | None, tuple[RedactionCategory, ...]]:
+    if value is None:
+        return None, ()
+    categories = list(redaction_categories_for_text(value))
+    redacted = _AUTH_HEADER_PATTERN.sub("[REDACTED_AUTH_HEADER]", value)
+    redacted = _AUTH_ASSIGNMENT_PATTERN.sub("[REDACTED_AUTH_HEADER]", redacted)
+    redacted = _COOKIE_PATTERN.sub("[REDACTED_COOKIE] ", redacted)
+    redacted = _COOKIE_ASSIGNMENT_PATTERN.sub("[REDACTED_COOKIE]", redacted)
+    redacted = _SERVICE_KEY_PATTERN.sub("[REDACTED_SERVICE_KEY]", redacted)
+    redacted = _TOKEN_PATTERN.sub("[REDACTED_TOKEN]", redacted)
+    redacted = _GENERIC_TOKEN_ASSIGNMENT_PATTERN.sub("[REDACTED_TOKEN]", redacted)
+    redacted = _EMAIL_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _KOREAN_RRN_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _PHONE_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _PRIVATE_DOCUMENT_PATTERN.sub("[REDACTED_PRIVATE_DOCUMENT]", redacted)
+    return re.sub(r"[ \t]{2,}", " ", redacted).strip(), ordered_redaction_categories(categories)
+
+
+def detect_prompt_injection(value: str) -> PromptInjectionState:
+    return (
+        "detected"
+        if any(pattern.search(value) for pattern in _PROMPT_INJECTION_PATTERNS)
+        else "not_detected"
+    )
+
+
+def redaction_categories_for_text(value: str) -> tuple[RedactionCategory, ...]:
+    categories: list[RedactionCategory] = []
+    if _AUTH_HEADER_PATTERN.search(value):
+        categories.append("auth_header")
+    if _AUTH_ASSIGNMENT_PATTERN.search(value):
+        categories.append("auth_header")
+    if _COOKIE_PATTERN.search(value):
+        categories.append("cookie")
+    if _COOKIE_ASSIGNMENT_PATTERN.search(value):
+        categories.append("cookie")
+    if _SERVICE_KEY_PATTERN.search(value):
+        categories.append("service_key")
+    if _TOKEN_PATTERN.search(value):
+        categories.append("token")
+    if _GENERIC_TOKEN_ASSIGNMENT_PATTERN.search(value):
+        categories.append("token")
+    if (
+        _EMAIL_PATTERN.search(value)
+        or _KOREAN_RRN_PATTERN.search(value)
+        or _PHONE_PATTERN.search(value)
+    ):
+        categories.append("pii")
+    if _PRIVATE_DOCUMENT_PATTERN.search(value):
+        categories.append("private_document")
+    return ordered_redaction_categories(categories)
+
+
+def ordered_redaction_categories(
+    categories: Iterable[RedactionCategory],
+) -> tuple[RedactionCategory, ...]:
+    order: tuple[RedactionCategory, ...] = (
+        "auth_header",
+        "cookie",
+        "service_key",
+        "token",
+        "pii",
+        "private_document",
+    )
+    present = set(categories)
+    return tuple(category for category in order if category in present)

package/src/ummaya/evidence/tool_layer.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ummaya.evidence.models import RouteTraceRecord
+from ummaya.evidence.tool_layer_models import ToolLayerEvidenceEvent
+
+
+@dataclass(frozen=True, slots=True)
+class ToolLayerEvidenceJoinError(ValueError):
+    """Raised when a tool-layer artifact cannot be joined to route evidence."""
+
+    event_id: str
+
+    def __str__(self) -> str:
+        return f"tool-layer event does not join to route evidence: {self.event_id}"
+
+
+def build_tool_layer_events(
+    route_trace_records: tuple[RouteTraceRecord, ...],
+    *,
+    observed_events: tuple[ToolLayerEvidenceEvent, ...] = (),
+) -> tuple[ToolLayerEvidenceEvent, ...]:
+    """Return validated tool-layer artifacts without synthesizing sample events."""
+
+    if not observed_events:
+        return ()
+
+    route_keys = {
+        (record.scenario_id, record.trace_id, record.correlation_id)
+        for record in route_trace_records
+        if record.trace_kind == "scenario_route"
+    }
+    for event in observed_events:
+        event_key = (event.scenario_id, event.trace_id, event.correlation_id)
+        if event_key not in route_keys:
+            raise ToolLayerEvidenceJoinError(event_id=event.event_id)
+    return observed_events

package/src/ummaya/evidence/tool_layer_models.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tool-layer Evidence Fabric event models."""
+
+from __future__ import annotations
+
+from typing import Literal, Self, assert_never
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic_core import PydanticCustomError
+
+ToolLayerExposureState = Literal[
+    "always-loaded",
+    "deferred-searchable",
+    "permission-gated-callable",
+    "hidden",
+    "unsupported",
+]
+ToolLayerTrustTier = Literal[0, 1, 2, 3, 4, 5]
+ToolLayerPermissionDecision = Literal[
+    "not_required",
+    "approved",
+    "denied",
+    "blocked_pending_approval",
+    "policy_preapproved",
+]
+ToolLayerResultStatus = Literal["succeeded", "failed", "blocked"]
+ToolLayerBlockedState = Literal[
+    "not_blocked",
+    "blocked_by_permission",
+    "blocked_by_policy",
+    "blocked_by_missing_source",
+    "blocked_by_unsupported",
+]
+ToolLayerRenderFrame = Literal[
+    "permission_prompt",
+    "tool_call",
+    "tool_result",
+    "blocked_state",
+]
+ToolLayerPromptInjectionState = Literal["detected", "not_detected"]
+ToolLayerSourceTrust = Literal["trusted", "untrusted"]
+ToolLayerSourceInstructionVisibility = Literal["evidence_only"]
+
+
+def _validation_error(code: str, message: str) -> PydanticCustomError:
+    return PydanticCustomError(code, message)
+
+
+class ToolLayerEvidenceEvent(BaseModel):
+    """One recovered Claude Code support-tool exposure and provenance event."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    event_id: str = Field(min_length=1)
+    scenario_id: str = Field(min_length=1)
+    trace_id: str = Field(min_length=1)
+    correlation_id: str = Field(min_length=1)
+    frame_hash: str = Field(min_length=64, max_length=64)
+    render_frame: ToolLayerRenderFrame
+    selected_tool: str = Field(min_length=1)
+    exposure_state: ToolLayerExposureState
+    trust_tier: ToolLayerTrustTier
+    permission_decision: ToolLayerPermissionDecision
+    source_url: str | None
+    source_local_handle: str | None
+    source_citation_id: str = Field(min_length=1)
+    provenance_id: str = Field(min_length=1)
+    source_trust: ToolLayerSourceTrust
+    source_prompt_injection: ToolLayerPromptInjectionState
+    source_instruction_visibility: ToolLayerSourceInstructionVisibility = "evidence_only"
+    result_status: ToolLayerResultStatus
+    result_summary: str | None
+    error_summary: str | None
+    blocked_state: ToolLayerBlockedState
+
+    @field_validator("frame_hash")
+    @classmethod
+    def _validate_frame_hash(cls, value: str) -> str:
+        if len(value) != 64 or any(ch not in "0123456789abcdef" for ch in value):
+            raise _validation_error(
+                "tool_layer_frame_hash", "frame_hash must be lowercase SHA-256 hex"
+            )
+        return value
+
+    @field_validator("source_url", "source_local_handle", "source_citation_id", "provenance_id")
+    @classmethod
+    def _reject_model_visible_leakage_keys(cls, value: str | None) -> str | None:
+        if value is not None and ("adapter_id" in value or "expected_tool" in value):
+            raise _validation_error(
+                "tool_layer_model_visible_leakage",
+                "tool-layer evidence cannot carry model-visible leakage keys",
+            )
+        return value
+
+    @field_validator("result_summary", "error_summary")
+    @classmethod
+    def _reject_empty_summary(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise _validation_error(
+                "tool_layer_blank_summary", "tool-layer summaries cannot be blank"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _requires_source_reference(self) -> Self:
+        if self.source_url is None and self.source_local_handle is None:
+            raise _validation_error(
+                "tool_layer_missing_source",
+                "tool-layer evidence requires source_url or source_local_handle",
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _requires_status_payload(self) -> Self:
+        match self.result_status:
+            case "succeeded":
+                if self.result_summary is None:
+                    raise _validation_error(
+                        "tool_layer_missing_result_summary",
+                        "succeeded tool-layer event requires result_summary",
+                    )
+                if self.error_summary is not None:
+                    raise _validation_error(
+                        "tool_layer_unexpected_error_summary",
+                        "succeeded tool-layer event cannot carry error_summary",
+                    )
+                if self.blocked_state != "not_blocked":
+                    raise _validation_error(
+                        "tool_layer_unexpected_blocked_state",
+                        "succeeded tool-layer event must not be blocked",
+                    )
+            case "failed":
+                if self.error_summary is None:
+                    raise _validation_error(
+                        "tool_layer_failed_without_error",
+                        "failed tool-layer event requires error_summary",
+                    )
+            case "blocked":
+                if self.error_summary is None:
+                    raise _validation_error(
+                        "tool_layer_blocked_without_error",
+                        "blocked tool-layer event requires error_summary",
+                    )
+                if self.blocked_state == "not_blocked":
+                    raise _validation_error(
+                        "tool_layer_blocked_without_state",
+                        "blocked tool-layer event requires a blocked_state",
+                    )
+            case unreachable:
+                assert_never(unreachable)
+        return self

package/src/ummaya/ipc/adapter_manifest_emitter.py

@@ -47,6 +47,7 @@ import importlib
 import json
 import logging
 import os
+import re
 from datetime import UTC, datetime
 from typing import IO, Any, Literal
 
@@ -255,7 +256,7 @@ def _build_entries(  # noqa: C901, ANN401 — three-source walker, refactor defe
     except Exception:
         tools_list = []
 
-    root_primitive_tool_ids = frozenset({"locate", "find", "check", "send"})
+    root_primitive_tool_ids = frozenset({"locate", "find", "check", "send", "document"})
 
     for tool in tools_list:
         tool_id_opt: str | None = tool.id if hasattr(tool, "id") else getattr(tool, "tool_id", None)
@@ -371,24 +372,39 @@ def _verify_family_llm_description(
     """Build model-facing prose for a verify-family manifest entry."""
 
     metadata = metadata or {}
-    tool_id = str(metadata.get("tool_id") or family).strip()
     name = str(metadata.get("name_ko") or family).strip()
-    scope_rules = str(metadata.get("scope_rules") or "").strip()
+    scope_rules = _safe_verify_scope_rules(str(metadata.get("scope_rules") or "").strip())
     scope_clause = f" {scope_rules}" if scope_rules else ""
     return (
-        f"Internal check-family surface for {name} (family_hint='{family}', "
-        f"bridged adapter id '{tool_id}'). Use this only through the core check "
-        "primitive before a downstream protected find/send action needs delegated "
-        "authorization. Params must follow input_schema_json exactly: scope_list "
-        "contains '<verb>:<adapter_family>.<action>' scope strings, purpose_ko is "
-        "the Korean citizen-facing consent purpose, and purpose_en is the audit-log "
+        f"Internal check-family surface for {name} (family_hint='{family}'). "
+        "Use this only through the core check primitive before a downstream "
+        "protected find/send action needs delegated authorization. Params must "
+        "follow input_schema_json exactly: scope_list contains "
+        "'<verb>:<adapter_family>.<action>' scope strings, purpose_ko is the "
+        "Korean citizen-facing consent purpose, and purpose_en is the audit-log "
         "English purpose. The manifest entry stays source_mode='internal' because "
         "the agency citation is emitted by the verify response transparency stamp, "
-        "while the pre-call tool schema remains stable for the TUI and LLM loop."
+        "while the pre-call tool schema remains stable for the TUI and LLM loop. "
+        "Do not mention internal mock bridge identifiers in citizen-facing prose."
         f"{scope_clause}"
     )
 
 
+def _safe_verify_scope_rules(scope_rules: str) -> str:
+    if not scope_rules:
+        return ""
+    safe_sentences: list[str] = []
+    for sentence in re.split(r"(?<=[.!?])\s+", scope_rules):
+        candidate = sentence.strip()
+        if not candidate:
+            continue
+        lowered = candidate.lower()
+        if "mock_verify" in lowered or "tool_id" in lowered:
+            continue
+        safe_sentences.append(candidate)
+    return " ".join(safe_sentences)
+
+
 def _string_list(value: object) -> list[str]:
     """Return non-empty strings from a loosely typed metadata list."""
 

package/src/ummaya/ipc/document_intent_normalization.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import re
+import uuid
+from pathlib import Path
+from typing import Final
+
+_DOCUMENT_WRITE_REQUEST_RE: Final = re.compile(
+    r"(작성|수정|편집|채우|채워|입력|변경|저장|write|edit|fill|apply|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_SAVE_REQUEST_RE: Final = re.compile(
+    r"(저장|내보내|export|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_READ_ONLY_INSPECT_RE: Final = re.compile(
+    r"(구조.{0,30}빈칸.{0,30}확인|빈칸.{0,30}확인|구조.{0,30}확인|"
+    r"확인해\s*줘|검토만|inspect|read[- ]?only)",
+    re.IGNORECASE,
+)
+_DOCUMENT_MUTATION_PROHIBITION_RE: Final = re.compile(
+    r"(절대.{0,40}(?:수정|저장|작성|채우|입력|변경).{0,40}"
+    r"(?:하지\s*마|하지\s*말|금지)|"
+    r"(?:수정|저장|작성|채우|입력|변경).{0,30}(?:하지\s*마|하지\s*말)|"
+    r"(?:do not|don't).{0,40}(?:modify|save|write|edit|fill))",
+    re.IGNORECASE,
+)
+_QUESTION_FIRST_AUTHORING_RE: Final = re.compile(
+    r"(근거가\s*부족하면\s*먼저\s*질문|먼저\s*(?:확인|파악|검토|질문|물어)|"
+    r"초안을?\s*먼저|아직.{0,40}(?:쓰지\s*마|작성하지\s*마|저장하지\s*마|"
+    r"반영하지\s*마)|문서에는\s*쓰지\s*마)",
+    re.IGNORECASE,
+)
+_DOCUMENT_MUTATION_PARAM_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "approved_draft_id",
+        "destination_display_name",
+        "destination_path",
+        "dry_run",
+        "patches",
+        "styles",
+        "template_id",
+    }
+)
+_DOCUMENT_INTERNAL_USER_QUERY_KEY: Final = "__ummaya_user_query"
+_DOCUMENT_ROOT_SYNTHESIS_KEYS: Final[frozenset[str]] = frozenset(
+    {_DOCUMENT_INTERNAL_USER_QUERY_KEY}
+)
+_DOCUMENT_EXPLICIT_LOCAL_PATH_RE: Final = re.compile(
+    r"(?P<path>(?:~|/)[^\s\"'<>]+?\."
+    r"(?:hwpx|hwp|docx|pdf|xlsx|pptx|odt|ods|odp|doc|xls|ppt|csv|txt|md|json|xml|html))",
+    re.IGNORECASE,
+)
+
+
+def _normalize_document_root_call_for_user_intent(
+    fname: str,
+    args_obj: dict[str, object],
+    latest_user_utt: str,
+) -> dict[str, object]:
+    if fname != "document" or args_obj.get("tool_id") != "document":
+        return args_obj
+    params_obj = args_obj.get("params")
+    if not isinstance(params_obj, dict):
+        return args_obj
+
+    intent_text = _document_intent_text(params_obj, latest_user_utt)
+    synthesized_params = _synthesize_document_read_params(params_obj, intent_text)
+    if synthesized_params is not None:
+        return {**args_obj, "params": synthesized_params}
+
+    normalized_params = dict(params_obj)
+    normalized_params.pop(_DOCUMENT_INTERNAL_USER_QUERY_KEY, None)
+    _normalize_document_path_from_user_query(normalized_params, intent_text)
+    if _is_explicit_read_only_inspect_intent(intent_text):
+        read_only_params = _strip_mutation_params(normalized_params)
+        read_only_params["operation"] = "inspect"
+        read_only_params["instruction"] = intent_text
+        return {**args_obj, "params": read_only_params}
+
+    operation = str(params_obj.get("operation") or "").casefold()
+    changed = normalized_params != params_obj
+    if (
+        operation in {"fill", "save"}
+        and intent_text
+        and _DOCUMENT_WRITE_REQUEST_RE.search(intent_text)
+    ):
+        if _DOCUMENT_SAVE_REQUEST_RE.search(intent_text):
+            normalized_params["operation"] = "save"
+        normalized_params["instruction"] = intent_text
+        return {**args_obj, "params": normalized_params}
+    if operation not in {"inspect", "extract"}:
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+    if _should_keep_read_only_for_question_first_authoring(intent_text):
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+    if not intent_text or not _DOCUMENT_WRITE_REQUEST_RE.search(intent_text):
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+
+    normalized_params["operation"] = (
+        "save" if _DOCUMENT_SAVE_REQUEST_RE.search(intent_text) else "fill"
+    )
+    normalized_params["instruction"] = intent_text
+    return {**args_obj, "params": normalized_params}
+
+
+def _document_intent_text(params_obj: dict[str, object], latest_user_utt: str) -> str:
+    internal_user_query = params_obj.get(_DOCUMENT_INTERNAL_USER_QUERY_KEY)
+    if isinstance(internal_user_query, str) and internal_user_query.strip():
+        return internal_user_query.strip()
+    return latest_user_utt
+
+
+def _synthesize_document_read_params(
+    params_obj: dict[str, object],
+    intent_text: str,
+) -> dict[str, object] | None:
+    if (
+        not intent_text
+        or isinstance(params_obj.get("document"), dict)
+        or set(params_obj) - _DOCUMENT_ROOT_SYNTHESIS_KEYS
+    ):
+        return None
+    local_path = _first_existing_document_path(intent_text, None)
+    if local_path is None:
+        return None
+    document_format = local_path.suffix.removeprefix(".").lower()
+    return {
+        "correlation_id": f"document-intent-{uuid.uuid4().hex}",
+        "document": {"path": str(local_path), "expected_format": document_format},
+        "operation": "inspect",
+        "instruction": intent_text,
+    }
+
+
+def _normalize_document_path_from_user_query(
+    normalized_params: dict[str, object],
+    intent_text: str,
+) -> None:
+    if not intent_text:
+        return
+    document_obj = normalized_params.get("document")
+    if not isinstance(document_obj, dict):
+        return
+    current_path = document_obj.get("path")
+    if isinstance(current_path, str) and Path(current_path).expanduser().exists():
+        return
+    expected_format = document_obj.get("expected_format")
+    expected_suffix = f".{expected_format}".lower() if isinstance(expected_format, str) else None
+    explicit_path = _first_existing_document_path(intent_text, expected_suffix)
+    if explicit_path is None:
+        return
+    normalized_params["document"] = {
+        **document_obj,
+        "path": str(explicit_path),
+    }
+
+
+def _first_existing_document_path(intent_text: str, expected_suffix: str | None) -> Path | None:
+    for match in _DOCUMENT_EXPLICIT_LOCAL_PATH_RE.finditer(intent_text):
+        candidate = Path(match.group("path").rstrip(".,;:)]}）")).expanduser()
+        if expected_suffix is not None and candidate.suffix.lower() != expected_suffix:
+            continue
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def _should_keep_read_only_for_question_first_authoring(intent_text: str) -> bool:
+    return bool(intent_text and _QUESTION_FIRST_AUTHORING_RE.search(intent_text))
+
+
+def _is_explicit_read_only_inspect_intent(intent_text: str) -> bool:
+    return bool(
+        intent_text
+        and _DOCUMENT_READ_ONLY_INSPECT_RE.search(intent_text)
+        and _DOCUMENT_MUTATION_PROHIBITION_RE.search(intent_text)
+    )
+
+
+def _strip_mutation_params(params_obj: dict[str, object]) -> dict[str, object]:
+    return {
+        key: value for key, value in params_obj.items() if key not in _DOCUMENT_MUTATION_PARAM_KEYS
+    }

package/src/ummaya/ipc/frame_schema.py

@@ -528,7 +528,7 @@ class ToolResultEnvelope(BaseModel):
 
     model_config = ConfigDict(frozen=True, extra="allow", populate_by_name=True)
 
-    kind: Literal["find", "locate", "send", "check"] = Field(
+    kind: Literal["find", "locate", "send", "check", "document"] = Field(
         description="Primitive kind discriminator per Spec 031."
     )
 
@@ -576,7 +576,7 @@ class WorkerStatusFrame(_BaseFrame):
     role_id: str = Field(
         description="Specialist label (e.g., transport-specialist, health-specialist)."
     )
-    current_primitive: Literal["find", "locate", "send", "check"] = Field(
+    current_primitive: Literal["find", "locate", "send", "check", "document"] = Field(
         description="Primitive currently being invoked by this worker."
     )
     status: Literal["idle", "running", "waiting_permission", "error"] = Field(
@@ -599,7 +599,7 @@ class PermissionRequestFrame(_BaseFrame):
         description="ULID; round-trips in the matching permission_response frame."
     )
     worker_id: str = Field(description="Worker requesting permission.")
-    primitive_kind: Literal["find", "locate", "send", "check"] = Field(
+    primitive_kind: Literal["find", "locate", "send", "check", "document"] = Field(
         description="The primitive the worker wants to invoke."
     )
     description_ko: str = Field(description="Korean-language description shown to the citizen.")
@@ -669,7 +669,7 @@ class PermissionResponseFrame(_BaseFrame):
     # `layer: 1, tool_name: 'unknown'` (UI-C-1 spec violation: Layer 2/3
     # submits were colour-coded green like a Layer 1 verify).
     # Both fields are optional so legacy backends remain wire-compatible.
-    primitive_kind: Literal["find", "locate", "send", "check"] | None = Field(
+    primitive_kind: Literal["find", "locate", "send", "check", "document"] | None = Field(
         default=None,
         description=(
             "The primitive that was authorised. The TUI feeds this into "
@@ -1220,7 +1220,7 @@ class AdapterManifestEntry(BaseModel):
         max_length=80,
         description="Human-readable display name; bilingual permitted.",
     )
-    primitive: Literal["find", "send", "check", "locate"] = Field(
+    primitive: Literal["find", "send", "check", "locate", "document"] = Field(
         description="Primitive verb the adapter is registered under (I6).",
     )
     policy_authority_url: str | None = Field(