ltcai 9.9.4 → 9.9.9

package/latticeai/core/agent.py

@@ -31,8 +31,21 @@ from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Mapping, Opt
 
 from lattice_brain.runtime.hooks import dispatch_tool
 from lattice_brain.runtime.contracts import runtime_boundary_contract, single_agent_contract
+from latticeai.core.agent_permission import (
+    block_reason_for_tool,
+    non_auto_plan_steps,
+    resolve_deps_mode,
+)
+from latticeai.core.agent_profiles import AgentProfile, profile_for_model
 from latticeai.core.agent_trace import LoopTrace
+from latticeai.core.permission_mode import (
+    PermissionMode,
+    is_circuit_breaker,
+    plan_requires_approval,
+    should_stage_proposal,
+)
 from latticeai.core.file_generation import (
+    generate_file_content,
     infer_file_target,
     infer_project_manifest,
     sanitize_write_content,
@@ -67,7 +80,7 @@ class AgentRunContext:
     __slots__ = ("state", "plan", "transcript", "retry_count",
                  "state_history", "corrections", "final_message", "rollback_log",
                  "executing_model", "reviewing_model", "approved_by_human", "trace",
-                 "on_step")
+                 "on_step", "project_context", "permission_mode")
 
     def __init__(self) -> None:
         self.state:           AgentState   = AgentState.IDLE
@@ -86,6 +99,16 @@ class AgentRunContext:
         # callback here so live SSE clients see progress while EXECUTING.
         # Never serialized; a broken observer never breaks the loop.
         self.on_step: Optional[Callable[[Dict[str, Any]], None]] = None
