localcode 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

localcode/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"

localcode/agent/context.py

@@ -45,6 +45,37 @@ if TYPE_CHECKING:
 __all__: list[str] = []
 
 
+def _spill_tool_output(result: str, tool_name: str) -> str | None:
+    """Write an oversized tool result to a file and return its path.
+
+    Truncation alone makes a small model re-run the command "to see the rest".
+    Instead we keep the full output on disk and point the model at it (grep/
+    read the exact part). Best-effort: None on error → caller falls back to
+    plain truncation. Content-hashed filenames; old spills reaped after 7 days.
+    """
+    try:
+        import hashlib
+        import time as _time
+        from ..paths import global_state_dir
+        spill_dir = global_state_dir() / "tool_output"
+        spill_dir.mkdir(parents=True, exist_ok=True)
+        # Reap spills older than 7 days so this never grows unbounded.
+        try:
+            cutoff = _time.time() - 7 * 86400
+            for old in spill_dir.glob("*.txt"):
+                if old.stat().st_mtime < cutoff:
+                    old.unlink(missing_ok=True)
+        except Exception:
+            pass
+        digest = hashlib.sha1(result.encode("utf-8", "replace")).hexdigest()[:12]
+        path = spill_dir / f"{tool_name}_{digest}.txt"
+        if not path.exists():
+            path.write_text(result, encoding="utf-8", errors="replace")
+        return str(path)
+    except Exception:
+        return None
+
+
 def _truncate_result(result: str, tool_name: str) -> str:
     """Truncate a tool result to its per-tool size limit with a
     strategy tuned to what each tool's output actually looks like.
@@ -70,6 +101,15 @@ def _truncate_result(result: str, tool_name: str) -> str:
         return result
 
     dropped = len(result) - limit
+    # Spill the FULL output to disk and point the model at it, so it fetches
+    # the exact part it needs instead of re-running the command to "see the
+    # rest". Appended to every strategy's hint below.
+    _spill = _spill_tool_output(result, tool_name)
+    spill_hint = (
+        f" Full output saved to {_spill} — read_file (with offset) or grep it "
+        f"to see the rest; do NOT re-run the command."
+        if _spill else ""
+    )
 
     if tool_name == "read_file":
         # Keep the HEAD; if we can find line numbers in the content
@@ -85,7 +125,7 @@ def _truncate_result(result: str, tool_name: str) -> str:
                 last_numbered = int(line.split("\t", 1)[0])
         hint = (
             f"\n\n[truncated — {dropped} more chars not shown. "
-            f"{'Call read_file with offset=' + str(last_numbered) + ' to continue reading from there.' if last_numbered else 'Call read_file with a larger offset to continue.'}]"
+            f"{'Call read_file with offset=' + str(last_numbered) + ' to continue reading from there.' if last_numbered else 'Call read_file with a larger offset to continue.'}{spill_hint}]"
         )
         return head + hint
 
@@ -99,7 +139,7 @@ def _truncate_result(result: str, tool_name: str) -> str:
         dropped_lines = result[limit:].count("\n") + 1
         hint = (
             f"\n\n[truncated — {dropped_lines} more match-lines not shown. "
-            "Narrow with a more specific pattern or `include=*.py` to see them.]"
+            f"Narrow with a more specific pattern or `include=*.py` to see them.{spill_hint}]"
         )
         return head + hint
 
@@ -114,7 +154,7 @@ def _truncate_result(result: str, tool_name: str) -> str:
             first_sig = "\n".join(non_empty[:8])
             last_sig = "\n".join(non_empty[-12:]) if len(non_empty) > 12 else ""
             marker = (
-                f"\n\n[... {dropped} chars of bash output compressed ...]\n\n"
+                f"\n\n[... {dropped} chars of bash output compressed.{spill_hint} ...]\n\n"
             )
             if any(token in result for token in ("backend", "frontend", "src/", "node_modules", "package.json", "pyproject.toml")):
                 tree_hint = (
@@ -133,14 +173,14 @@ def _truncate_result(result: str, tool_name: str) -> str:
         tail_size = limit - head_size - 64  # 64 chars for the marker line
         head = result[:head_size]
         tail = result[-tail_size:]
-        marker = f"\n\n[... {dropped} chars of middle output dropped ...]\n\n"
+        marker = f"\n\n[... {dropped} chars of middle output dropped.{spill_hint} ...]\n\n"
         return head + marker + tail
 
     # Default — middle-drop.
     half = limit // 2
     return (
         result[:half]
-        + f"\n\n[...{dropped} chars truncated...]\n\n"
+        + f"\n\n[...{dropped} chars truncated.{spill_hint} ...]\n\n"
         + result[-half:]
     )
 
@@ -205,11 +245,11 @@ def _semantic_tool_summary(content: str) -> str:
         or "Traceback " in content
     )
     if is_error:
-        tail = "\n".join([ln for ln in lines[-12:] if ln.strip()])[:1200]
-        return (
-            f"[older tool error preserved: {len(content)} chars, "
-            f"{len(lines)} lines]\n{first_line}\n{tail}"
-        )
+        # Self-conditioning (arXiv:2509.09677): echoing an OLD error's text
+        # pushes the model to repeat the mistake. Recent errors stay intact
+        # (kept above by keep_recent) so it can fix the immediate problem;
+        # older ones drop to a neutral note (the ledger still records the fact).
+        return "[an earlier tool call errored and was handled — details dropped]"
     if facts:
         return (
             f"[older successful tool result summarized: {len(content)} chars, "
@@ -684,9 +724,10 @@ def build_progress_ledger(
         return list(dict.fromkeys(s for s in seq if s))
 
     lines = [
-        "## Work already done this task — build on it. Do NOT re-read a file or "
-        "re-run a command listed below unless you have CHANGED it since; you "
-        "already have the result.",
+        "## A log of YOUR OWN tool calls so far this turn — NOT the user's work "
+        "and NOT pre-existing files on disk (leftover files you did not create are "
+        "not your progress or your task). Don't re-read/re-run anything below "
+        "unless you changed it; keep making NEW progress toward the user's goal.",
     ]
     rd = _uniq(files_read)
     if rd:

localcode/agent/loop.py

@@ -721,6 +721,19 @@ def run_agent_loop(
                     ]
             except Exception:
                 pass
+            # Inject the working-memory checklist (todo_write tool): the model
+            # always sees its own plan (done / in-progress / left) so it
+            # advances instead of repeating. Appended LAST, ephemeral, empty-safe.
+            try:
+                from ..tools.todo_write import render_todo_reminder
+                _todos = list(getattr(app.session, "todos", []) or [])
+                _todo_note = render_todo_reminder(_todos)
+                if _todo_note:
+                    model_messages = list(model_messages) + [
+                        {"role": "user", "content": _todo_note}
+                    ]
+            except Exception:
+                pass
             round_tool_schemas = schemas_for_goal(
                 _goal_state.goal_type,
                 user_text,
@@ -1206,7 +1219,11 @@ def run_agent_loop(
                 break
 
         # ── No tool calls = model is done ──
-        if not tool_calls:
+        # Also require no pending tool call: the runtime promotes pending
+        # tools into `tool_calls`, but if a future path doesn't, we keep
+        # looping instead of ending early (small models often emit a stop
+        # token with a call still pending).
+        if not tool_calls and not _round_pending_tool_count:
             # Match v0.2.12's no-tool-calls path exactly: render content,
             # render any grounded file summary, break. Nothing else.
             #

localcode/agent/prompts.py

@@ -42,11 +42,12 @@ _STACK_MARKERS: tuple[tuple[str, str], ...] = (
 SYSTEM_PROMPT = """\
 You are LocalCode, a coding agent on the user's machine with full filesystem access.
 
