localcode 0.3.21__tar.gz → 0.3.23__tar.gz

{localcode-0.3.21/src/localcode.egg-info → localcode-0.3.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.21
+Version: 0.3.23
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0

{localcode-0.3.21 → localcode-0.3.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.3.21"
+version = "0.3.23"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
 requires-python = ">=3.10"

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.3.21"
+__version__ = "0.3.23"

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/context.py

@@ -605,25 +605,42 @@ def _msg_bytes(messages: list[dict]) -> int:
 
 def _window_aware_compaction(ctx_window_chars: int | None) -> tuple[int, int]:
     """(history_budget_bytes, keep_recent_tool_results) scaled to the context
-    window. The whole point: compaction must be DYNAMIC per machine. A 16 GB
-    Mac with a ~16K window has no room, so aggressive lossy compaction (the
-    old fixed 36 KB / keep-4) is correct. A 128 GB Mac with a 128K window has
-    ~8x the room — crushing its history to 36 KB threw away the data model the
-    model needs and made it lose track / re-read / drift. So budget ~55% of
-    the window to history and keep proportionally more recent tool output.
+    window. Capacity and replay latency are separate budgets: large-RAM Macs
+    can retain richer recent evidence, but hybrid/recurrent local models may
+    still re-process the entire prompt each round. Durable ledgers preserve
+    completed work while this hot transcript remains bounded.
 
     `ctx_window_chars` ≈ num_ctx tokens × ~3.5 chars/token. None/unknown →
     the legacy fixed behaviour (back-compat, safe on tiny windows).
     """
     if not ctx_window_chars or ctx_window_chars <= 0:
         return 36_000, COMPACT_KEEP_RECENT_TOOL_RESULTS
-    budget = max(36_000, int(ctx_window_chars * 0.55))
-    keep = max(COMPACT_KEEP_RECENT_TOOL_RESULTS, min(24, ctx_window_chars // 20_000))
+    # A large KV window is capacity, not a latency target. Live 128 GB / Qwen
+    # traces showed TTFT rising from ~2 s to 44 s as one build replayed ~28K
+    # prompt tokens. Cap the hot transcript while the durable progress ledger
+    # and filesystem-state block preserve what was completed.
+    budget = max(36_000, min(48_000, int(ctx_window_chars * 0.20)))
+    keep = max(COMPACT_KEEP_RECENT_TOOL_RESULTS, min(8, ctx_window_chars // 40_000))
     return budget, keep
 
 
+def latency_budgeted_hot_replay(
+    ctx_window_chars: int | None,
+    observed_ttft_ms: int | None,
+    *,
+    target_ttft_ms: int = 8_000,
+) -> tuple[int, int]:
+    """Adapt hot replay to measured local prefill latency, not KV capacity."""
+    budget, keep = _window_aware_compaction(ctx_window_chars)
+    if not observed_ttft_ms or observed_ttft_ms <= target_ttft_ms:
+        return budget, keep
+    ratio = max(0.35, target_ttft_ms / observed_ttft_ms)
+    return max(18_000, int(budget * ratio)), max(2, int(keep * ratio))
+
+
 def _prepare_model_messages(
-    messages: list[dict], ctx_window_chars: int | None = None
+    messages: list[dict], ctx_window_chars: int | None = None,
+    observed_ttft_ms: int | None = None,
 ) -> list[dict]:
     """One-stop context-shrink pass before sending to the model.
 
@@ -649,7 +666,7 @@ def _prepare_model_messages(
     practice?" without instrumenting the agent loop. Silent on no-op
     so the log doesn't fill up with empty events.
     """
-    budget_bytes, keep_recent = _window_aware_compaction(ctx_window_chars)
+    budget_bytes, keep_recent = latency_budgeted_hot_replay(ctx_window_chars, observed_ttft_ms)
     before = _msg_bytes(messages)
     after_writes = _redact_old_write_args(messages)
     bytes_writes = before - _msg_bytes(after_writes)
@@ -704,31 +721,36 @@ def _microcompact_for_prompt_budget(messages: list[dict], *, target_bytes: int =
         return messages
 
     system_count = 1 if messages and messages[0].get("role") == "system" else 0
-    boundary = max(system_count, len(messages) - 12)
-    while boundary > system_count:
-        if messages[boundary].get("role") == "tool":
-            boundary -= 1
-            continue
-        prev = messages[boundary - 1]
-        if prev.get("role") == "assistant" and prev.get("tool_calls"):
-            boundary -= 1
+    best = messages
+    # Tighten the protocol-safe suffix until the serialized prompt fits. A
+    # fixed 12-message tail can itself contain several complete source files.
+    for tail_size in (12, 10, 8, 6, 4):
+        boundary = max(system_count, len(messages) - tail_size)
+        while boundary > system_count:
+            if messages[boundary].get("role") == "tool":
+                boundary -= 1
+                continue
+            prev = messages[boundary - 1]
+            if prev.get("role") == "assistant" and prev.get("tool_calls"):
+                boundary -= 1
+                continue
+            break
+        if boundary <= system_count:
             continue
-        break
-    if boundary <= system_count:
-        return messages
-
-    old = messages[system_count:boundary]
-    recent = messages[boundary:]
-    summary = _compact_history_summary(old)
-    candidate = [
-        *messages[:system_count],
-        {"role": "user", "content": summary},
-        {"role": "assistant", "content": "Continuing with the summarized prior work."},
-        *recent,
-    ]
-    if _msg_bytes(candidate) >= _msg_bytes(messages):
-        return messages
-    return candidate
+        old = messages[system_count:boundary]
+        recent = messages[boundary:]
+        summary = _compact_history_summary(old)
+        candidate = [
+            *messages[:system_count],
+            {"role": "user", "content": summary},
+            {"role": "assistant", "content": "Continuing with the summarized prior work."},
+            *recent,
+        ]
+        if _msg_bytes(candidate) < _msg_bytes(best):
+            best = candidate
+        if _msg_bytes(candidate) <= target_bytes:
+            return candidate
+    return best
 
 
 def _compact_history_summary(messages: list[dict]) -> str:

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/goal.py

@@ -154,21 +154,30 @@ class GoalState:
 
 
 def infer_goal_state(user_text: str) -> GoalState:
-    # Generalist mode: every turn is general_task. The regex-based branching
-    # (build_app / edit_existing / run_or_launch / question) was driving
-    # false-positive rejections in loop.py and over-greedy followup
-    # downgrades in app.py. Single code path = no classifier confusion.
     text = (user_text or "").strip()
+    lower = text.lower()
+    if re.search(r"\b(build|create|make|scaffold|implement)\b.{0,40}\b(app|application|website|dashboard|api|service|project)\b", lower):
+        goal_type, task_kind = "build_app", "new_app"
+        criteria = ("Requested implementation exists on disk", "Relevant build or tests pass", "Runtime behavior is verified when applicable")
+    elif re.search(r"\b(run|launch|start|serve|open)\b.{0,24}\b(app|server|site|project|it)\b", lower):
+        goal_type, task_kind = "run_or_launch", "run"
+        criteria = ("Target process is running", "Exact access URL or process status is reported")
+    elif re.search(r"\b(fix|change|edit|update|refactor|rename|remove|add)\b", lower):
+        goal_type, task_kind = "edit_existing", "edit"
+        criteria = ("Requested code change exists", "Relevant verification passes")
+    elif re.match(r"^(what|why|how|where|when|who|is|are|can|could|should|does|do)\b", lower) or text.endswith("?"):
+        goal_type, task_kind = "question", "question"
+        criteria = ("Question is answered from grounded evidence",)
+    else:
+        goal_type, task_kind = "general_task", "general_task"
+        criteria = ("Assistant makes concrete progress toward the user's request", "Assistant stops only on completion or a focused blocking question")
     return GoalState(
         raw_user_text=text,
-        goal_type="general_task",
-        task_kind="general_task",
+        goal_type=goal_type,
+        task_kind=task_kind,
         task_slug=_make_task_slug(text),
         goal_summary=text[:240],
-        success_criteria=(
-            "Assistant makes concrete progress toward the user's request",
-            "Assistant stops only on completion or a focused blocking question",
-        ),
+        success_criteria=criteria,
     )
 
 

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/helpers.py

@@ -162,6 +162,15 @@ def _execute_tool_result(app: "LocalCodeApp", name: str, args: dict, out: "Outpu
     wrapping plan-mode policy layer that refuses destructive tools
     while the agent is in plan-explore mode.
     """
+    try:
+        hook = getattr(app, "hooks", None)
+        decision = hook.on_pre_tool_use(name, args) if hook is not None else None
+        if decision is not None and decision.blocked:
+            reason = decision.error or decision.output or "pre-tool hook blocked"
+            return ToolResult(text=f"REJECTED: {reason}", ok=False, facts={"tool": name, "ok": False, "hook_blocked": True})
+    except Exception:
+        pass
+
     # Lint-gate: for source-file writes/edits, snapshot the file before the
     # tool runs so we can auto-revert on syntax-break. Motivation: the model
     # at 2-bit quant has been observed to delete import statements during
@@ -210,8 +219,19 @@ def _execute_tool_result(app: "LocalCodeApp", name: str, args: dict, out: "Outpu
         result = _tools_dispatch_result(name, ToolContext(app=app, out=out), args)
     except Exception as e:
         text = f"Error in {name}: {type(e).__name__}: {e}"
+        try:
+            if getattr(app, "hooks", None) is not None:
+                app.hooks.on_post_tool_use(name, args, text, error=True)
+        except Exception:
+            pass
         return ToolResult(text=text, ok=False, facts={"tool": name, "ok": False, "error_type": type(e).__name__})
 
+    try:
+        if getattr(app, "hooks", None) is not None:
+            app.hooks.on_post_tool_use(name, args, result.text, error=not result.ok)
+    except Exception:
+        pass
+
     if target_path is not None and target_path.exists() and target_path.suffix == ".py":
         # Python: ast.parse is cheap and authoritative.
         import ast as _ast
@@ -228,6 +248,12 @@ def _execute_tool_result(app: "LocalCodeApp", name: str, args: dict, out: "Outpu
                 "user explicitly asked."
             )
             return ToolResult(text=text, ok=False, facts={"tool": name, "ok": False, "path": str(target_path), "reverted": True})
+    if name in _lint_tools:
+        try:
+            if getattr(app, "hooks", None) is not None:
+                app.hooks.on_post_edit(str(args.get("path", "")), result.text, error=not result.ok)
+        except Exception:
+            pass
     return result
 
 

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/hooks.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 import re
 from typing import Any
+from ..evidence import EvidenceRegistry
 __all__ = [
     "TurnState",
     "EvidenceLedger",
@@ -20,6 +21,8 @@ __all__ = [
     "completion_gate",
     "ran_build_or_test",
     "_changed_code_files",
+    "CompletionEvidence",
+    "deterministic_completion",
 ]
 
 
@@ -32,6 +35,7 @@ class TurnState:
     bash_history: list[tuple[str, str]] = field(default_factory=list)
     tools_called: list[str] = field(default_factory=list)
     evidence: "EvidenceLedger" = field(default_factory=lambda: EvidenceLedger())
+    verification_registry: EvidenceRegistry = field(default_factory=EvidenceRegistry)
 
 
 @dataclass
@@ -85,6 +89,22 @@ class QualityVerdict:
     correction: str = ""
 
 
+@dataclass(frozen=True)
+class CompletionEvidence:
+    criterion: str
+    evidence: tuple[str, ...] = ()
+    satisfied: bool = False
+
+
+def deterministic_completion(criteria: list[CompletionEvidence]) -> QualityVerdict:
+    if not criteria:
+        return QualityVerdict(False, "no-success-criteria", "Define verifiable outcomes first.")
+    missing = [item.criterion for item in criteria if not item.satisfied or not item.evidence]
+    if missing:
+        return QualityVerdict(False, "missing-completion-evidence", "Gather evidence for: " + "; ".join(missing[:5]))
+    return QualityVerdict(True, "success-criteria-satisfied", "Stop: further polish is out of scope.")
+
+
 def before_turn(state: TurnState) -> None:
     """Reserved hook for per-turn initialization."""
     return None

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/loop.py

@@ -591,6 +591,7 @@ def run_agent_loop(
     _MAX_LOOKS_FINE_STREAK = 3
     _deterministic_launch_done = False
     _verified_launch_summary = ""
+    _observed_ttft_ms = 0
 
     if _goal_state.goal_type == "run_or_launch":
         try:
@@ -715,9 +716,15 @@ def run_agent_loop(
                     f"Compacting conversation (≈{estimate_tokens(messages)} tokens "
                     f"of {ctx_tokens} context → summary)..."
                 )
+                _before_compact_count = len(messages)
                 messages[:] = compact(
                     messages, app.engine, context_window=ctx_tokens, ram_gb=_ram_gb
                 )
+                try:
+                    if getattr(app, "hooks", None) is not None:
+                        app.hooks.on_post_compaction(_before_compact_count, len(messages))
+                except Exception:
+                    pass
         except Exception as _compact_err:
             # Never let compaction failure kill the agent loop — continue
             # with the unchanged messages and let the user see the error.
@@ -774,7 +781,8 @@ def run_agent_loop(
             except Exception:
                 _ctx_chars = None
             model_messages = hook_before_model(
-                _prepare_model_messages(messages, ctx_window_chars=_ctx_chars),
+                _prepare_model_messages(messages, ctx_window_chars=_ctx_chars,
+                                        observed_ttft_ms=_observed_ttft_ms),
                 _hook_state,
             )
             # Inject a window-scaled progress ledger (Codex-style tool-state
@@ -872,6 +880,7 @@ def run_agent_loop(
             _round_reasoning_chars = _stream_result.reasoning_chars
             _round_pending_tool_count = _stream_result.pending_tool_count
             _round_ttft_ms = _stream_result.ttft_ms
+            _observed_ttft_ms = _round_ttft_ms
             _round_decode_ms = _stream_result.decode_ms
             _stream_tool_calls = _stream_result.tool_calls
             _primary_round_tool = (
@@ -1412,6 +1421,43 @@ def run_agent_loop(
                         continue  # let it verify before finishing
                 # else: gate clean and either self-verified or already advised →
                 # fall through and accept completion.
+            if (not _blocking_question and _goal_state.goal_type == "edit_existing"
+                    and _changed_code_files(changed_files)
+                    and not ran_build_or_test(bash_history)
+                    and _completion_gate_retries < 1):
+                _completion_gate_retries += 1
+                if _append_nudge(
+                    "SYSTEM: The requested edit exists, but no relevant test, build, "
+                    "typecheck, or import check has passed. Run the narrowest "
+                    "deterministic verification now, fix failures, then finish.",
+                    kind="edit_verify_advise",
+                ):
+                    continue
+            if (not _blocking_question
+                    and _goal_state.goal_type in {"build_app", "edit_existing"}
+                    and changed_files
+                    and "relevant-verification" in _hook_state.verification_registry.requirements
+                    and _hook_state.verification_registry.satisfied("relevant-verification", os.environ)):
+                from .state_machine import TaskEvent, transition
+                _done_transition = transition("verify", TaskEvent.REQUIREMENTS_SATISFIED)
+                _announce_task_stage(_done_transition.after.value)
+            _completion_blocked = (
+                not _blocking_question
+                and _goal_state.goal_type in {"build_app", "edit_existing"}
+                and bool(_changed_code_files(changed_files))
+                and (
+                    "relevant-verification" not in _hook_state.verification_registry.requirements
+                    or not _hook_state.verification_registry.satisfied(
+                        "relevant-verification", os.environ
+                    )
+                )
+            )
+            if _completion_blocked:
+                content = (
+                    "Implementation changes were made, but LocalCode could not record "
+                    "a passing build, test, typecheck, or import check for the current "
+                    "file hashes. The task remains incomplete rather than claiming success."
+                )
             if _goal_state.goal_type == "run_or_launch":
                 _task_port = int(getattr(_task_state, "active_port", 0) or 0)
                 content = ground_run_or_launch_text(content, _task_port)
@@ -1433,7 +1479,11 @@ def run_agent_loop(
                     )
                     _render_markdown(grounded_access, app.console if hasattr(app, 'console') else None)
                     full_response.append(grounded_access)
-            _loop_exit_reason = "blocked_question" if _blocking_question else "model_done"
+            _loop_exit_reason = (
+                "blocked_question" if _blocking_question
+                else "completion_gate:unverified" if _completion_blocked
+                else "model_done"
+            )
             break
 
         # ── Execute tools ──
@@ -1631,18 +1681,10 @@ def run_agent_loop(
             # POST_REJECTION stall path nudges it to retry — model
             # doesn't just stop, it actually splits the work.
             _oversize_stub = oversize_stub_for_tool(tool_name, args, 1_000_000)
+            # edit_file already carries the exact old text as grounded context.
+            # Requiring a separate read first rejected valid one-shot edits and
+            # let small models falsely narrate success after the rejection.
             _edit_sequence_stub = None
-            if (
-                _goal_state.goal_type == "edit_existing"
-                and tool_name in {"write_file", "append_file", "edit_file", "multi_edit", "edit_diff"}
-                and not _edit_context_seen
-            ):
-                _edit_sequence_stub = (
-                    "REJECTED: edit_existing workflow requires context before patching. "
-                    "First locate the relevant files with list_files/grep/glob and read "
-                    "the target file or focused range with read_file. Then apply the "
-                    "smallest targeted edit and verify it."
-                )
 
             # HARD rewrite-stop: the churn NUDGE (limit 3) only advises — logs
             # showed a model rewrite one file 16x while 25-34 nudges fired.
@@ -1739,13 +1781,44 @@ def run_agent_loop(
             _round_tool_exec_ms += int(
                 (time.monotonic() - _tool_started_at) * 1000
             )
+            _tool_succeeded = bool(_tool_facts.get("ok", True)) and not tool_result_is_error(str(tool_result))
+            if _goal_state.goal_type in {"build_app", "edit_existing"}:
+                from .state_machine import event_for_tool, transition
+                _stage_event = event_for_tool(tool_name, succeeded=_tool_succeeded)
+                if _stage_event is not None:
+                    _stage_transition = transition(_current_task_stage_for_thinking(), _stage_event)
+                    if _stage_transition.changed:
+                        _announce_task_stage(_stage_transition.after.value)
             if tool_name == "bash":
                 _bash_cmd = str(args.get("command", ""))
                 bash_history.append((_bash_cmd, str(tool_result)))
-                if str(tool_result).startswith("[exit code ") or str(tool_result).startswith("REJECTED:"):
+                from ..execution_policy import assess_shell_execution
+                _execution = assess_shell_execution(_bash_cmd, str(tool_result), int(_tool_facts.get("exit_code", 0 if _tool_succeeded else 1)))
+                if not _execution.task_succeeded:
                     app._last_failed_tool_name = tool_name
                 else:
                     app._last_failed_tool_name = ""
+                if _goal_state.goal_type in {"build_app", "edit_existing"} and ran_build_or_test([(_bash_cmd, str(tool_result))]):
+                    from pathlib import Path as _EvidencePath
+                    from ..evidence import EvidenceRequirement
+                    _verification_files = tuple(
+                        _EvidencePath(path) if _EvidencePath(path).is_absolute()
+                        else _EvidencePath(app.repo_root) / path
+                        for path in changed_files
+                    )
+                    _hook_state.verification_registry.require(EvidenceRequirement(
+                        "relevant-verification", _verification_files, _bash_cmd,
+                        ("PATH", "NODE_ENV", "PYTHONPATH"),
+                    ))
+                    _hook_state.verification_registry.record(
+                        "relevant-verification", environment=os.environ,
+                        passed=_execution.task_succeeded, output=str(tool_result),
+                    )
+                    from .state_machine import TaskEvent, transition
+                    _verify_event = TaskEvent.VERIFICATION_PASSED if _execution.task_succeeded else TaskEvent.VERIFICATION_FAILED
+                    _verify_transition = transition(_current_task_stage_for_thinking(), _verify_event)
+                    if _verify_transition.changed:
+                        _announce_task_stage(_verify_transition.after.value)
                 if _goal_state.goal_type in {"build_app", "run_or_launch"}:
                     port = extract_port(f"{args.get('command', '')}\n{tool_result}")
                     if port:
@@ -2079,11 +2152,18 @@ def run_agent_loop(
         # counts as another re-planning round. Quiet rounds (no progress, no
         # narration) leave the streak unchanged.
         _round_changed_new_file = len(changed_files) > _changed_files_at_round_start
-        _round_ran_build = ran_build_or_test(bash_history[_bash_history_at_round_start:])
+        _round_bash = bash_history[_bash_history_at_round_start:]
+        _round_ran_build = ran_build_or_test(_round_bash)
+        # Successful setup/scaffolding is concrete progress too. The live trace
+        # incorrectly called mkdir + npm create "re-planning without progress".
+        _round_ran_successful_bash = any(
+            result and not str(result).startswith(("[exit code ", "Error:", "REJECTED:"))
+            for _cmd, result in _round_bash
+        )
         _round_had_reasoning = bool(
             (content and content.strip()) or _round_reasoning_chars > 0
         )
-        if _round_changed_new_file or _round_ran_build:
+        if _round_changed_new_file or _round_ran_build or _round_ran_successful_bash:
             _planning_streak = 0
         elif _round_had_reasoning and not _round_was_readonly:
             _planning_streak += 1

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/prompt_context.py

@@ -204,6 +204,13 @@ def build_dynamic_skills_block(
         )
 
         registry = load_registry(app.repo_root)
+        catalog = registry.listing()
+        catalog_block = (
+            "\n\n## Available Skills\n"
+            "Load a matching recipe with the skill tool; full bodies are deferred.\n"
+            + catalog
+            if catalog else ""
+        )
         recent_tools = list(getattr(app, "_recent_tool_names", []) or [])
         last_failed_tool = str(getattr(app, "_last_failed_tool_name", "") or "")
         candidates = dynamic_skill_candidates(
@@ -227,13 +234,13 @@ def build_dynamic_skills_block(
         # turns so llama.cpp's prefix-cache can hit.
         if not selected:
             return (
-                "",
+                catalog_block,
                 [],
                 [],
                 0,
                 candidates,
             )
-        block = dynamic_skill_block(selected)
+        block = catalog_block + dynamic_skill_block(selected)
         return (
             block,
             [skill.name for skill in selected],

localcode-0.3.23/src/localcode/agent/state_machine.py

@@ -0,0 +1,100 @@
+"""Deterministic lifecycle for coding tasks.
+
+The model proposes actions; the harness owns stage transitions.  Keeping this
+table outside the prompt prevents narration such as "build succeeded" from
+silently becoming completion state.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+__all__ = [
+    "TaskStage", "TaskEvent", "Transition", "normalize_stage", "transition",
+    "event_for_tool",
+]
+
+
+class TaskStage(str, Enum):
+    DISCOVER = "discover"
+    PLAN = "plan"
+    IMPLEMENT = "implement"
+    VERIFY = "verify"
+    REPAIR = "repair"
+    COMPLETE = "complete"
+    BLOCKED = "blocked"
+
+
+class TaskEvent(str, Enum):
+    CONTEXT_READY = "context_ready"
+    PLAN_READY = "plan_ready"
+    MUTATION_SUCCEEDED = "mutation_succeeded"
+    VERIFICATION_REQUESTED = "verification_requested"
+    VERIFICATION_PASSED = "verification_passed"
+    VERIFICATION_FAILED = "verification_failed"
+    REQUIREMENTS_SATISFIED = "requirements_satisfied"
+    BLOCKED = "blocked"
+
+
+_TRANSITIONS: dict[tuple[TaskStage, TaskEvent], TaskStage] = {
+    (TaskStage.DISCOVER, TaskEvent.CONTEXT_READY): TaskStage.PLAN,
+    (TaskStage.PLAN, TaskEvent.PLAN_READY): TaskStage.IMPLEMENT,
+    (TaskStage.DISCOVER, TaskEvent.MUTATION_SUCCEEDED): TaskStage.IMPLEMENT,
+    (TaskStage.PLAN, TaskEvent.MUTATION_SUCCEEDED): TaskStage.IMPLEMENT,
+    (TaskStage.IMPLEMENT, TaskEvent.MUTATION_SUCCEEDED): TaskStage.IMPLEMENT,
+    (TaskStage.IMPLEMENT, TaskEvent.VERIFICATION_REQUESTED): TaskStage.VERIFY,
+    (TaskStage.IMPLEMENT, TaskEvent.VERIFICATION_PASSED): TaskStage.VERIFY,
+    (TaskStage.IMPLEMENT, TaskEvent.VERIFICATION_FAILED): TaskStage.REPAIR,
+    (TaskStage.VERIFY, TaskEvent.VERIFICATION_FAILED): TaskStage.REPAIR,
+    (TaskStage.REPAIR, TaskEvent.MUTATION_SUCCEEDED): TaskStage.VERIFY,
+    (TaskStage.REPAIR, TaskEvent.VERIFICATION_PASSED): TaskStage.VERIFY,
+    (TaskStage.VERIFY, TaskEvent.VERIFICATION_PASSED): TaskStage.VERIFY,
+    (TaskStage.VERIFY, TaskEvent.REQUIREMENTS_SATISFIED): TaskStage.COMPLETE,
+}
+
+
+@dataclass(frozen=True)
+class Transition:
+    before: TaskStage
+    event: TaskEvent
+    after: TaskStage
+    changed: bool
+
+
+def normalize_stage(value: str | TaskStage | None) -> TaskStage:
+    raw = str(value or "").strip().lower()
+    aliases = {
+        "": TaskStage.DISCOVER,
+        "planning": TaskStage.PLAN,
+        "scaffolding": TaskStage.PLAN,
+        "running": TaskStage.IMPLEMENT,
+        "implementing": TaskStage.IMPLEMENT,
+        "verified": TaskStage.VERIFY,
+        "done": TaskStage.COMPLETE,
+    }
+    if raw in aliases:
+        return aliases[raw]
+    try:
+        return TaskStage(raw)
+    except ValueError:
+        return TaskStage.DISCOVER
+
+
+def transition(current: str | TaskStage | None, event: TaskEvent) -> Transition:
+    before = normalize_stage(current)
+    if event == TaskEvent.BLOCKED:
+        after = TaskStage.BLOCKED
+    else:
+        after = _TRANSITIONS.get((before, event), before)
+    return Transition(before=before, event=event, after=after, changed=after != before)
+
+
+def event_for_tool(tool_name: str, *, succeeded: bool, verification: bool = False) -> TaskEvent | None:
+    """Map grounded tool facts to a lifecycle event."""
+    if verification:
+        return TaskEvent.VERIFICATION_PASSED if succeeded else TaskEvent.VERIFICATION_FAILED
+    if succeeded and (tool_name or "").strip() in {
+        "write_file", "append_file", "edit_file", "multi_edit", "apply_patch", "bash",
+    }:
+        return TaskEvent.MUTATION_SUCCEEDED
+    return None

{localcode-0.3.21 → localcode-0.3.23}/src/localcode/agent/turn_finalization.py

@@ -70,6 +70,15 @@ def finalize_turn(
     """Emit turn_end and persist task/session state."""
     blocked_reason = final_text if loop_exit_reason == "blocked_question" else ""
     completion_status, task_status = status_for_exit(loop_exit_reason)
+    try:
+        hook = getattr(app, "hooks", None)
+        if hook is not None:
+            hook_result = hook.on_pre_completion(final_text, completion_status)
+            if hook_result.blocked:
+                completion_status, task_status = "stopped_early", "failed"
+                blocked_reason = hook_result.error or hook_result.output or "pre-completion hook blocked"
+    except Exception as exc:
+        _emit_finalization_error(turn_id, "pre_completion_hook", exc)
     try:
         from ..events import emit