+        # Multi-turn project loop (v9.9.6): a prompt block describing where the
+        # project stands — files already produced, open TODOs, the last honest
+        # verification. Empty for a standalone run, which behaves exactly as
+        # before. Set by the HTTP layer, read by plan/execute/verify.
+        self.project_context: str = ""
+        # Autonomy dial resolved once per run (v9.9.8). The HTTP layer stamps
+        # the user/workspace-scoped mode here so the plan gate and every
+        # per-tool gate in the same run agree; ``None`` falls back to the
+        # process-wide resolver on ``deps``.
+        self.permission_mode: Optional[str] = None
 
 
 _THINK_BLOCK_RE = re.compile(
@@ -340,6 +363,146 @@ def compact_transcript(
     return summarized
 
 
+def files_written(
+    transcript: List[Dict[str, Any]],
+    file_create_actions: FrozenSet[str],
+) -> List[str]:
+    """Ordered unique paths of files this run successfully wrote (review L5).
+
+    Later executor steps get this as explicit context, so "만들고 이어서
+    설명해" multi-step work sees its own output instead of a stale
+    workspace picture.
+    """
+    seen: List[str] = []
+    for step in transcript:
+        if step.get("state") != AgentState.EXECUTING.value:
+            continue
+        if step.get("action") not in file_create_actions:
+            continue
+        if not isinstance(step.get("result"), dict):
+            continue
+        path = step["result"].get("path") or (step.get("args") or {}).get("path")
+        if path and str(path) not in seen:
+            seen.append(str(path))
+    return seen
+
+
+def artifact_checklist(
+    transcript: List[Dict[str, Any]],
+    file_create_actions: FrozenSet[str],
+) -> List[Dict[str, Any]]:
+    """Deterministic artifact facts for the critic (review L4).
+
+    The critic previously judged file work from prose alone; this surfaces
+    the sanitize/repair honesty flags per written file so a repaired
+    placeholder can never pass as a fulfilled request unchecked.
+    """
+    checklist: List[Dict[str, Any]] = []
+    for step in transcript:
+        if step.get("state") != AgentState.EXECUTING.value:
+            continue
+        if step.get("action") not in file_create_actions:
+            continue
+        if not isinstance(step.get("result"), dict):
+            continue
+        path = step["result"].get("path") or (step.get("args") or {}).get("path")
+        if not path:
+            continue
+        sanitize_meta = step.get("content_sanitize") or {}
+        checklist.append({
+            "path": str(path),
+            "sanitized": bool(sanitize_meta.get("sanitized")),
+            "repaired": bool(sanitize_meta.get("repaired")),
+        })
+    return checklist
+
+
+# Explicit requirement lines a user writes out: "- 다크모드", "1. 검색 기능",
+# "* dark mode". Free prose is deliberately NOT parsed — a wrong requirement
+# is worse than no requirement.
+_REQUIREMENT_LINE_RE = re.compile(r"^\s*(?:[-*•]|\d+[.)])\s+(.{3,120})$", re.MULTILINE)
+
+
+def requirement_coverage(
+    user_message: str,
+    transcript: List[Dict[str, Any]],
+    file_create_actions: FrozenSet[str],
+) -> Dict[str, Any]:
+    """Did the run produce what the request actually asked for? (review 루프 §2)
+
+    The critic judged prose against prose, so "make an HTML+CSS+JS todo app"
+    could pass with one file written. This is the deterministic half of the
+    answer, built from two sources that are honest about their own limits:
+
+    * **manifest files** — when the request maps to a known multi-file project
+      (:func:`infer_project_manifest`), every declared path must have been
+      written. A missing manifest file is a *hard* miss: it is not a matter of
+      taste whether ``style.css`` exists.
+    * **explicit requirement lines** — bullet/numbered lines the user wrote
+      out. These are reported to the critic as a checklist but never block on
+      their own: matching a feature to a transcript is a judgement call, and
+      guessing it wrong would either fake completion or block real work.
+
+    Returns ``{"files": {...}, "requirements": [...], "missing_files": [...],
+    "complete": bool}`` where ``complete`` is false only when a declared
+    manifest file is missing.
+    """
+    written = files_written(transcript, file_create_actions)
+    written_names = {Path(path).name.lower() for path in written}
+    manifest = infer_project_manifest(user_message) or {}
+    declared = [str(spec.get("path") or "") for spec in manifest.get("files", [])]
+    missing = [
+        path for path in declared
+        if path and Path(path).name.lower() not in written_names
+    ]
+    requirements = [
+        line.strip()
+        for line in _REQUIREMENT_LINE_RE.findall(str(user_message or ""))
+    ][:10]
+    return {
+        "files": {"declared": declared, "written": written},
+        "missing_files": missing,
+        "requirements": requirements,
+        "complete": not missing,
+    }
+
+
+def _format_requirement_coverage(coverage: Dict[str, Any]) -> str:
+    """Requirement facts for the critic prompt, or "" when there is nothing."""
+    lines: List[str] = []
+    declared = coverage["files"]["declared"]
+    if declared:
+        written = set(coverage["files"]["written"])
+        lines.append("Requested files (deterministic, from the request):")
+        for path in declared:
+            got = any(Path(item).name.lower() == Path(path).name.lower() for item in written)
+            lines.append(f"- {path}: {'written' if got else 'MISSING'}")
+    if coverage["requirements"]:
+        lines.append(
+            "Requirements the user listed explicitly — check each one against "
+            "the artifacts, not against the plan:"
+        )
+        lines.extend(f"- {item}" for item in coverage["requirements"])
+    return "\n\n" + "\n".join(lines) if lines else ""
+
+
+def _format_artifact_checklist(checklist: List[Dict[str, Any]]) -> str:
+    lines = []
+    for item in checklist:
+        state = (
+            "auto-REPAIRED scaffold" if item["repaired"]
+            else ("sanitized model output" if item["sanitized"] else "written as produced")
+        )
+        lines.append(f"- {item['path']}: {state}")
+    return (
+        "Artifact checklist (deterministic, from the transcript):\n"
+        + "\n".join(lines)
+        + "\nVerify each artifact actually fulfills the user's request. An "
+        "auto-repaired scaffold is NOT completion unless its content "
+        "satisfies what was asked."
+    )
+
+
 @dataclass(frozen=True)
 class TranscriptBudget:
     """Executor/critic prompt shaping caps (review Wave 0.3).
@@ -450,6 +613,16 @@ class AgentDeps:
     # state machine does not shell out directly. Tests can pass a recorder.
     rollback_file: Optional[Callable[[str], Dict[str, Any]]] = None
 
+    # ── snapshot rollback ports (optional, review L7) ────────────────
+    # git-only rollback left non-git workspaces and newly created files
+    # unrecoverable. ``snapshot_file(path)`` captures pre-write state
+    # ({"existed", "content", "too_large"}) before a file-create action;
+    # ``restore_snapshot(path, content)`` restores it (content=None deletes
+    # a file the run created). Both are production-wired with workspace
+    # path safety; tests pass recorders.
+    snapshot_file: Optional[Callable[[str], Dict[str, Any]]] = None
+    restore_snapshot: Optional[Callable[[str, Optional[str]], Dict[str, Any]]] = None
+
     # ── lifecycle hooks port (optional) ──────────────────────────────
     # When present, every tool execution fires the shared pre_tool/post_tool
     # lifecycle, so the agent tool path no longer bypasses hooks.
@@ -484,6 +657,19 @@ class AgentDeps:
     # can also be attached on AgentRunContext.on_step. Both are advisory.
     on_step: Optional[Callable[[Dict[str, Any]], None]] = None
 
+    # ── agent profile (optional, v9.9.7) ─────────────────────────────
+    # How hard the loop works to keep a weak model on contract. None selects
+    # per-run from the executing model id (``profile_for_model``); tests
+    # inject a fixed profile.
+    agent_profile: Optional["AgentProfile"] = None
+
+    # ── permission mode port (optional, v9.9.8) ──────────────────────
+    # The autonomy dial. Either a static mode, or a resolver callable that
+    # accepts ``user_email``/``workspace_id`` scope kwargs (preferred) or no
+    # arguments at all — see ``call_mode_source``. ``None`` means strict,
+    # which is exactly the pre-9.9.8 behaviour.
+    permission_mode: Any = None
+
 
 class SingleAgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
@@ -513,6 +699,44 @@ class SingleAgentRuntime:
             self._env_transcript_budget = TranscriptBudget.from_env()
         return self._env_transcript_budget
 
+    # ── permission mode (v9.9.8) ─────────────────────────────────────
+    def resolve_permission_mode(
+        self,
+        ctx: Optional[AgentRunContext] = None,
+        *,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> PermissionMode:
+        """Autonomy dial for this run.
+
+        A mode stamped on ``ctx`` wins, so the plan a user approved and every
+        tool step in the same run are judged by one dial even if the stored
+        preference changes mid-run. Otherwise the resolver on ``deps`` is
+        consulted with the caller's scope — resolving unscoped would collapse
+        every caller onto the process-wide default.
+        """
+        return resolve_deps_mode(
+            self.deps, ctx, user_email=user_email, workspace_id=workspace_id,
+        )
+
+    def _governed_tools(self) -> FrozenSet[str]:
+        governor = getattr(self.deps, "change_governor", None)
+        if governor is None:
+            return frozenset()
+        return frozenset(getattr(governor, "governed_tools", frozenset()))
+
+    def profile_for(self, model_id: Optional[str]) -> AgentProfile:
+        """Loop profile for the model actually executing this run (v9.9.7).
+
+        An injected ``AgentDeps.agent_profile`` wins (tests, explicit config);
+        otherwise the profile is derived from the model id, so a small local
+        model gets the compact loop without any extra configuration.
+        """
+        injected = getattr(self.deps, "agent_profile", None)
+        if injected is not None:
+            return injected
+        return profile_for_model(model_id)
+
     def _emit_step(self, ctx: AgentRunContext, phase: str, event: str, **details: Any) -> None:
         """Fire the per-run / deps step observers (review Wave 1.1).
 
@@ -532,6 +756,17 @@ class SingleAgentRuntime:
             except Exception as exc:  # noqa: BLE001 — observers are advisory
                 logging.warning("agent step observer failed: %s", exc)
 
+    @staticmethod
+    def _project_block(ctx: AgentRunContext) -> str:
+        """Project-session context for prompts, or "" for a standalone run.
+
+        Multi-turn project loop (v9.9.6): a later run must see the files the
+        project already produced and what is still open, instead of planning
+        from a blank workspace every time.
+        """
+        summary = str(getattr(ctx, "project_context", "") or "").strip()
+        return f"\n\n[PROJECT SESSION]\n{summary}" if summary else ""
+
     def boundary(self) -> Dict[str, Any]:
         return runtime_boundary_contract(
             name="SingleAgentRuntime",
@@ -561,10 +796,11 @@ class SingleAgentRuntime:
     ) -> None:
         """PLAN: Planner role produces a structured plan JSON."""
         d = self.deps
+        project_block = self._project_block(ctx)
         context = (
             f"{d.planner_prompt}\n\n"
             f"[LANGUAGE HINT: {lang_hint}]\n"
-            f"Workspace root: {d.agent_root}\n\n"
+            f"Workspace root: {d.agent_root}{project_block}\n\n"
             f"User request: {req.message}"
         )
         raw = await d.generate_as(
@@ -614,21 +850,20 @@ class SingleAgentRuntime:
         weakening the gate itself.
         """
         d = self.deps
-        auto_approve_tools = {name for name, p in d.tool_governance.items() if p["auto_approve"]}
+        mode = self.resolve_permission_mode(ctx)
         # Governor-managed tools never hard-block the plan: each call is
         # classified at execution time — additive creates run, mutations and
         # deletions of existing content become review proposals.
-        governed_tools = (
-            frozenset(getattr(d.change_governor, "governed_tools", frozenset()))
-            if d.change_governor is not None else frozenset()
-        )
+        governed_tools = self._governed_tools()
         steps = ctx.plan.get("steps", [])
-        non_auto = [
-            s.get("action") for s in steps
-            if s.get("action") not in auto_approve_tools
-            and s.get("action") not in governed_tools
-        ]
-        requires = bool(ctx.plan.get("requires_approval", False)) or bool(non_auto)
+        non_auto = non_auto_plan_steps(
+            mode, steps, d.tool_governance or {}, governed_tools=governed_tools,
+        )
+        requires = plan_requires_approval(
+            mode,
+            non_auto_steps=non_auto,
+            plan_flag=bool(ctx.plan.get("requires_approval", False)),
+        )
         lines = [
             f"{index}. {step.get('description') or step.get('action') or '?'}"
             for index, step in enumerate(steps, start=1)
@@ -639,6 +874,7 @@ class SingleAgentRuntime:
         return {
             "requires_approval": requires,
             "non_auto_steps": non_auto,
+            "permission_mode": mode.value,
             "plan_summary": summary,
         }
 
@@ -681,13 +917,16 @@ class SingleAgentRuntime:
     ) -> None:
         """EXECUTE: Executor role calls tools one at a time until final or budget exhausted."""
         d = self.deps
+        profile = self.profile_for(model_id)
         exec_count = sum(1 for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value)
         budget = max(1, max_steps - exec_count)
         parse_failures = 0
 
         for _ in range(budget):
             request_workspace = getattr(req, "workspace_id", None)
-            context = self._executor_context(ctx, req, lang_hint, current_user, request_workspace)
+            context = self._executor_context(
+                ctx, req, lang_hint, current_user, request_workspace, profile=profile
+            )
             raw = await d.generate_as(
                 model_id,
                 message="Execute the next step.",
@@ -700,7 +939,15 @@ class SingleAgentRuntime:
                 ctx.trace.repair("execute", repairs=exec_repairs)
             except ValueError as exc:
                 parse_failures += 1
-                if self._note_parse_failure(ctx, raw, exc, parse_failures):
+                if self._note_parse_failure(ctx, raw, exc, parse_failures, profile):
+                    # Direct-path fallback (v9.9.7): a small model that cannot
+                    # hold the tool-call protocol can still write a file. Run
+                    # the plan's own file steps without asking for any JSON.
+                    if profile.direct_path_fallback and await self._direct_file_path(
+                        ctx, req, current_user, model_id
+                    ):
+                        ctx.state = AgentState.VERIFYING
+                        return
                     break
                 continue
 
@@ -767,6 +1014,7 @@ class SingleAgentRuntime:
     def _executor_context(
         self, ctx: AgentRunContext, req: Any, lang_hint: str,
         current_user: str, request_workspace: Optional[str],
+        profile: Optional[AgentProfile] = None,
     ) -> str:
         """Assemble one executor turn's prompt (plan, corrections, recent chat)."""
         d = self.deps
@@ -786,16 +1034,26 @@ class SingleAgentRuntime:
             recent_kwargs["workspace_id"] = request_workspace
         recent_conversation = d.recent_chat_context(**recent_kwargs) or "(none)"
         budget = self.transcript_budget
+        # A small model drowns in a long transcript far sooner than a large
+        # one, so the profile may narrow the window (v9.9.7).
+        window = min(budget.window, profile.transcript_window) if profile else budget.window
         bounded_transcript = compact_transcript(
             ctx.transcript,
-            window=budget.window,
+            window=window,
             result_chars=budget.result_chars,
         )
+        # Mid-run workspace awareness (review L5): later steps must see what
+        # this run already produced instead of a stale workspace picture.
+        written = files_written(ctx.transcript, d.file_create_actions)
+        written_hint = (
+            "\n\nFiles written by this run so far (they exist in the workspace now):\n"
+            + "\n".join(f"- {path}" for path in written)
+        ) if written else ""
         return (
             f"{d.executor_prompt}\n\n"
             f"[LANGUAGE HINT: {lang_hint}]\n"
-            f"Workspace root: {d.agent_root}\n\n"
-            f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}\n\n"
+            f"Workspace root: {d.agent_root}{self._project_block(ctx)}\n\n"
+            f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}{written_hint}\n\n"
             f"Recent conversation:\n{recent_conversation}\n\n"
             f"User request: {req.message}{corrections_hint}\n\n"
             f"Execution transcript:\n{json.dumps(bounded_transcript, ensure_ascii=False, indent=2)}"
@@ -803,13 +1061,15 @@ class SingleAgentRuntime:
 
     def _note_parse_failure(
         self, ctx: AgentRunContext, raw: Any, exc: ValueError, parse_failures: int,
+        profile: Optional[AgentProfile] = None,
     ) -> bool:
         """Record one executor parse slip; True when the run should stop retrying."""
+        profile = profile or self.profile_for(None)
         ctx.transcript.append({
             "state": AgentState.EXECUTING.value, "action": "parse_error",
             "raw": str(raw)[:400], "error": str(exc),
         })
-        if parse_failures >= 3:
+        if parse_failures >= profile.parse_failure_budget:
             ctx.trace.parse_error("execute", error=str(exc), recovered=False)
             self._emit_step(ctx, "execute", "parse_error", recovered=False)
             return True
@@ -823,9 +1083,10 @@ class SingleAgentRuntime:
             'EXACTLY one JSON object like {"thoughts": "...", "action": '
             '"tool_name", "args": {...}} and nothing else.'
         )
-        if parse_failures >= 2:
+        if parse_failures >= profile.escalate_after:
             # Escalate: name the valid tools so the model stops
-            # inventing action names or prose.
+            # inventing action names or prose. The compact profile escalates
+            # a slip earlier — a small model needs the list sooner.
             valid = ", ".join(sorted(self.deps.tool_governance.keys()))
             hint = (
                 f"{hint} Valid action values are: {valid}, final. "
@@ -836,6 +1097,84 @@ class SingleAgentRuntime:
             ctx.trace.correction("execute", hint=hint)
         return False
 
+    async def _direct_file_path(
+        self, ctx: AgentRunContext, req: Any, current_user: str,
+        model_id: Optional[str],
+    ) -> bool:
+        """Write the plan's file steps without asking the model for JSON (v9.9.7).
+
+        The compact profile's escape hatch. A 1–4B local model that cannot hold
+        the tool-call protocol can still write a file, so when JSON tool calls
+        are exhausted the loop drops the protocol entirely: it takes the paths
+        the *planner* already chose and asks only for file content in plain
+        text, through the same validated
+        :func:`~latticeai.core.file_generation.generate_file_content` pipeline
+        the direct chat path uses.
+
+        Returns True when at least one file was actually written. Honest
+        failure modes: no planned paths, a governor that stages the write as a
+        proposal, or a tool error all return False and leave the run to end as
+        it would have — this never fabricates evidence.
+        """
+        d = self.deps
+        planned: List[str] = []
+        for step in ctx.plan.get("steps") or []:
+            if not isinstance(step, dict) or step.get("action") not in d.file_create_actions:
+                continue
+            path = str((step.get("args") or {}).get("path") or "").strip()
+            if path and path not in planned:
+                planned.append(path)
+        if not planned:
+            inferred = infer_file_target(getattr(req, "message", "") or "")
+            if inferred:
+                planned = [inferred]
+        if not planned:
+            return False
+
+        goal = str(ctx.plan.get("goal") or getattr(req, "message", "") or "")
+
+        async def _generate(context: str) -> Any:
+            return await d.generate_as(
+                model_id,
+                message="Write the file content.",
+                context=context,
+                max_tokens=self.phase_budgets.execute_tokens,
+                temperature=0.2,
+            )
+
+        wrote = False
+        for path in planned[:6]:
+            try:
+                content, meta = await generate_file_content(
+                    _generate,
+                    target_path=path,
+                    user_request=goal,
+                    bundle_files=planned if len(planned) > 1 else None,
+                )
+            except Exception as exc:  # noqa: BLE001 — fallback must not raise
+                logging.warning("direct file path generation failed for %s: %s", path, exc)
+                continue
+            ctx.trace.llm_call("execute", model=model_id)
+            ctx.trace.repair("execute", repairs=["direct_path_fallback"])
+            args = {"path": path, "content": content}
+            policy = d.policy_for("write_file", args)
+            risk = d.risk_level(policy)
+            before = len(ctx.transcript)
+            self._dispatch_step(ctx, "write_file", "direct path fallback", args, policy, risk, current_user)
+            last = ctx.transcript[-1] if len(ctx.transcript) > before else {}
+            if isinstance(last.get("result"), dict) and not last["result"].get("proposed"):
+                wrote = True
+                last["direct_path"] = True
+                last["generation"] = {"repaired": bool(meta.get("repaired"))}
+        if wrote:
+            ctx.trace.decision("execute", decision="direct_path_fallback", files=len(planned))
+            self._emit_step(ctx, "execute", "direct_path", files=len(planned))
+            ctx.final_message = (
+                "도구 호출 형식을 계속 벗어나서, 계획에 있던 파일을 직접 생성했습니다. "
+                "내용을 확인해 주세요."
+            )
+        return wrote
+
     def _is_repeated_create(self, ctx: AgentRunContext, name: Any, args: dict) -> bool:
         """Loop guard: the same file-create action+args re-issued right after a result."""
         exec_steps = [s for s in ctx.transcript if s.get("state") == AgentState.EXECUTING.value]
@@ -858,10 +1197,37 @@ class SingleAgentRuntime:
         Returns ``(proposed, governor_allows_additive)``: ``proposed`` means the
         step was staged as a proposal (skip execution); ``allows_additive`` lets
         an additive create pass the classic approval gate.
+
+        Under a mode that does not stage proposals (``trusted`` / ``bypass``)
+        the decision is made *before* the governor is consulted, because
+        ``review`` persists a proposal as a side effect — reviewing first and
+        discarding the verdict afterwards would apply the change *and* leave an
+        orphan proposal pending in the Review Center.
         """
         d = self.deps
         if d.change_governor is None:
             return False, False
+
+        mode = self.resolve_permission_mode(
+            ctx, user_email=current_user, workspace_id=request_workspace,
+        )
+        if not should_stage_proposal(mode, proposal_required=True):
+            if name not in self._governed_tools():
+                return False, False
+            if policy.get("destructive") or policy.get("risk") == "destructive":
+                # Let the destructive gate downstream own the block + transcript.
+                return False, False
+            d.audit(
+                "agent_change_auto_applied",
+                user_email=current_user,
+                workspace_id=request_workspace,
+                action=name,
+                path=str(args.get("path") or "") or None,
+                permission_mode=mode.value,
+                note="permission mode auto-applies mutation with audit",
+            )
+            return False, True
+
         verdict = d.change_governor.review(
             name, args, policy=dict(policy),
             user_email=current_user, workspace_id=request_workspace,
@@ -893,16 +1259,42 @@ class SingleAgentRuntime:
         self, ctx: AgentRunContext, req: Any, name: str, thoughts: str, args: dict,
         policy: dict, risk: str, current_user: str, governor_allows_additive: bool,
     ) -> bool:
-        """Classic destructive / explicit-approval gates; True when the step was blocked."""
+        """Destructive / circuit-breaker / explicit-approval gates.
+
+        Returns True when the step was blocked. The active permission mode can
+        widen what runs without an extra approval prompt, but never widens a
+        circuit breaker or the destructive gate.
+        """
         d = self.deps
-        if policy["risk"] == "destructive":
+        mode = self.resolve_permission_mode(
+            ctx,
+            user_email=current_user,
+            workspace_id=getattr(req, "workspace_id", None),
+        )
+        # Hard denials first — mode-invariant. A circuit breaker (root/home
+        # paths, `rm -rf /` style commands) and a destructive policy are both
+        # audited as ``blocked`` with the reason that actually fired, rather
+        # than being flattened into the approval path.
+        breaker = is_circuit_breaker(name, policy, args)
+        hard_deny = breaker or (
+            "destructive policy"
+            if policy["risk"] == "destructive" or policy.get("destructive")
+            else None
+        )
+        if hard_deny:
+            error = (
+                f"BLOCKED: destructive action '{name}' not permitted in agent mode."
+                if hard_deny == "destructive policy"
+                else f"BLOCKED: {hard_deny}"
+            )
             ctx.trace.tool("execute", name=name, outcome="blocked_destructive", risk=risk)
             self._emit_step(ctx, "execute", "blocked", action=name, reason="destructive")
             ctx.transcript.append({
                 "state": AgentState.EXECUTING.value, "action": name,
                 "thoughts": thoughts, "args": args, "risk": risk,
                 "governance": dict(policy),
-                "error": f"BLOCKED: destructive action '{name}' not permitted in agent mode.",
+                "permission_mode": mode.value,
+                "error": error,
             })
             d.audit(
                 "agent_blocked", user_email=current_user, source=getattr(req, "source", None) or "agent",
@@ -910,25 +1302,33 @@ class SingleAgentRuntime:
             )
             return True
 
-        if not policy["auto_approve"] and not ctx.approved_by_human and not governor_allows_additive:
-            d.audit(
-                "agent_exec", user_email=current_user, source=getattr(req, "source", None) or "agent",
-                state=AgentState.EXECUTING.value, action=name, risk=risk,
-                shell=policy["shell"], network=policy["network"],
-                destructive=policy["destructive"], sandbox=policy["sandbox"],
-                rollback=policy["rollback"],
-                args={k: v for k, v in args.items() if k != "content"},
-            )
-            ctx.trace.tool("execute", name=name, outcome="blocked_approval", risk=risk)
-            self._emit_step(ctx, "execute", "blocked", action=name, reason="approval")
-            ctx.transcript.append({
-                "state": AgentState.EXECUTING.value, "action": name,
-                "thoughts": thoughts, "args": args, "risk": risk,
-                "governance": dict(policy),
-                "error": f"BLOCKED: action '{name}' requires explicit approval.",
-            })
-            return True
-        return False
+        reason = block_reason_for_tool(
+            mode, name, policy, args,
+            approved_by_human=bool(ctx.approved_by_human),
+            governor_allows_additive=governor_allows_additive,
+        )
+        if reason is None:
+            return False
+
+        d.audit(
+            "agent_exec", user_email=current_user, source=getattr(req, "source", None) or "agent",
+            state=AgentState.EXECUTING.value, action=name, risk=risk,
+            shell=policy["shell"], network=policy["network"],
+            destructive=policy["destructive"], sandbox=policy["sandbox"],
+            rollback=policy["rollback"],
+            permission_mode=mode.value,
+            args={k: v for k, v in args.items() if k != "content"},
+        )
+        ctx.trace.tool("execute", name=name, outcome="blocked_approval", risk=risk)
+        self._emit_step(ctx, "execute", "blocked", action=name, reason="approval")
+        ctx.transcript.append({
+            "state": AgentState.EXECUTING.value, "action": name,
+            "thoughts": thoughts, "args": args, "risk": risk,
+            "governance": dict(policy),
+            "permission_mode": mode.value,
+            "error": reason,
+        })
+        return True
 
     def _dispatch_step(
         self, ctx: AgentRunContext, name: str, thoughts: str, args: dict,
@@ -961,6 +1361,22 @@ class SingleAgentRuntime:
             if s.get("state") == AgentState.EXECUTING.value
             and s.get("action") not in (None, "final", "parse_error")
         )
+        if (
+            name in d.file_create_actions
+            and d.snapshot_file is not None
+            and args.get("path")
+        ):
+            # Pre-write snapshot (review L7): the first capture per path is
+            # the true pre-run state — later writes to the same path must
+            # not overwrite it. Best-effort: a snapshot failure never
+            # blocks the write, it only narrows rollback options.
+            path_str = str(args["path"])
+            if not any(entry.get("path") == path_str for entry in ctx.rollback_log):
+                try:
+                    pre = d.snapshot_file(path_str)
+                    ctx.rollback_log.append({"path": path_str, **(pre or {})})
+                except Exception as exc:  # noqa: BLE001
+                    logging.warning("pre-write snapshot failed for %s: %s", path_str, exc)
         try:
             d.check_role(name, current_user)
             # Shared tool lifecycle: pre_tool (may block) → execute → post_tool.
@@ -1025,11 +1441,25 @@ class SingleAgentRuntime:
         verify_transcript = _truncate_strings(
             ctx.transcript, self.transcript_budget.verify_chars
         )
+        # Deterministic artifact facts (review L4): the critic sees the
+        # sanitize/repair honesty flags per written file, not just prose.
+        checklist = artifact_checklist(ctx.transcript, d.file_create_actions)
+        checklist_hint = (
+            f"\n\n{_format_artifact_checklist(checklist)}" if checklist else ""
+        )
+        # Requirement coverage (review 루프 §2): the critic previously judged
+        # "did this fulfill the request?" from prose alone. It now also sees
+        # which requested files actually exist and which requirements the user
+        # spelled out.
+        coverage = requirement_coverage(
+            req.message, ctx.transcript, d.file_create_actions
+        )
         context = (
             f"{d.critic_prompt}\n\n"
             f"[LANGUAGE HINT: {lang_hint}]\n\n"
             f"Original request: {req.message}\n"
-            f"Plan goal: {ctx.plan.get('goal', req.message)}\n\n"
+            f"Plan goal: {ctx.plan.get('goal', req.message)}{checklist_hint}"
+            f"{_format_requirement_coverage(coverage)}\n\n"
             f"Full transcript:\n{json.dumps(verify_transcript, ensure_ascii=False, indent=2)}"
         )
         raw = await d.generate_as(
@@ -1129,6 +1559,24 @@ class SingleAgentRuntime:
                 )
                 ctx.state = AgentState.NEEDS_REVIEW
                 return
+            if not coverage["complete"]:
+                # A PASS that leaves a *requested file* unwritten is not a
+                # completion — this is a fact, not a judgement, so it is
+                # enforced rather than merely reported to the critic.
+                missing = ", ".join(coverage["missing_files"])
+                ctx.trace.decision(
+                    "verify", decision="needs_review_missing_files",
+                    missing=len(coverage["missing_files"]),
+                )
+                ctx.transcript.append({
+                    "state": AgentState.VERIFYING.value,
+                    "requirement_coverage": coverage,
+                })
+                ctx.final_message = (
+                    f"요청한 파일 중 일부가 만들어지지 않아 완료로 처리하지 않았습니다: {missing}"
+                )
+                ctx.state = AgentState.NEEDS_REVIEW
+                return
             if not ctx.final_message:
                 ctx.final_message = verdict.get("reason", "작업이 완료되었습니다.")
             ctx.state = AgentState.DONE
@@ -1162,40 +1610,68 @@ class SingleAgentRuntime:
             ctx.state = AgentState.FAILED
 
     # ── ROLLBACK ─────────────────────────────────────────────────────
+    def _snapshot_for(self, ctx: AgentRunContext, path: str) -> Optional[Dict[str, Any]]:
+        for entry in ctx.rollback_log:
+            if entry.get("path") == path:
+                return entry
+        return None
+
+    def _rollback_one(self, ctx: AgentRunContext, path: str, gov: Dict[str, Any]) -> Dict[str, Any]:
+        """Recover one path: git when governed and available, else the
+        pre-write snapshot, else an honest ``mode="none"`` (review L7)."""
+        d = self.deps
+        if gov.get("rollback") == "git" and d.rollback_file is not None:
+            try:
+                result = dict(d.rollback_file(str(path)))
+            except Exception as exc:  # noqa: BLE001
+                result = {"path": path, "ok": False, "error": str(exc)}
+            if result.get("ok"):
+                result["mode"] = "git"
+                return result
+        snapshot = self._snapshot_for(ctx, str(path))
+        if snapshot is not None and d.restore_snapshot is not None and not snapshot.get("too_large"):
+            content = snapshot.get("content") if snapshot.get("existed") else None
+            try:
+                restored = dict(d.restore_snapshot(str(path), content))
+            except Exception as exc:  # noqa: BLE001
+                restored = {"path": path, "ok": False, "error": str(exc)}
+            restored.setdefault("path", path)
+            restored["mode"] = "snapshot"
+            return restored
+        return {
+            "path": path, "ok": False, "mode": "none",
+            "error": "no rollback available (git not applicable, no usable snapshot)",
+        }
+
     def rollback(self, ctx: AgentRunContext, current_user: str) -> None:
-        """ROLLBACK: attempt git checkout for each edited file, then FAILED."""
+        """ROLLBACK: recover written files (git → snapshot → none), then FAILED."""
         d = self.deps
         rolled: List[dict] = []
+        seen_paths: set = set()
         for step in ctx.transcript:
             if step.get("state") != AgentState.EXECUTING.value:
                 continue
-            gov = step.get("governance", {})
-            if gov.get("rollback") != "git":
+            if not isinstance(step.get("result"), dict):
                 continue
-            result = step.get("result", {})
-            if not isinstance(result, dict):
-                result = {}
-            path = result.get("path") or (step.get("args") or {}).get("path", "")
-            if not path:
+            gov = step.get("governance", {}) or {}
+            path = step["result"].get("path") or (step.get("args") or {}).get("path", "")
+            if not path or str(path) in seen_paths:
                 continue
-            if d.rollback_file is None:
-                rolled.append({"path": path, "ok": False, "error": "rollback_file port is not configured"})
+            if gov.get("rollback") != "git" and step.get("action") not in d.file_create_actions:
                 continue
-            try:
-                rolled.append(d.rollback_file(str(path)))
-            except Exception as exc:
-                rolled.append({"path": path, "ok": False, "error": str(exc)})
+            seen_paths.add(str(path))
+            rolled.append(self._rollback_one(ctx, str(path), gov))
 
         ctx.transcript.append({"state": AgentState.ROLLBACK.value, "rolled_back": rolled})
         ctx.trace.decision(
             "rollback", decision="rolled_back",
             attempted=len(rolled), recovered=sum(1 for r in rolled if r.get("ok")),
         )
-        recovered = [r["path"] for r in rolled if r.get("ok")]
+        recovered = [f"{r['path']} ({r.get('mode')})" for r in rolled if r.get("ok")]
         ctx.final_message = (
             f"실행 실패로 롤백했습니다. 복구 파일: {recovered}"
             if recovered
-            else "롤백을 시도했으나 복구할 파일이 없거나 git이 초기화되지 않았습니다."
+            else "롤백을 시도했으나 복구할 파일이 없거나 git/스냅샷 복구 수단이 없습니다."
         )
         d.audit("agent_rollback", user_email=current_user, rolled_back=rolled)
         self._emit_step(ctx, "rollback", "rolled_back", recovered=len(recovered))