lcode-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-05
+
+### Added
+
+- Plan mode: a `plan` permission mode (Shift+Tab from `ask`, `/mode plan`, `lcode --plan`, or
+  `/plan <request>`) in which the model can read, search, run read-only commands, use the web and
+  read-only subagents, but can't change anything. It presents a plan with the new `present_plan`
+  tool, and you approve it (in `ask` or `auto-edit` mode), edit it, save it to `.lcode/plans/`, or
+  send it back with feedback. An approved plan fills the todo list and is kept through compaction;
+  `/plan` shows it. See [Plan mode](https://nasser1941.github.io/lcode/usage/#plan-mode).
+
+### Fixed
+
+- `lcode mcp add` shows the default value in its questions again, such as `AWS region
+  [us-east-1]`; the terminal formatting swallowed it.
+- The end-of-session "Worth remembering?" list shows each note's type (`[feedback]`, `[project]`, …),
+  which the same problem hid.
+
 ## [0.8.0] - 2026-10-05
 
 ### Added
@@ -246,7 +264,8 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/nasser1941/lcode/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/nasser1941/lcode/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/nasser1941/lcode/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/nasser1941/lcode/compare/v0.6.0...v0.6.1

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -80,6 +80,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
   Podman) that only sees your project, without network access unless you allow it.