-Available tools: read_file, write_file, append_file, edit_file, bash, list_files.
+Available tools: read_file, write_file, append_file, edit_file, bash, list_files, todo_write.
 
 How to work:
 - Match scope to the request. Answer plain questions plainly. Build what was asked when asked. Don't write a script when a one-line bash command will do.
 - Cover every requirement the user named. If your chosen approach can't deliver one, change the approach — don't drop the requirement to fit the approach.
+- PLAN MULTI-STEP WORK. For any task with 3+ steps, call `todo_write` FIRST to lay out the steps, then keep it current: mark exactly ONE item in_progress before you start it, and mark it completed the instant it's done. Your task list is shown back to you every round — read it to see what's already finished and what's left, so you advance to the next step instead of redoing one you've already done. If you catch yourself about to re-read a file or re-run a command you ran before, check the list: you've likely already done it.
 - If the request is ambiguous in a way that affects your approach (stack, interface, scope), ask one short question before building, not after.
 - ACT, DON'T NARRATE. Every "let me read", "let me fix", "now I'll write" MUST be followed by the actual tool call IN THE SAME TURN. If you say "let me write the fix" and then end your turn without calling edit_file or write_file, you have failed the user. The user has explicitly complained about this. Never describe a fix without immediately performing it.
 - Forbidden patterns: "Let me read the file:" + end of turn. "I'll rewrite this:" + end of turn. "Now I'll apply the fix:" + end of turn. If the next thing out of your mouth is a verb of intent, the very next action MUST be the tool call that delivers on that intent.
@@ -58,6 +59,8 @@ How to work:
 - For new projects, create a small multi-file structure by default. Keep entrypoints thin; move reusable logic, styles, data/config, templates, and assets into focused files. Use one large file only if requested.
 - Prefer edit_file for existing files. Use write_file when creating a new file or doing a deliberate full rewrite.
 - When a tool returns an error, read it, fix the specific problem, and retry with DIFFERENT input. Never repeat an identical failing call: if the same call fails or returns the same result twice, change the arguments or the approach, or move on — do not loop. Don't give up after one failed call, but don't spin on it either.
+- DON'T RE-READ OR RE-SEARCH what you already have. If you already read a file this turn and it hasn't changed, the content is still above — use it, don't read it again. If a search already gave you a useful result, act on it (open the match, make the edit); don't run the same search again. Repeating a read/search you've already done is the #1 way turns stall.
+- After a tool result, CONTINUE from where you left off — don't restate what you just did or re-summarize the plan. Take the next concrete action.
 - DON'T CONFABULATE. If the user names a person, song, place, term, library, command, or concept you do not recognize, your FIRST move is to say "I don't recognize that" — NOT to invent a plausible-sounding meaning by phonetic association. Phonetic fits ("Alombasi sounds Bantu so it must be a Zambian chant", "Pyfoo sounds like a Python library so it must do X") are exactly the failure mode. If a web search would help, run it BEFORE asserting facts; if results are empty, say so plainly. Never write paragraph-length cultural/etymological/technical descriptions of something you can't actually source — "I'd love to know more, what's it from?" is the correct answer. Doubling down when the user repeats the unknown term is also forbidden; repetition is not evidence.
 
 Runtime facts (true today; rely on these instead of guessing):

localcode/agent/recovery.py

@@ -390,9 +390,11 @@ def churn_nudge_for(signal: ChurnSignal) -> str:
         )
     # INVESTIGATION_SPIN
     return (
-        "SYSTEM: You've spent several rounds reading and searching files "
-        "without taking any concrete action. You're investigating in circles. "
-        "Take a concrete action NOW: make a specific edit, run the build/tests, "
-        "or — if you genuinely lack information only the user has — ask ONE "
-        "focused question. Do not read or grep more files this round."
+        "SYSTEM: Several rounds of reading/listing/searching without WRITING "
+        "anything — you're going in circles. STOP exploring. If the task is to "
+        "build something, create the target file and write real code THIS round "
+        "with write_file/edit_file; do NOT read, ls, find, cat, or grep again. "
+        "Leftover files on disk are NOT your progress (may be an unrelated run) — "
+        "only files YOU write count. If you truly lack info only the user has, "
+        "ask ONE focused question; otherwise start writing now."
     )