+- **Plan mode.** `/plan <request>` or Shift+Tab: the model explores read-only and presents a plan;
+  you approve, edit or send it back before anything changes.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Subagents.** The model hands broad searches, planning and self-contained changes to subagents
@@ -195,7 +197,7 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Plan mode](https://github.com/nasser1941/lcode/issues/41) and [custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
+- [Custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
 - [Ready-made MCP for Metabase, Encord and Valohai](https://github.com/nasser1941/lcode/issues/53)
 - Then: [smarter context for small windows](https://github.com/nasser1941/lcode/issues/46), [language servers](https://github.com/nasser1941/lcode/issues/44), [a repository map with local embeddings](https://github.com/nasser1941/lcode/issues/45), [hooks](https://github.com/nasser1941/lcode/issues/43)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/README.md

@@ -46,6 +46,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
   Podman) that only sees your project, without network access unless you allow it.
+- **Plan mode.** `/plan <request>` or Shift+Tab: the model explores read-only and presents a plan;
+  you approve, edit or send it back before anything changes.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Subagents.** The model hands broad searches, planning and self-contained changes to subagents
@@ -161,7 +163,7 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Plan mode](https://github.com/nasser1941/lcode/issues/41) and [custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
+- [Custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
 - [Ready-made MCP for Metabase, Encord and Valohai](https://github.com/nasser1941/lcode/issues/53)
 - Then: [smarter context for small windows](https://github.com/nasser1941/lcode/issues/46), [language servers](https://github.com/nasser1941/lcode/issues/44), [a repository map with local embeddings](https://github.com/nasser1941/lcode/issues/45), [hooks](https://github.com/nasser1941/lcode/issues/43)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/docs/configuration.md

@@ -20,7 +20,7 @@ lcode config path                      # print the file location
 | `num_batch` | 512 | Prompt batch size. Larger reads prompts faster but needs more GPU memory |
 | `keep_alive` | `30m` | How long Ollama keeps the model in memory after the last request |
 | `ollama_host` | `http://localhost:11434` | Ollama server URL |
-| `permission_mode` | `ask` | `ask`, `auto-edit` or `yolo` |
+| `permission_mode` | `ask` | `ask`, `plan`, `auto-edit` or `yolo` |
 | `think` | `true` | Let the model reason before answering |
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/docs/how-it-works.md

@@ -89,6 +89,7 @@ the Ollama server you configure, it only contacts the web when the model searche
 | `bench.py` | `lcode bench`: the benchmark tasks, their checks and the reports |
 | `vision.py` | Looking at images with a model that can see |
 | `subagents.py` | Subagents: agent types, running them (also in parallel), worktrees for workers |
+| `planning.py` | Plan mode: what it allows, presenting a plan and approving it |
 | `memory.py` | Notes that carry over between sessions, and the end-of-session check |
 | `sandbox.py` | The optional container for shell commands |
 | `checkpoints.py` | Snapshots before the model changes files, for `/undo` and `/rewind` |

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.8.0 — local coding agent            │
+│ lcode v0.9.0 — local coding agent            │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/docs/usage.md

@@ -20,6 +20,7 @@ lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases
 | `-r, --repo DIR` | Work in another directory |
 | `-c, --continue` | Continue the most recently used session in this directory |
 | `--resume [SESSION]` | Resume a saved session: pick from a list, or give its number, name or id |
+| `--plan` | Start in [plan mode](#plan-mode): agree on a plan before anything changes |
 | `--auto-edit` | Apply file edits without asking (commands still ask) |
 | `--yolo` | Never ask for permission |
 | `--no-think` | Turn off the model's reasoning: faster, less accurate |
@@ -38,7 +39,7 @@ lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases
 | ++esc++ ++enter++ or a trailing `\` | New line |
 | ++ctrl+c++ | Interrupt the model or a running command |
 | ++ctrl+d++ | Quit |
-| ++shift+tab++ | Cycle permission mode: ask → auto-edit → yolo |
+| ++shift+tab++ | Cycle permission mode: ask → plan → auto-edit → yolo |
 | ++tab++ | Complete slash commands and `@` paths |
 | `@path` | Attach a file (or a directory listing) to your message |
 | `@name` | Ask for a [subagent](agents.md) of that type, e.g. `@plan` |
@@ -63,12 +64,13 @@ reasoning is on.
 | `/memory [show\|edit\|delete N]` | The [notes](memory.md) lcode remembers |
 | `/sandbox [network on\|off]` | The [sandbox](sandbox.md) for shell commands |
 | `/mcp [tools\|login\|restart NAME]` | [MCP servers](mcp.md), their status and tools |
+| `/plan [request]` | Work out a [plan](#plan-mode) before changing anything, or show the approved plan |
 | `/compact [focus]` | Summarize the conversation to free context |
 | `/context [size]` | Show how full the context window is and change its size: pick from a list with memory estimates, or give a size like `/context 128k` (`/ctx` is a shortcut) |
 | `/model [name]`, `/models` | Switch model, list models |
 | `/think [on\|off]` | Toggle reasoning |
 | `/verbose` | Toggle showing the reasoning text |
-| `/mode [ask\|auto-edit\|yolo]` | Set the permission mode |
+| `/mode [ask\|plan\|auto-edit\|yolo]` | Set the permission mode |
 | `/cd DIR` | Change the working directory |
 | `/todos` | Show the model's task list |
 | `/exit` | Quit |
@@ -90,6 +92,7 @@ reasoning is on.
 | `view_image` | Look at an image: a model that can see describes it ([Images](#images)) |
 | `agent` | Hand a task to a [subagent](agents.md) with its own context; only its report comes back |
 | `memory` | Save, update or delete [notes](memory.md) that later sessions load |
+| `present_plan` | In [plan mode](#plan-mode): show the plan and ask for approval |
 
 lcode refuses to edit a file the model hasn't read in the session, or one that changed on disk since
 it was read, so the model always edits the current version.
@@ -127,12 +130,16 @@ image support off with `lcode config set vision_model off`.
 | Mode | File edits | Shell commands |
 |---|---|---|
 | `ask` (default) | ask | ask, except read-only commands |
+| `plan` | refused | only read-only commands ([Plan mode](#plan-mode)) |
 | `auto-edit` | automatic | ask, except read-only commands |
 | `yolo` | automatic | automatic |
 
+++shift+tab++ cycles through them in this order, `/mode` sets one, and `--plan`, `--auto-edit` and
+`--yolo` start in one.
+
 Read-only commands run without asking: `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `find`, `tree`,
 `wc`, `diff`, `git status/log/diff/show/branch/blame` and similar, as long as they don't redirect
-output, chain commands or run subshells.
+output, chain commands or run subshells. A `cd <folder> &&` in front is fine.
 
 When asked, answer ++y++ (once), ++a++ (always, for this command or for all edits, until you quit)
 or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests with -x first`.
@@ -146,6 +153,42 @@ or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests w
 With the [sandbox](sandbox.md) on, `auto-edit` mode runs shell commands without asking too: they can
 only reach the project, and `/undo` can take their changes back.
 
+## Plan mode
+
+Local models are slower than cloud models and make more mistakes, so on a bigger change it pays to
+agree on the approach before the model starts editing. In **plan mode** the model can read, search,
+run read-only commands, use the web and [explore and plan subagents](agents.md), but it can't
+change anything. It ends by presenting a plan: numbered steps, the files it will change, the risks
+and how it will verify the work.
+
+```text
+❯ /plan add retries to the webhook handlers
+  …
+╭─ Plan: Retries for webhook handlers ───────────────────────────────────────────╮
+│ 1. Wrap the HTTP call in payments/webhooks.py:88 in a retry loop (3 tries, …)  │
+│ 2. Add tests for a timeout and a 500 in tests/test_webhooks.py                 │
+│ Risks: duplicate deliveries if the endpoint isn't idempotent …                 │
+│ Verify: pytest tests/test_webhooks.py                                          │
+╰────────────────────────────────────────────────────────────────────────────────╯
+  [y] run it, asking before changes · [a] run it, edits without asking (auto-edit)
+  [e] edit the plan · [s] save it to .lcode/plans/ · [n] keep planning (+ what to change)
+  >
+```
+
+| Answer | |
+|---|---|
+| ++y++ or ++enter++ | Approve: lcode switches to `ask` mode and the model starts on the plan right away |
+| ++a++ | Approve and switch to `auto-edit`, so file edits don't ask |
+| ++e++ | Edit the plan in your editor first; the model follows your version |
+| ++s++ | Save it as `.lcode/plans/<title>.md`, for example to share it or commit it |
+| ++n++ + text | Send it back: `n keep the old API working` |
+
+After approval, the todo list is filled from the plan's numbered steps, and the plan is kept word
+for word when the conversation is compacted. `/plan` shows the approved plan.
+
+Start planning with `/plan <request>` (switches to plan mode and sends the request), with
+++shift+tab++ (one step from `ask`), or with `lcode --plan`.
+
 ## Undo and checkpoints
 
 Before the model first changes anything in a request (an edit, a new file, or a shell command that

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/pyproject.toml

@@ -71,6 +71,7 @@ ignore = [
 "src/lcode/agent.py" = ["E501"] # the prompts are prose; wrapping them would change what the model sees
 "src/lcode/memory.py" = ["E501"]
 "src/lcode/subagents.py" = ["E501"]
+"src/lcode/planning.py" = ["E501"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/__init__.py

@@ -1,3 +1,3 @@
 """lcode — a local-first terminal coding agent powered by open-weight models via Ollama."""
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/agent.py

@@ -21,7 +21,7 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, limits, sessions, subagents, vision, web
+from lcode import catalog, limits, planning, sessions, subagents, vision, web
 from lcode import memory as memory_notes
 from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
@@ -32,6 +32,7 @@ from lcode.render import MarkdownStreamer
 from lcode.sandbox import Sandbox, SandboxError, project_root
 from lcode.tools import (
     MEMORY_SCHEMA,
+    PRESENT_PLAN_SCHEMA,
     SCHEMAS,
     VIEW_IMAGE_SCHEMA,
     WEB_FETCH_SCHEMA,
@@ -198,6 +199,7 @@ class Agent:
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
         self.agent_runs: list[subagents.Record] = []  # subagents run in this session, for /agents
+        self.plan = ""  # the plan the user approved; kept through compaction
         # Set on subagents (see lcode.subagents):
         self.allowed_tools: set[str] | None = None  # None: every tool
         self.read_only = False  # only read-only shell commands
@@ -259,6 +261,9 @@ class Agent:
         assert self._agent_types is not None
         return self._agent_types[2]
 
+    def planning(self) -> bool:
+        return self.perms.mode == "plan"
+
     def tool_names(self) -> set[str]:
         return {s["function"]["name"] for s in self.tool_schemas()}
 
@@ -283,6 +288,8 @@ class Agent:
             schemas.append(MEMORY_SCHEMA)
         if self.settings.subagents:
             schemas.append(subagents.schema(self.agent_types(), self.settings.max_parallel_agents))
+        if self.planning():
+            schemas.append(PRESENT_PLAN_SCHEMA)
         if self.mcp:
             schemas += self.mcp.schemas(self.settings.context)
         if self.allowed_tools is not None:
@@ -638,7 +645,8 @@ class Agent:
 
     def _run_turn(self, user_text: str, max_steps: int = MAX_STEPS_PER_TURN) -> None:
         self.prepare_mcp()
-        self.messages.append({"role": "user", "content": self.expand_mentions(user_text)})
+        note = planning.NOTE if self.planning() and self.allowed_tools is None else ""
+        self.messages.append({"role": "user", "content": self.expand_mentions(user_text) + note})
         malformed = 0
         for _ in range(max_steps):
             if self.cancel is not None and self.cancel.is_set():
@@ -777,6 +785,8 @@ class Agent:
             {"role": "user", "content": f"[Summary of our conversation so far]\n\n{summary}"},
             {"role": "assistant", "content": "Got it — I have the context from the summary and will continue."},
         ]
+        if self.plan:  # the approved plan stays word for word
+            self.messages[1]["content"] += f"\n\n[The plan the user approved; keep following it]\n\n{self.plan}"
         self.ctx_used = sum(len(m["content"]) for m in self.messages) // 3
         self.reflected = len(self.messages)
         self.console.print(Panel(Markdown(summary), title="Compacted summary", border_style="blue"))

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/cli.py

@@ -519,7 +519,9 @@ def cmd_chat(args) -> None:
     context, note = choose_context(ollama, model, spec, requested_ctx, hw)
     if note:
         console.print(f"[yellow]Context {format_tokens(context)}: {note}[/]")
-    mode = "yolo" if args.yolo else ("auto-edit" if args.auto_edit else cfg["permission_mode"])
+    mode = (
+        "yolo" if args.yolo else ("auto-edit" if args.auto_edit else ("plan" if args.plan else cfg["permission_mode"]))
+    )
     num_batch = cfg["num_batch"]
     if num_batch is None and spec and spec.num_batch:
         if model == spec.local_name:
@@ -589,6 +591,7 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="SESSION",
         help="resume a saved session: pick from a list, or give its number, name or id",
     )
+    parser.add_argument("--plan", action="store_true", help="start in plan mode: agree on a plan before any change")
     parser.add_argument("--auto-edit", action="store_true", help="apply file edits without asking")
     parser.add_argument("--yolo", action="store_true", help="never ask for permission (edits and commands)")
     parser.add_argument("--no-think", action="store_true", help="disable model reasoning (faster, less accurate)")

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/config.py

@@ -21,7 +21,7 @@ else:
     STATE_DIR = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state") / "lcode"
 
 DEFAULT_MODEL = "qwen3.6-35b"
-PERMISSION_MODES = ("ask", "auto-edit", "yolo")
+PERMISSION_MODES = ("ask", "plan", "auto-edit", "yolo")  # Shift+Tab cycles in this order
 WEB_MODES = ("on", "ask", "off")
 SEARCH_BACKENDS = ("auto", "ollama", "brave", "tavily", "searxng")
 MCP_TOOL_MODES = ("auto", "direct", "search")
@@ -35,7 +35,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "num_batch": (None, int, "prompt batch size; larger reads prompts faster but needs more VRAM"),
     "keep_alive": ("30m", str, "how long Ollama keeps the model loaded after the last request"),
     "ollama_host": ("http://localhost:11434", str, "Ollama server URL"),
-    "permission_mode": ("ask", str, "ask | auto-edit | yolo"),
+    "permission_mode": ("ask", str, "ask | plan | auto-edit | yolo"),
     "think": (True, bool, "let the model reason before answering (slower, better)"),
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/mcp/commands.py

@@ -216,9 +216,9 @@ def _ask(spec: catalog.Input, console: Console) -> str | None:
         source = " ".join(spec.from_command)
         if Confirm.ask(f"  Use the token from `{source}`?", default=True, console=console):
             return suggestion
-    default = f" [{spec.default}]" if spec.default else ""
+    default = f" \\[{escape(spec.default)}]" if spec.default else ""  # escaped, or rich takes it for markup
     while True:
-        value = console.input(f"  {spec.prompt}{default}: ", password=spec.secret).strip()
+        value = console.input(f"  {escape(spec.prompt)}{default}: ", password=spec.secret).strip()
         value = value or spec.default or ""
         if value or spec.optional:
             return value or None

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/memory.py

@@ -507,7 +507,7 @@ def reflect(agent: Agent) -> None:
             where = "every repository" if note.scope == "user" else "this repository"
             update = memory.find(note.name, note.scope)
             rows.append(
-                f"[cyan]{i}[/] [{note.type}] {escape(note.description)} [dim]({where}"
+                f"[cyan]{i}[/] \\[{note.type}] {escape(note.description)} [dim]({where}"
                 f"{', updates ' + escape(update.name) if update else ''})[/]"
                 + (f"\n    [dim]{escape(note.details)}[/]" if note.details else "")
             )

lcode_cli-0.9.0/src/lcode/planning.py

@@ -0,0 +1,138 @@
+"""Plan mode: agree on an approach before anything changes.
+
+In the `plan` permission mode the model can read, search, run read-only commands, use the web and
+read-only subagents, but can't change anything. It ends by presenting a plan with the
+present_plan tool. The user approves it (lcode switches to `ask` or `auto-edit`, fills the todo
+list from the plan's steps and keeps the plan through compaction), edits it, saves it to
+`.lcode/plans/`, or sends it back with feedback.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.markdown import Markdown
+from rich.markup import escape
+from rich.panel import Panel
+
+from lcode.checkpoints import work_tree_for
+from lcode.memory import slugify
+
+if TYPE_CHECKING:
+    from lcode.agent import Agent
+
+# Tools that can't change anything (bash is limited to read-only commands, agent to read-only types).
+PLAN_MODE_TOOLS = frozenset(
+    {
+        "read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write",
+        "agent", "memory", "present_plan", "mcp_find_tools",
+    }
+)  # fmt: skip
+
+NOTE = """
+
+[lcode] Plan mode is on: you can read, search, run read-only commands, use the web and read-only subagents, but you can't change anything yet. Work out how to do this, then call present_plan with: numbered steps, the files you'll change and how, the risks, and how you'll verify the result. Ask the user only about decisions that are genuinely theirs."""
+
+BLOCKED = (
+    "Plan mode is on, so nothing can be changed yet. Finish working out the plan and present it with "
+    "present_plan; once the user approves it, you can make the changes."
+)
+
+CHOICES = (
+    "  [bold]\\[y][/] run it, asking before changes · [bold]\\[a][/] run it, edits without asking (auto-edit)\n"
+    "  [bold]\\[e][/] edit the plan · [bold]\\[s][/] save it to .lcode/plans/ · [bold]\\[n][/] keep planning (+ what to change)"
+)
+
+
+def steps(plan: str, limit: int = 20) -> list[str]:
+    """The plan's numbered steps (top level only), for the todo list."""
+    found = []
+    for line in plan.splitlines():
+        m = re.match(r"^ {0,3}\d+[.)]\s+(.+)", line)
+        if m:
+            # Plain text for the todo list: no bold, code or emphasis marks (underscores in names stay).
+            text = m.group(1).replace("**", "").replace("__", "").replace("`", "")
+            text = re.sub(r"(?<!\w)[*_]([^*_]+)[*_](?!\w)", r"\1", text).strip().rstrip(":").strip()
+            found.append(text if len(text) <= 120 else text[:119].rstrip() + "…")
+    return found[:limit]
+
+
+def edit_text(text: str) -> str:
+    """Let the user edit `text` in their editor; returns the result."""
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR") or ("nano" if shutil.which("nano") else "vi")
+    with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False) as f:
+        f.write(text)
+        path = Path(f.name)
+    try:
+        subprocess.call([*shlex.split(editor), str(path)])
+        return path.read_text()
+    finally:
+        path.unlink(missing_ok=True)
+
+
+def save(agent: Agent, title: str, plan: str) -> Path:
+    folder = work_tree_for(agent.cwd) / ".lcode" / "plans"
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / f"{slugify(title) or 'plan'}.md"
+    path.write_text(f"# {title}\n\n{plan.strip()}\n")
+    return path
+
+
+def present(agent: Agent, title: str, plan: str) -> str:
+    """Show the plan and let the user decide. Returns the tool result for the model."""
+    c = agent.console
+    title = " ".join(title.split()) or "Plan"
+    plan = plan.strip()
+    if not plan:
+        return "Error: the plan is empty. Write the steps, the files, the risks and how you'll verify the work."
+    edited = False
+    while True:
+        c.print(Panel(Markdown(plan), title=f"Plan: {escape(title)}", title_align="left", border_style="cyan"))
+        if not agent.interactive:
+            return "The plan was shown to the user, who will review it later. Stop here and don't change anything."
+        c.print(CHOICES)
+        try:
+            answer = input("  > ").strip()
+        except EOFError:
+            return "The plan was shown to the user, who will review it later. Stop here and don't change anything."
+        word = answer.lower()
+        if word in ("", "y", "yes"):
+            return approve(agent, title, plan, "ask", edited)
+        if word in ("a", "auto", "auto-edit"):
+            return approve(agent, title, plan, "auto-edit", edited)
+        if word in ("e", "edit"):
+            new = edit_text(plan).strip()
+            if new and new != plan:
+                plan, edited = new, True
+            continue
+        if word in ("s", "save"):
+            path = save(agent, title, plan)
+            c.print(f"[green]Saved to {escape(agent.tools.rel(path))}[/]")
+            continue
+        feedback = re.sub(r"^(no|n)\b[\s,:-]*", "", answer, flags=re.I).strip()
+        if feedback:
+            return f"The user wants changes to the plan: {feedback}\nStay in plan mode: revise the plan and present it again."
+        return "The user didn't approve the plan. Ask them what they'd like to change."
+
+
+def approve(agent: Agent, title: str, plan: str, mode: str, edited: bool) -> str:
+    agent.perms.mode = mode
+    agent.plan = f"# {title}\n\n{plan}"
+    todo = steps(plan)
+    if todo:
+        agent.tools.todos = [{"content": step, "status": "pending"} for step in todo]
+        agent.tools.show_todos()
+    how = "file edits no longer ask (auto-edit)" if mode == "auto-edit" else "changes ask for approval as usual"
+    agent.console.print(f"[green]Plan approved.[/] Mode: {mode} — {how}.")
+    result = f"The user approved the plan, and plan mode is off ({mode} mode: {how}). Carry it out now, step by step"
+    result += ", keeping the todo list up to date." if todo else "."
+    if edited:
+        result += f"\nThe user edited the plan first. This is the approved version:\n\n{plan}"
+    return result

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/repl.py

@@ -18,6 +18,7 @@ from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.key_binding import KeyBindings
 from rich.console import Group
+from rich.markdown import Markdown
 from rich.markup import escape
 from rich.panel import Panel
 from rich.rule import Rule
@@ -55,7 +56,8 @@ COMMANDS = {
     "/models": "List models and how they fit this machine",
     "/think": "Toggle model reasoning on/off",
     "/verbose": "Toggle showing the model's reasoning text",
-    "/mode": "Permission mode: ask | auto-edit | yolo (Shift+Tab cycles)",
+    "/plan": "Plan before changing anything: /plan <request>, or /plan to show the approved plan",
+    "/mode": "Permission mode: ask | plan | auto-edit | yolo (Shift+Tab cycles)",
     "/cd": "Change the working directory",
     "/todos": "Show the current todo list",
     "/exit": "Quit",
@@ -118,7 +120,7 @@ def build_session(agent: Agent) -> PromptSession:
     def toolbar():
         s = agent.settings
         pct = 100 * agent.ctx_used / s.context
-        color = {"ask": "ansigreen", "auto-edit": "ansiyellow", "yolo": "ansired"}[agent.perms.mode]
+        color = {"ask": "ansigreen", "plan": "ansicyan", "auto-edit": "ansiyellow", "yolo": "ansired"}[agent.perms.mode]
         return HTML(
             f" <b>{html.escape(s.model)}</b> · ctx {format_tokens(agent.ctx_used)}/{format_tokens(s.context)} "
             f"({pct:.0f}%) · mode <{color}>{agent.perms.mode}</{color}> (shift+tab) · "
@@ -772,6 +774,20 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
     elif cmd == "/verbose":
         s.show_thinking = not s.show_thinking
         c.print(f"Showing reasoning text: {'on' if s.show_thinking else 'off'}.")
+    elif cmd == "/plan":
+        if not arg:
+            if agent.plan:
+                c.print(Panel(Markdown(agent.plan), title="Approved plan", title_align="left", border_style="cyan"))
+            else:
+                c.print(
+                    "No approved plan in this session. [bold]/plan <request>[/] works out a plan first, without "
+                    "changing anything (or Shift+Tab to plan mode)."
+                )
+            return True
+        agent.perms.mode = "plan"
+        c.print("[cyan]Plan mode:[/] the model can look around but not change anything until you approve its plan.")
+        c.print(Rule(style="dim"))
+        run_safely(agent, arg)
     elif cmd == "/mode":
         if arg in PERMISSION_MODES:
             agent.perms.mode = arg

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/src/lcode/tools.py

@@ -24,6 +24,7 @@ from rich.text import Text
 
 from lcode import web
 from lcode.permissions import bash_key, is_read_only
+from lcode.planning import BLOCKED, PLAN_MODE_TOOLS
 from lcode.sandbox import SandboxError
 from lcode.vision import is_image
 
@@ -198,8 +199,22 @@ MEMORY_SCHEMA = _fn(
     },
     ["action"],
 )
+PRESENT_PLAN_SCHEMA = _fn(
+    "present_plan",
+    "Plan mode: show the user your plan and ask for approval. Once approved, plan mode ends and you carry it out.",
+    {
+        "title": {"type": "string", "description": "A short name for the plan, e.g. 'Add retries to webhooks'"},
+        "plan": {
+            "type": "string",
+            "description": "Markdown: numbered steps, the files you'll change and how, the risks, and how you'll "
+            "verify the result",
+        },
+    },
+    ["title", "plan"],
+)
 TOOL_NAMES = {
-    s["function"]["name"] for s in [*SCHEMAS, WEB_SEARCH_SCHEMA, WEB_FETCH_SCHEMA, VIEW_IMAGE_SCHEMA, MEMORY_SCHEMA]
+    s["function"]["name"]
+    for s in [*SCHEMAS, WEB_SEARCH_SCHEMA, WEB_FETCH_SCHEMA, VIEW_IMAGE_SCHEMA, MEMORY_SCHEMA, PRESENT_PLAN_SCHEMA]
 }
 
 
@@ -337,6 +352,10 @@ class Toolbox:
         allowed = self.agent.allowed_tools
         if allowed is not None and name not in allowed:
             return f"Error: {name} isn't available to you. Available: {', '.join(sorted(allowed))}"
+        if self.agent.planning() and name not in PLAN_MODE_TOOLS:
+            return f"Error: {BLOCKED}"
+        if name == "present_plan" and not self.agent.planning():
+            return "Error: plan mode is off, so there's nothing to present: carry on with the work."
         if self.agent.mcp and self.agent.mcp.owns(name):
             return self._mcp(name, args)
         fn = getattr(self, f"t_{name}", None)
@@ -376,8 +395,17 @@ class Toolbox:
             raise ToolError("subagents are turned off")
         from lcode import subagents
 
+        kind = self.agent.agent_types().get(type)
+        if self.agent.planning() and kind and not kind.read_only:
+            raise ToolError(f"plan mode is on: only read-only agents can run now ({BLOCKED})")
         return subagents.run_one(self.agent, {"type": type, "task": task, "description": description})
 
+    # -- plan mode
+    def t_present_plan(self, title: str, plan: str) -> str:
+        from lcode.planning import present
+
+        return present(self.agent, title, plan)
+
     # -- memory
     def t_memory(
         self, action: str, name: str = "", type: str = "", description: str = "", details: str = "", scope: str = ""
@@ -605,6 +633,8 @@ class Toolbox:
     # -- shell
     def t_bash(self, command: str, timeout: int = 180) -> str:
         sandbox = self.agent.sandbox
+        if self.agent.planning() and not is_read_only(command):
+            raise ToolError(f"{BLOCKED} Until then, only read-only commands run (ls, cat, grep, git log, …).")
         if self.agent.read_only and not is_read_only(command):
             raise ToolError(
                 "you can only run read-only commands (such as ls, cat, grep, find, git log, git diff), one at a "

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/tests/test_mcp.py

@@ -556,3 +556,18 @@ def test_gpu_tools_run_to_completion(make_agent, tmp_path, monkeypatch):
     agent.run_turn("make an image")
     assert sent == [{"a": 1, "b": 2, "wait": True}]
     agent.mcp.close()
+
+
+def test_input_prompts_show_their_default(monkeypatch):
+    import io
+
+    from rich.console import Console
+
+    from lcode.mcp.catalog import Input
+    from lcode.mcp.commands import _ask
+
+    console = Console(file=io.StringIO(), force_terminal=False)
+    monkeypatch.delenv("AWS_REGION", raising=False)
+    monkeypatch.setattr("builtins.input", lambda *args: "")
+    assert _ask(Input("AWS_REGION", "AWS region", default="us-east-1"), console) == "us-east-1"
+    assert "AWS region [us-east-1]: " in console.file.getvalue()  # not swallowed as rich markup

{lcode_cli-0.8.0 → lcode_cli-0.9.0}/tests/test_memory.py

@@ -246,6 +246,7 @@ def test_reflection_with_memory_ask_saves_only_what_the_user_picks(make_agent, m
     answers(monkeypatch, "2")
     memory_notes.reflect(agent)
     assert [n.name for n in agent.memory().notes()] == ["vpn"]
+    assert "1 [feedback] Use pnpm, not npm (this repository)" in output(agent)
 
 
 def test_reflection_with_memory_ask_saves_nothing_without_approval(make_agent, monkeypatch):

lcode_cli-0.9.0/tests/test_plan_mode.py

@@ -0,0 +1,161 @@
+import io
+
+from rich.console import Console
+
+from conftest import output, reply
+from lcode import config, planning
+from lcode.hardware import Hardware
+from lcode.permissions import Permissions
+from lcode.repl import handle_command
+
+HW = Hardware("linux", "x", 31, "GPU", 12)
+PLAN = (
+    "1. Add `mul` to **src/pkg/math.py**\n2. Test it\n   - with negative numbers\n\n"
+    "Risks: none.\nVerify: run the tests."
+)
+
+
+def tool(name, **arguments):
+    return {"function": {"name": name, "arguments": arguments}}
+
+
+def answers(monkeypatch, *replies):
+    queue = list(replies)
+    monkeypatch.setattr("builtins.input", lambda prompt="": queue.pop(0))
+
+
+def present(title="Add mul", plan=PLAN):
+    return tool("present_plan", title=title, plan=plan)
+
+
+def test_plan_mode_blocks_every_change(make_agent, repo):
+    agent = make_agent(
+        [
+            reply(
+                tool_calls=[
+                    tool("read_file", path="README.md"),
+                    tool("bash", command="cd src && ls"),
+                    tool("edit_file", path="README.md", old_string="Demo", new_string="X"),
+                    tool("write_file", path="new.txt", content="x"),
+                    tool("bash", command="touch made"),
+                    tool("agent", type="worker", task="change things"),
+                ]
+            ),
+            reply("Here's what I found."),
+        ],
+        mode="plan",
+        subagents=True,
+    )
+    agent.run_turn("add mul")
+    assert agent.messages[1]["content"].endswith(planning.NOTE)
+    assert "present_plan" in {t["function"]["name"] for t in agent.ollama.payloads[0]["tools"]}
+    results = [m["content"] for m in agent.messages if m["role"] == "tool"]
+    assert "# Demo" in results[0] and "pkg" in results[1]
+    assert all("Plan mode is on" in r for r in results[2:]), results[2:]
+    assert (repo / "README.md").read_text() == "# Demo\n"
+    assert not (repo / "new.txt").exists() and not (repo / "made").exists()
+
+
+def test_approving_a_plan_switches_mode_and_fills_the_todo_list(make_agent, repo, monkeypatch):
+    agent = make_agent(
+        [
+            reply(tool_calls=[present()]),
+            reply(tool_calls=[tool("write_file", path="new.txt", content="x\n")]),
+            reply("Done."),
+        ],
+        mode="plan",
+    )
+    answers(monkeypatch, "a")
+    agent.run_turn("add mul")
+    assert agent.perms.mode == "auto-edit"
+    assert "[y] run it, asking before changes · [a] run it, edits without asking" in output(agent)
+    assert agent.plan.startswith("# Add mul\n\n1. Add `mul`")
+    assert agent.tools.todos == [
+        {"content": "Add mul to src/pkg/math.py", "status": "pending"},
+        {"content": "Test it", "status": "pending"},
+    ]
+    assert agent.messages[3]["content"].startswith("The user approved the plan, and plan mode is off (auto-edit mode")
+    assert (repo / "new.txt").read_text() == "x\n"  # carried out in the same request
+    assert "present_plan" not in {t["function"]["name"] for t in agent.ollama.payloads[1]["tools"]}
+
+
+def test_y_approves_in_ask_mode(make_agent, monkeypatch):
+    agent = make_agent([reply(tool_calls=[present()]), reply("Starting.")], mode="plan")
+    answers(monkeypatch, "")
+    agent.run_turn("add mul")
+    assert agent.perms.mode == "ask"
+    assert "(ask mode: changes ask for approval as usual)" in agent.messages[3]["content"]
+
+
+def test_a_plan_sent_back_with_feedback_stays_in_plan_mode(make_agent, monkeypatch):
+    agent = make_agent([reply(tool_calls=[present()]), reply("I'll revise it.")], mode="plan")
+    answers(monkeypatch, "add tests for overflow too")  # starts with "a", but isn't an approval
+    agent.run_turn("add mul")
+    assert agent.perms.mode == "plan" and agent.plan == ""
+    assert agent.messages[3]["content"].startswith("The user wants changes to the plan: add tests for overflow too")
+
+
+def test_edit_and_save_a_plan_before_approving(make_agent, repo, monkeypatch):
+    agent = make_agent([reply(tool_calls=[present()]), reply("Starting.")], mode="plan")
+    monkeypatch.setattr(planning, "edit_text", lambda text: text.replace("Test it", "Test it twice"))
+    answers(monkeypatch, "e", "s", "y")
+    agent.run_turn("add mul")
+    saved = repo / ".lcode" / "plans" / "add-mul.md"
+    assert "Test it twice" in saved.read_text()
+    result = agent.messages[3]["content"]
+    assert "The user edited the plan first" in result and "2. Test it twice" in result
+    assert agent.tools.todos[1]["content"] == "Test it twice"
+
+
+def test_without_a_terminal_the_plan_waits_for_review(make_agent):
+    agent = make_agent([reply(tool_calls=[present()]), reply("Waiting.")], mode="plan")
+    agent.interactive = False
+    agent.run_turn("add mul")
+    assert agent.perms.mode == "plan"
+    assert "review it later" in agent.messages[3]["content"]
+
+
+def test_present_plan_outside_plan_mode_is_refused(make_agent):
+    agent = make_agent([reply(tool_calls=[present()]), reply("ok")], mode="ask")
+    agent.run_turn("go")
+    assert agent.messages[3]["content"].startswith("Error: plan mode is off")
+    assert "present_plan" not in {t["function"]["name"] for t in agent.ollama.payloads[0]["tools"]}
+
+
+def test_the_approved_plan_survives_compaction(make_agent):
+    agent = make_agent([reply("ok"), reply("Summary.")])
+    agent.run_turn("hi")
+    agent.plan = "# Add mul\n\n1. Add it"
+    agent.compact()
+    assert agent.messages[1]["content"].endswith(
+        "[The plan the user approved; keep following it]\n\n# Add mul\n\n1. Add it"
+    )
+
+
+def test_plan_command(make_agent, monkeypatch):
+    agent = make_agent([reply(tool_calls=[present()]), reply("Starting.")], mode="ask")
+    handle_command(agent, "/plan", HW)
+    assert "No approved plan" in output(agent)
+    answers(monkeypatch, "y")
+    handle_command(agent, "/plan add mul", HW)
+    assert agent.messages[1]["content"].startswith("add mul") and planning.NOTE in agent.messages[1]["content"]
+    assert agent.perms.mode == "ask"
+    handle_command(agent, "/plan", HW)
+    assert "Approved plan" in output(agent)
+
+
+def test_shift_tab_reaches_plan_mode_first():
+    perms = Permissions(Console(file=io.StringIO()), "ask")
+    seen = []
+    for _ in range(4):
+        perms.cycle()
+        seen.append(perms.mode)
+    assert seen == ["plan", "auto-edit", "yolo", "ask"]
+    assert config.coerce("permission_mode", "plan") == "plan"
+
+
+def test_steps_come_from_the_numbered_lines():
+    assert planning.steps(PLAN) == ["Add mul to src/pkg/math.py", "Test it"]
+    real = "1. **`calc.py`** — add a `div(a, b)` function after `mul`:\n2. **`test_calc.py`** — add *two* tests:"
+    assert planning.steps(real) == ["calc.py — add a div(a, b) function after mul", "test_calc.py — add two tests"]
+    assert planning.steps("No numbers here") == []