localcode/entrypoint.py

@@ -22,21 +22,74 @@ _TERMINAL_RESTORE = (
     "\x1b[?25h\x1b[?1049l\x1b[0m"
 )
 
+# Snapshot of the controlling tty's termios settings, captured BEFORE the
+# TUI puts the terminal into raw mode. The escape sequence above only undoes
+# escape-driven state (alt-screen, mouse tracking, hidden cursor); it does
+# NOT undo the kernel-level raw mode (ECHO/ICANON/ISIG off). If the TUI
+# crashes or hangs and its own teardown is skipped, the terminal is left in
+# raw mode — no echo, and Ctrl+C generates no SIGINT — which looks like a
+# dead terminal. Restoring this snapshot (or `stty sane`) brings it back.
+_ORIG_TERMIOS = None  # tuple[int fd, list attrs] | None
+
+
+def _snapshot_terminal_state() -> None:
+    """Capture the tty's termios attrs before the TUI mutates them."""
+    global _ORIG_TERMIOS
+    if _ORIG_TERMIOS is not None:
+        return
+    try:
+        import termios
+        for stream in (sys.__stdin__, sys.__stdout__):
+            try:
+                if stream is not None and stream.isatty():
+                    fd = stream.fileno()
+                    _ORIG_TERMIOS = (fd, termios.tcgetattr(fd))
+                    return
+            except Exception:
+                continue
+    except Exception:
+        pass
+
 
 def _reset_terminal_state() -> None:
     payload = _TERMINAL_RESTORE.encode()
+    wrote = False
     try:
         with open("/dev/tty", "wb", buffering=0) as tty:
             tty.write(payload)
-        return
+        wrote = True
     except Exception:
         pass
+    if not wrote:
+        try:
+            if sys.__stdout__.isatty():
+                sys.__stdout__.write(_TERMINAL_RESTORE)
+                sys.__stdout__.flush()
+        except Exception:
+            pass
+    # Undo raw mode at the kernel level — escape codes can't do this. Restore
+    # the snapshot if we have one; otherwise fall back to `stty sane`. Without
+    # this, a crashed/hung TUI leaves the shell with no echo and a dead
+    # Ctrl+C until the user blindly types `reset`.
     try:
-        if sys.__stdout__.isatty():
-            sys.__stdout__.write(_TERMINAL_RESTORE)
-            sys.__stdout__.flush()
+        import termios
+        if _ORIG_TERMIOS is not None:
+            fd, attrs = _ORIG_TERMIOS
+            termios.tcsetattr(fd, termios.TCSADRAIN, attrs)
+        else:
+            raise RuntimeError("no snapshot")
     except Exception:
-        pass
+        try:
+            import subprocess
+            subprocess.run(
+                ["stty", "sane"],
+                stdin=open("/dev/tty", "rb"),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=2,
+            )
+        except Exception:
+            pass
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -248,6 +301,9 @@ def _run_headless(config, args, console) -> int:
 
 def main(argv: list[str] | None = None) -> None:
     _harden_against_debugger_attach()
+    # Snapshot the terminal while it's still sane — before the TUI enters
+    # raw mode — so any exit path (crash, hang, kill) can restore it.
+    _snapshot_terminal_state()
     import os
     import signal
     import warnings

localcode/runtime.py

@@ -242,6 +242,11 @@ class LocalCodeRuntimeGateway(_DiffusionMixin):
         self.config = config
         self._client: httpx.Client | None = None
         self.last_response_meta: dict[str, Any] = {}  # for token tracking
+        # Circuit-breaker state for the stream-recovery loop: consecutive
+        # server deaths since the last successful stream. Persists across
+        # calls/turns (this gateway is one per session) so a deterministic
+        # crash can't restart-loop forever. Reset to 0 on any success.
+        self._consecutive_stream_deaths = 0
         # llama_cpp is the only HTTP runtime (ollama/mlx/hf removed); diffusion
         # models are architecture-routed to the one-shot CLI, not this endpoint.
         base = self.config.base_url.rstrip("/")
@@ -1324,6 +1329,10 @@ class LocalCodeRuntimeGateway(_DiffusionMixin):
         # error instead of thrashing.
         _MAX_STREAM_RESTARTS = 1
         _restarts_done = 0
+        # Circuit-breaker ceiling: how many consecutive server deaths (across
+        # calls/turns, reset on any successful stream) we'll keep restarting
+        # through before declaring the server unstable and stopping the loop.
+        _MAX_CONSECUTIVE_STREAM_DEATHS = 3
         # STREAM-LEVEL "have we handed real content to the consumer yet?"
         # flag. The per-attempt `_emitted_real` is reset each try; this one
         # survives across attempts and is the streaming-safety gate for
@@ -1814,6 +1823,10 @@ class LocalCodeRuntimeGateway(_DiffusionMixin):
                         "type": "content",
                         "content": _fmt_err(_LCE(_by_code("E3108"))),
                     }
+                # Reached the end of a stream without an exception — the server
+                # answered. Clear the circuit breaker so a later transient death
+                # gets a fresh recovery budget (only CONSECUTIVE deaths count).
+                self._consecutive_stream_deaths = 0
                 yield {
                     "type": "stream_done",
                     "finish_reason": last_finish_reason,
@@ -1858,7 +1871,29 @@ class LocalCodeRuntimeGateway(_DiffusionMixin):
                 # With recovery: detect the pattern, wait for memory to
                 # settle, restart the server, retry the stream once.
                 err_str = _error_message(exc).lower()
-                is_conn_err = "connect" in err_str or "refused" in err_str
+                # Classify by EXCEPTION TYPE (with a text fallback), not a bare
+                # `"connect" in err_str` — that substring also matched httpx's
+                # RemoteProtocolError ("peer closed CONNECTION … incomplete
+                # chunked read"), but that's fine on its own; both a dead socket
+                # AND a mid-body drop are recoverable by restart. The real
+                # defect was the ABSENCE of a stop condition: a deterministic
+                # failure (an oversized request that kills the server every
+                # time) restarted + re-POSTed forever. The circuit breaker
+                # below (_consecutive_stream_deaths) bounds that.
+                try:
+                    import httpx as _httpx
+                    _is_protocol_drop = isinstance(exc, _httpx.RemoteProtocolError)
+                    _is_connect_err = isinstance(
+                        exc, (_httpx.ConnectError, _httpx.ConnectTimeout)
+                    )
+                except Exception:
+                    _is_protocol_drop = "incomplete chunked read" in err_str or "peer closed" in err_str
+                    _is_connect_err = False
+                if not _is_connect_err and not _is_protocol_drop:
+                    _is_connect_err = "connect" in err_str or "refused" in err_str
+                # Both a connect failure and a mid-stream protocol drop are
+                # "server went away" — recoverable by restart + retry.
+                is_conn_err = _is_connect_err or _is_protocol_drop
                 # Auto-recovery on connection-refused: try ONE server
                 # restart before surfacing the error to the user. Any
                 # time the server is dead (pressure-kill, OOM, crash,
@@ -1876,27 +1911,44 @@ class LocalCodeRuntimeGateway(_DiffusionMixin):
                 # e2e run 2026-04-23T23:54, long_coding_session failed
                 # 25/25 turns at 0.5 s each on a dead server).
                 _pressure_related = _pressure_kill_recent()
-                # STREAMING-SAFETY RULE: a connection drop AFTER we've already
-                # yielded real content cannot be recovered by restart+retry —
-                # re-running the stream would re-emit content the consumer
-                # already saw (double answer / corrupted turn). Restart+retry
-                # is only safe when nothing has been handed downstream yet
-                # (drop before first token). Mid-stream → surface E3102 with
-                # diagnostic context instead of silently replaying.
+                # STREAMING-SAFETY: a mid-stream drop that already yielded
+                # content may replay a partial duplicate on retry — acceptable
+                # (the recovery stage explains it) and far better than killing a
+                # turn that would otherwise self-heal (a hard E3102 here used to
+                # kill builds on a transient memory-pressure pause).
                 if is_conn_err:
-                    # Capture the disconnect class for diagnostics.
+                    # Capture the disconnect class for diagnostics (both a dead
+                    # socket and a mid-body protocol drop land here).
                     _log_disconnect_context(
-                        "stream_chat_events", exc, mid_stream=_emitted_real_stream
+                        "stream_chat_events", exc,
+                        mid_stream=_emitted_real_stream or _is_protocol_drop,
                     )
-                    # RECOVER even when content was already streamed: restart +
-                    # retry (below). The server gets paused/killed under memory
-                    # pressure mid-build and used to silently restart+continue;
-                    # hard-failing with E3102 here was a REGRESSION (turns that
-                    # used to self-heal started dying). A mid-response restart
-                    # may replay a partial duplicate of the reply — far better
-                    # than killing the whole turn. The retry path emits a clear
-                    # "restarting" stage so the duplicate is explained.
-                if is_conn_err and attempt < self.config.max_retries and _restarts_done < _MAX_STREAM_RESTARTS:
+                    # CIRCUIT BREAKER — the fix for the restart loop. Count
+                    # consecutive server deaths across calls (reset on any
+                    # successful stream, see below). A transient death recovers
+                    # on the first restart; a DETERMINISTIC one — a request too
+                    # large for the server, killing it every time — would
+                    # otherwise restart + re-POST forever. Once the deaths pile
+                    # up we stop restarting and surface actionable guidance.
+                    self._consecutive_stream_deaths = (
+                        getattr(self, "_consecutive_stream_deaths", 0) + 1
+                    )
+                    if self._consecutive_stream_deaths > _MAX_CONSECUTIVE_STREAM_DEATHS:
+                        yield {
+                            "type": "stage", "name": "server_unstable",
+                            "message": (
+                                "The model server keeps crashing on this request — "
+                                "it's likely too large for the current settings. "
+                                "Try /clear to shrink the context, or /model to "
+                                "switch to a lighter model."
+                            ),
+                        }
+                        break  # stop the restart loop; fall through to E3102
+                if (
+                    is_conn_err
+                    and attempt < self.config.max_retries
+                    and _restarts_done < _MAX_STREAM_RESTARTS
+                ):
                     _restarts_done += 1
                     recovery_label = (
                         "memory_pressure_recovery"

localcode/server_manager.py

@@ -398,23 +398,20 @@ class ServerManager:
         """
         with self._lock:
             had_prior = self._process is not None
+            _prev_model = self._model_path  # capture before shutdown clears it
             self._shutdown_locked()
-            # Wait for the OLD server's memory to actually release
-            # before spawning the new one. `process.wait()` returns
-            # when the child reaps, but the kernel may take 1-3 s to
-            # release wired Metal memory. Spawning the new ~10 GB
-            # server in that window double-commits memory and reliably
-            # triggers the pressure monitor on a 16 GB Mac (the bug
-            # behind the user's "two servers running" hypothesis).
-            #
-            # Target: enough free memory to fit a typical model + 1 GB
-            # margin (~11 GB for our standard quant). Best-effort —
-            # times out at 8 s if the target isn't met, logs the
-            # outcome, and proceeds anyway (the user wanted to switch
-            # models; refusing entirely would be worse than retry).
+            # Wait for the OLD server's memory to actually release before
+            # spawning the new one: the kernel may take 1-3 s to free wired
+            # Metal memory after the child reaps, and spawning the new ~10 GB
+            # server in that window double-commits and trips the pressure
+            # monitor on a 16 GB Mac. Best-effort — targets ~11 GB free, times
+            # out at 8 s, and proceeds anyway (refusing would be worse).
             if had_prior:
-                _lifecycle_log("memory_wait_start",
-                               reason="model_switch", target_mb=11000)
+                # Only a genuine model change is "model_switch"; a same-model
+                # relaunch (crash/disconnect recovery) is "server_restart".
+                _reason = ("model_switch" if (model_path and model_path != _prev_model)
+                           else "server_restart")
+                _lifecycle_log("memory_wait_start", reason=_reason, target_mb=11000)
                 _wait_for_memory_release(min_free_mb=11000, timeout_s=8.0)
 
             # Find a port we can actually bind to. If the default is

localcode/session.py

@@ -49,6 +49,10 @@ class SessionState:
     events: list[dict[str, str]] = field(default_factory=list)
     current_task: TaskState | None = None
     recent_tasks: list[TaskState] = field(default_factory=list)
+    # Working-memory checklist written by the todo_write tool: a list of
+    # {content, status, activeForm} dicts. Persisted so a resumed session
+    # keeps its plan; injected into context each round by the agent loop.
+    todos: list[dict] = field(default_factory=list)
 
 
 class SessionStore:
@@ -170,6 +174,7 @@ class SessionStore:
             events=list(data.get("events", [])),
             current_task=_load_task(current_task),
             recent_tasks=[task for task in (_load_task(t) for t in recent_tasks) if task is not None],
+            todos=list(data.get("todos", [])),
         )
 
     def save(self, session: SessionState) -> Path:
@@ -184,6 +189,7 @@ class SessionStore:
             "pinned_files": session.pinned_files,
             "last_assistant_text": session.last_assistant_text,
             "events": session.events,
+            "todos": session.todos,
             "current_task": None if session.current_task is None else {
                 "task_id": session.current_task.task_id,
                 "user_request": session.current_task.user_request,

localcode/tools/__init__.py

@@ -36,6 +36,7 @@ from . import (
     plan_mode,
     read_file,
     skill_tool,
+    todo_write,
     web_fetch,
     web_search,
     write_file,
@@ -60,6 +61,7 @@ _TOOLS: dict[str, tuple[dict, Callable[[ToolContext, dict], str]]] = {
     "web_search":     (web_search.SCHEMA,     web_search.execute),
     "web_fetch":      (web_fetch.SCHEMA,      web_fetch.execute),
     "skill":          (skill_tool.SCHEMA,     skill_tool.execute),
+    "todo_write":     (todo_write.SCHEMA,     todo_write.execute),
     "agent":          (agent.SCHEMA,          agent.execute),
     "enter_plan_mode": (plan_mode.ENTER_SCHEMA, plan_mode.execute_enter),
     "exit_plan_mode":  (plan_mode.EXIT_SCHEMA,  plan_mode.execute_exit),
@@ -80,6 +82,7 @@ _PUBLIC_TOOL_NAMES = [
     "web_search",
     "web_fetch",
     "skill",
+    "todo_write",
     "agent",
 ]
 
@@ -126,6 +129,9 @@ def schemas_for_goal(
         # Sub-agent — lets the model spawn focused sub-tasks (explore/plan/verify
         # /general-purpose) so it doesn't burn its own context on long searches.
         "agent",
+        # Working-memory checklist — lets the model record a plan and track
+        # done/in-progress/remaining across rounds so it stops repeating work.
+        "todo_write",
     }
     schemas = schemas_for_names(selected)
     # MCP tools — any tools exposed by user-configured MCP servers in
@@ -154,6 +160,7 @@ _MODULES = {
     "web_search": web_search,
     "web_fetch": web_fetch,
     "skill": skill_tool,
+    "todo_write": todo_write,
 }
 
 

localcode/tools/bash.py

@@ -711,6 +711,50 @@ def _normalize_repo_root_variants(cmd: str, repo: str) -> str:
     return pattern.sub(repo, cmd)
 
 
+def _quoting_error_hint(output: str) -> str:
+    """Turn a raw shell quoting failure into actionable guidance.
+
+    A path with spaces or parentheses (e.g. `Qwen 3.6 35B-A3B (Q8)`) that
+    isn't quoted breaks bash with `syntax error near unexpected token` — an
+    error a model can't act on, so it retries the same broken shape in a loop
+    (observed exactly this). Tell it precisely how to fix it.
+    """
+    low = output.lower()
+    if "syntax error near unexpected token" not in low and "unexpected eof" not in low:
+        return ""
+    return (
+        "HINT: a path or argument with spaces or parentheses wasn't quoted, so "
+        "the shell mis-parsed it. Wrap paths in SINGLE quotes — e.g. "
+        "ls -la '/Users/you/My Dir (v2)'. Simpler and safer: use list_files or "
+        "read_file with the path as an argument — they take the raw path and "
+        "never need shell escaping."
+    )
+
+
+def _redirect_shell_dir_listing(cmd: str) -> str:
+    """Route `ls <path>` to list_files, which can't break on spaces/parens.
+
+    Mirrors the `cat → read_file` guard. Only fires for a plain `ls` with a
+    PATH argument (no pipes/redirs/chains) — bare `ls`/`ls -la` in the cwd
+    can't hit the quoting failure, so it's left to run.
+    """
+    _cd, body = _extract_leading_cd(cmd)
+    b = body.strip()
+    if any(sep in b for sep in ("|", ">", "<", "&&", "||", ";", "$(", "`")):
+        return ""
+    # Path arg must NOT start with '-' (else `ls -la` reads its own flags as a path).
+    m = re.match(r"^ls((?:\s+-[a-zA-Z]+)*)\s+([^-\s].*)$", b)
+    if m is None:
+        return ""  # bare `ls`/`ls -la` (no path) — harmless, let it run
+    path = m.group(2).strip().strip('"').strip("'")
+    return (
+        f"REJECTED: use list_files(path='{path}') to inspect a directory, not "
+        "bash `ls <path>`. list_files takes the path as an argument, so it never "
+        "breaks on spaces or parentheses in a folder name — which is what fails "
+        "with bash here."
+    )
+
+
 def execute(ctx: ToolContext, args: dict) -> str:
     cmd = _normalize_repo_root_variants(args["command"], str(ctx.repo))
     # Block ANY use of process-attaching debuggers — lldb / dtrace /
@@ -776,6 +820,9 @@ def execute(ctx: ToolContext, args: dict) -> str:
     file_read_redirect = _redirect_shell_file_read(cmd, str(repo))
     if file_read_redirect:
         return file_read_redirect
+    dir_listing_redirect = _redirect_shell_dir_listing(cmd)
+    if dir_listing_redirect:
+        return dir_listing_redirect
     file_write_redirect = _redirect_shell_file_write(cmd, str(repo))
     if file_write_redirect:
         return file_write_redirect
@@ -969,6 +1016,11 @@ def execute(ctx: ToolContext, args: dict) -> str:
             pass
         if r.returncode != 0:
             output = f"[exit code {r.returncode}]\n{output}"
+            # Shell quoting failure (unquoted spaces/parens in a path) → give
+            # the model an actionable fix instead of a raw syntax error it loops on.
+            _qh = _quoting_error_hint(output)
+            if _qh:
+                output = _qh + "\n\n" + output
         # AirPlay-collision detector: if the model curls localhost:5000
         # or :7000, those are squatted by macOS AirPlay Receiver /
         # AirTunes — bare `curl -s` sees a 200 with empty body and