lcode-cli 0.27.0__py3-none-any.whl → 0.28.1__py3-none-any.whl

lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.27.0"
+__version__ = "0.28.1"
 
 API = ("Session", "Result", "Options", "SetupError")
 

lcode/agent.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import base64
+import contextlib
 import datetime as dt
 import json
+import os
 import platform
 import re
 import shutil
@@ -23,7 +25,20 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, codesearch, extensions, limits, notify, planning, repomap, sessions, subagents, vision, web
+from lcode import (
+    catalog,
+    codesearch,
+    extensions,
+    limits,
+    notify,
+    planning,
+    repomap,
+    residency,
+    sessions,
+    subagents,
+    vision,
+    web,
+)
 from lcode import context as context_tools
 from lcode import memory as memory_notes
 from lcode.checkpoints import Checkpoints
@@ -53,7 +68,12 @@ from lcode.tools import (
     truncate,
 )
 
-GPU_MEMORY_ERRORS = ("out of memory", "illegal memory access", "cudamalloc failed")
+GPU_MEMORY_ERRORS = (
+    "out of memory",
+    "illegal memory access",
+    "cudamalloc failed",
+    "requires more system memory",  # Ollama: the model and its context don't fit in RAM either
+)
 SAFE_NUM_BATCH = 512  # Ollama's default prompt batch
 MAX_STEPS_PER_TURN = 150
 EVENT_OUTPUT = 4000  # characters of a tool's output in an event
@@ -62,6 +82,9 @@ REFUSED = ("Error:", "A deny rule", "The user denied", "This needs the user's pe
 MAX_MALFORMED_CALL_RETRIES = 2  # Ollama rejects tool calls whose arguments aren't valid JSON
 # How Ollama reports a tool call it couldn't parse (Qwen3.6's calls are XML)
 MALFORMED_CALL = ("error parsing tool call", "XML syntax error")
+RESULT_SHARE = 0.25  # of the context window, at most, for one tool result
+MIN_RESULT_CHARS = 8000
+READING_NOTE_TOKENS = 4000  # new input this large gets "Reading … new tokens" in the status line
 AUTO_COMPACT_RATIO = 0.85  # summarize the history when the context is this full
 PRUNED_ENOUGH = 0.6  # after pruning old tool output, summarize only if the context is still this full
 # @path, @"path with spaces" or @'path'
@@ -171,6 +194,10 @@ def project_root_or_cwd(cwd: Path) -> Path:
     return work_tree_for(cwd)
 
 
+def conversation_chars(messages: list[dict]) -> int:
+    return sum(len(str(m.get("content") or "")) + len(str(m.get("thinking") or "")) for m in messages)
+
+
 def call_arguments(call: dict) -> dict:
     """A tool call's arguments as a dict (some models send them as a JSON string)."""
     args = call.get("function", {}).get("arguments") or {}
@@ -189,17 +216,22 @@ class Progress:
     arrives, for example while the model writes a long file into a tool call.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, phase: str = "Thinking") -> None:
         self.started = self.last_chunk = time.time()
-        self.phase = "Thinking"
+        self.phase = phase
         self.chars = 0
 
     def update(self, phase: str, text: str) -> None:
         self.phase, self.chars, self.last_chunk = phase, self.chars + len(text), time.time()
 
+    def set_phase(self, phase: str) -> None:
+        """What happens before the first token: loading the model, reading the prompt."""
+        self.phase, self.last_chunk = phase, time.time()
+
     def __rich__(self) -> Text:
         now = time.time()
-        phase = self.phase if now - self.last_chunk < 3 else "Working"
+        streaming = self.phase in ("Thinking", "Writing")  # loading and reading say what they are throughout
+        phase = self.phase if now - self.last_chunk < 3 or not streaming else "Working"
         return Text.from_markup(
             f"[cyan]{phase}…[/] [dim]({self.chars // 4} tokens, {now - self.started:.0f}s · Ctrl+C to stop)[/]"
         )
@@ -288,6 +320,12 @@ class Agent:
         # Decides on a presented plan instead of asking in the terminal: "ask", "auto-edit", or why not.
         self.plan_review: Callable[[str, str], str] | None = None
         self.max_steps = MAX_STEPS_PER_TURN
+        self.hardware = None  # an lcode.hardware.Hardware, set by the CLI: for what fits on the GPU
+        self.made_room_for = ""  # why the model was unloaded (the vision model, an MCP tool), for the reload line
+        self.load_state = ""  # "loading" while the model loads in the background at startup (lcode.repl)
+        self.autosave = False  # save the session after every step (sessions people resume; not the bench's)
+        self.sent_chars = 0  # characters of the conversation the model had already read
+        self.counted_chars: int | None = None  # characters that ctx_used covers (None: all of them)
         self.turn_status = ""  # how the last request ended: success, max_steps, loop
         self.repeats = Repeats(settings.repeat_limit)  # notices when the model repeats itself
         self.response = None  # the streaming response, so another thread can abort it
@@ -465,12 +503,33 @@ class Agent:
             image = vision.read_image(path)
             # The session's own model keeps its settings, so Ollama doesn't reload it.
             options = self.options() if model == self.settings.model else None
-            loading = "" if model == self.settings.model else " (loads it; the next request reloads the main model)"
-            with self.console.status(f"Looking at {path.name} with {model}{loading}…", spinner="dots"):
+            with self.vision_swap(model, path.name):
                 return vision.describe(self.ollama, model, image, question, options, self.settings.keep_alive)
         except vision.VisionError as e:
             raise ToolError(str(e)) from e
 
+    @contextlib.contextmanager
+    def vision_swap(self, model: str, what: str):
+        """Look at an image with `model`, saying when it has to load and when the main model made room for it."""
+        main = self.settings.model
+        own = model == main
+        main_was_loaded = not own and residency.placement(self.ollama, main) is not None
+        if own or residency.placement(self.ollama, model) is not None:
+            text = f"Looking at {what} with {model}…"
+        else:
+            text = f"Loading the vision model {model} to look at {what}" + (
+                f"; {main} makes room and reloads afterwards…" if main_was_loaded else "…"
+            )
+        with self.console.status(text, spinner="dots"):
+            yield
+        if main_was_loaded and residency.placement(self.ollama, main) is None:
+            self.made_room_for = f"the vision model {model}"
+            self.say(f"{main} was unloaded to make room for {model}; it reloads for the next step.")
+
+    def say(self, text: str, warning: bool = False) -> None:
+        """One line about what happens under the hood (loading, memory), not about the work itself."""
+        self.console.print(Text(f"{'⚠' if warning else '◆'} {text}", style="yellow" if warning else "dim cyan"))
+
     def describe_image_data(self, data: str, mime: str) -> str:
         """For images that tools return (e.g. an MCP browser's screenshots): a description, or a note."""
         model = self.vision_model()
@@ -478,7 +537,7 @@ class Agent:
             return f"[{mime} image not shown: {vision.INSTALL_HINT}]"
         options = self.options() if model == self.settings.model else None
         try:
-            with self.console.status(f"Looking at the {mime} image with {model}…", spinner="dots"):
+            with self.vision_swap(model, f"the {mime} image"):
                 text = vision.describe(
                     self.ollama, model, base64.b64decode(data), "", options, self.settings.keep_alive
                 )
@@ -522,6 +581,7 @@ class Agent:
         self.tools.read_mtimes.clear()
         self.reflected = len(self.messages)
         self.ctx_used = len(self.messages[0]["content"]) // 3
+        self.counted_chars = None
 
     def session_file(self) -> Path:
         return sessions.sessions_dir() / f"{self.session_id}.json"
@@ -543,7 +603,10 @@ class Agent:
             "messages": self.messages,
             "checkpoints": self.checkpoints.to_json(),
         }
-        f.write_text(json.dumps(data))
+        # Written next to it and then renamed: a crash halfway leaves the previous version, not a broken file.
+        partial = f.with_name(f".{f.name}.partial")
+        partial.write_text(json.dumps(data))
+        os.replace(partial, f)
 
     def new_session(self) -> None:
         self.reset()
@@ -580,6 +643,7 @@ class Agent:
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
         self.reflected = len(self.messages)  # checked for notes to remember when that session ended
         self.ctx_used = sum(len(json.dumps(m)) for m in self.messages) // 3
+        self.counted_chars = None
         return note
 
     def load_latest(self) -> bool:
@@ -624,9 +688,11 @@ class Agent:
                 if not started and batch and batch > SAFE_NUM_BATCH:
                     # Larger batches read prompts faster but need extra VRAM that isn't always free.
                     self.settings.num_batch = SAFE_NUM_BATCH
-                    self.console.print(
-                        f"[yellow]The GPU ran out of memory with a prompt batch of {batch}; retrying with "
-                        f"{SAFE_NUM_BATCH}.[/] [dim]To skip this retry: lcode config set num_batch {SAFE_NUM_BATCH}[/]"
+                    self.say(
+                        f"The GPU ran out of memory reading the prompt in batches of {batch} tokens. Retrying with "
+                        f"batches of {SAFE_NUM_BATCH}: a little slower to read, but it needs less memory. To start "
+                        f"there next time: lcode config set num_batch {SAFE_NUM_BATCH}",
+                        warning=True,
                     )
                     yield from self.chat(messages, tools, think)
                     return
@@ -636,16 +702,19 @@ class Agent:
                     smaller = max(catalog.MIN_USEFUL_CONTEXT, context // 2)
                     self.settings.context = smaller
                     limits.record(self.settings.model, smaller)
-                    self.console.print(
-                        f"[yellow]{self.settings.model} didn't fit in GPU memory with a {format_tokens(context)} "
-                        f"context; retrying with {format_tokens(smaller)}.[/] [dim]lcode will start there next "
-                        "time on this machine.[/]"
+                    self.say(
+                        f"{self.settings.model} didn't fit in memory with a {format_tokens(context)} context: the "
+                        "context needs its own memory next to the model. Reloading it with "
+                        f"{format_tokens(smaller)}; lcode will start there next time on this machine.",
+                        warning=True,
                     )
                     yield from self.chat(messages, tools, think)
                     return
                 raise OllamaError(
-                    f"{e}\nThe model ran out of GPU memory. Try a smaller context (/ctx 128k), close other programs "
-                    "using the GPU, or pick a smaller model (/models)."
+                    f"{e}\n{self.settings.model} ran out of memory. Close other programs that use the GPU (another "
+                    "model, a game, an image generator), use a smaller context (/ctx "
+                    f"{format_tokens(max(catalog.MIN_USEFUL_CONTEXT // 2, context // 2)).lower()}), or pick a smaller "
+                    "model (/models)."
                 ) from e
             raise
 
@@ -659,6 +728,7 @@ class Agent:
         content, thinking, tool_calls, final = "", "", [], {}
         md = MarkdownStreamer(self.console)
         progress = Progress()
+        watch = self.before_request(progress)
         status = None
         printed_thinking = False
 
@@ -680,6 +750,9 @@ class Agent:
                 if self.cancel is not None and self.cancel.is_set():
                     raise KeyboardInterrupt
                 msg = chunk.get("message", {})
+                if watch is not None:
+                    self.after_load(watch)
+                    watch = None
                 if msg.get("thinking"):
                     thinking += msg["thinking"]
                     if self.on_delta:
@@ -714,6 +787,8 @@ class Agent:
             raise
         finally:
             stop_spinner()
+            if watch is not None:
+                watch.stop()
         if printed_thinking:
             self.console.print()
         md.flush()
@@ -732,10 +807,49 @@ class Agent:
             self.usage["output_tokens"] += final.get("eval_count", 0)
             self.usage["output_ns"] += final.get("eval_duration", 0)
             self.ctx_used = final.get("prompt_eval_count", 0) + final.get("eval_count", 0)
+            self.sent_chars = self.counted_chars = conversation_chars(self.messages)
             seconds = final.get("eval_duration", 0) / 1e9
             self.last_speed = final.get("eval_count", 0) / seconds if seconds else 0.0
         return message
 
+    def before_request(self, progress: Progress) -> residency.LoadWatch | None:
+        """Set the status line for what comes before the first token: loading the model if it isn't in memory
+        (watched until it is), then reading the prompt. Returns the watch while the model loads."""
+        if getattr(self.ollama, "kind", "ollama") != "ollama":
+            return None
+        model, context = self.settings.model, self.settings.context
+        fresh = max(0, conversation_chars(self.messages) - self.sent_chars) // 3
+        where = residency.placement(self.ollama, model)
+        if where is not None and (not where.context or where.context == context):
+            if fresh >= READING_NOTE_TOKENS:
+                progress.set_phase(f"Reading {format_tokens(fresh)} new tokens")
+            return None
+        total = conversation_chars(self.messages) // 3
+        if where is not None:
+            phase = f"Reloading {model} with a {format_tokens(context)} context"
+        elif self.made_room_for:
+            phase = f"Reloading {model} into memory (it made room for {self.made_room_for})"
+        else:
+            phase = f"Loading {model} into memory"
+        progress.set_phase(phase)
+        watch = residency.LoadWatch(
+            self.ollama, model, context, progress, f"Reading the conversation ({format_tokens(total)} tokens)"
+        )
+        watch.reload = where is not None or bool(self.made_room_for)
+        return watch
+
+    def after_load(self, watch: residency.LoadWatch) -> None:
+        """The first token after a load: one line on how long it took and how the model fits."""
+        seconds = watch.stop()
+        self.made_room_for = ""
+        self.load_state = ""
+        where = residency.placement(self.ollama, self.settings.model)
+        dense = residency.is_moe(self.ollama, self.settings.model) is False
+        report = residency.load_report(
+            self.settings.model, seconds, where, self.settings.context, self.hardware, dense, watch.reload
+        )
+        self.say(report, warning=report.endswith(("closed.", "slow.")))
+
     def describe_call(self, name: str, args: dict) -> str:
         if name in ("read_file", "write_file", "edit_file"):
             path = self.tools.rel(self.tools.resolve(args.get("path", "")))
@@ -839,6 +953,8 @@ class Agent:
         for step in range(self.max_steps):
             if self.cancel is not None and self.cancel.is_set():
                 raise KeyboardInterrupt
+            if step and self.autosave:
+                self.save()  # a crash or a closed terminal loses at most this step
             self.maybe_compact()
             try:
                 reply = self.assistant_step()
@@ -923,6 +1039,9 @@ class Agent:
                     self.console.print(Text(f"  {result[:300]}", style="red"))
                 elif name in ("read_file", "grep", "glob", "list_dir"):
                     self.console.print(Text(f"  ⎿ {result.count(chr(10)) + 1} line(s)", style="dim"))
+                budget = self.result_budget()
+                if len(result) > budget and name not in ("agent", "skill"):
+                    result = context_tools.shorten(result, budget, f"{name} result")
                 verdict = self.repeats.check(name, args, result)
                 if verdict.note:
                     result += verdict.note
@@ -1057,8 +1176,21 @@ class Agent:
             limit = min(limit, self.settings.compact_at)
         return limit
 
+    def next_request_tokens(self) -> int:
+        """The size of the next request: what the model last counted, plus what was added since (tool output,
+        attachments). Deciding on the last count alone let one large tool result overflow the window."""
+        if self.counted_chars is None:
+            return self.ctx_used
+        return self.ctx_used + max(0, conversation_chars(self.messages) - self.counted_chars) // 3
+
+    def result_budget(self) -> int:
+        """Characters one tool result may take: a share of the window, so one large result can't fill it."""
+        return max(MIN_RESULT_CHARS, int(self.settings.context * 3 * RESULT_SHARE))
+
     def maybe_compact(self) -> None:
         limit = self.compact_limit()
+        if self.next_request_tokens() > limit:
+            self.ctx_used, self.counted_chars = self.next_request_tokens(), None
         if self.ctx_used <= limit:
             return
         enough = int(limit * PRUNED_ENOUGH / AUTO_COMPACT_RATIO)  # after pruning, a summary isn't needed below this
@@ -1071,6 +1203,7 @@ class Agent:
                 )  # not enough: before the last request
             context_tools.note_removed(self.messages, removed)
             if saved:
+                self.sent_chars = 0  # the conversation changed: the model reads it again
                 self.pruned += 1
                 self.ctx_used = max(len(self.messages[0]["content"]) // 3, self.ctx_used - saved // 3)
                 self.console.print(
@@ -1126,7 +1259,9 @@ class Agent:
             )
             self.skills_loaded.clear()
         self.ctx_used = sum(len(m["content"]) for m in self.messages) // 3
+        self.counted_chars = None
         self.summarized_size = self.ctx_used
+        self.sent_chars = 0
         self.reflected = len(self.messages)
         self.console.print(Panel(Markdown(summary), title="Compacted summary", border_style="blue"))
 

lcode/api.py

@@ -199,6 +199,8 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         compact_at=cfg["compact_at"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
+    agent.hardware = hw
+    agent.autosave = True
     agent.interactive = options.interactive
     if options.max_steps:
         agent.max_steps = options.max_steps

lcode/context.py

@@ -14,8 +14,10 @@ full output is saved to a file the model can read if it needs more.
 from __future__ import annotations
 
 import json
+import os
 import re
 import time
+from collections import deque
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -253,6 +255,72 @@ def shorten(text: str, limit: int, label: str = "output") -> str:
     return f"{head}{note}{tail}{where}"
 
 
+class OutputSpool:
+    """Output collected line by line with bounded memory: once it's long, everything goes to a file, and only the
+    start, the end and the error-looking lines stay in memory. What `shorten` returns comes out the same."""
+
+    def __init__(self, limit: int, label: str = "output") -> None:
+        self.limit, self.label = limit, label
+        self.head: list[str] = []  # everything, until the output gets long; then its start
+        self.tail: deque[str] = deque()
+        self.tail_chars = 0
+        self.errors: list[str] = []
+        self.chars = 0
+        self.file = None
+        self.path: Path | None = None
+
+    def add(self, line: str) -> None:
+        self.chars += len(line)
+        if self.file is None:
+            self.head.append(line)
+            if self.chars > self.limit * 2:
+                self._spool()
+            return
+        try:
+            self.file.write(line)
+        except OSError:
+            pass
+        if ERROR_LINE.search(line) and len(self.errors) < MAX_ERROR_LINES:
+            self.errors.append(line.strip()[:300])
+        self.tail.append(line)
+        self.tail_chars += len(line)
+        while self.tail_chars > self.limit // 4 and len(self.tail) > 1:
+            self.tail_chars -= len(self.tail.popleft())
+
+    def _spool(self) -> None:
+        text = "".join(self.head)
+        self.path = save_output(text, self.label)
+        if self.path is not None:
+            try:
+                self.file = self.path.open("a")
+            except OSError:
+                self.file = None
+        if self.file is None:  # nowhere to keep it: keep only the start and carry on counting
+            self.file = open(os.devnull, "w")  # noqa: SIM115
+        head = text[: self.limit * 3 // 5]
+        self.head = [head]
+
+    def text(self) -> str:
+        if self.file is None:
+            return shorten("".join(self.head), self.limit, self.label)
+        self.file.close()
+        head, tail = "".join(self.head), "".join(self.tail)
+        cut = self.chars - len(head) - len(tail)
+        note = f"\n\n... [{cut} characters cut"
+        if self.errors:
+            note += f"; {len(self.errors)} line(s) from them that look like errors:]\n" + "\n".join(self.errors)
+            note += "\n[...]\n\n"
+        else:
+            note += "] ...\n\n"
+        where = (
+            f"\n[The full {self.label} ({self.chars} characters) is in {self.path}: read parts of it with read_file "
+            "if you need them.]"
+            if self.path
+            else ""
+        )
+        return f"{head}{note}{tail}{where}"
+
+
 # ----------------------------------------------------------------------------- what uses the context
 
 

lcode/permissions.py

@@ -22,51 +22,173 @@ SAFE_GIT = {"status", "log", "diff", "show", "branch", "ls-files", "rev-parse",
 MULTI_WORD = {"git", "npm", "pnpm", "yarn", "pip", "uv", "docker", "cargo", "go", "kubectl", "python", "python3", "brew"}  # fmt: skip  # noqa: E501
 
 
-def bash_key(command: str) -> str:
-    """The key "always allow" remembers: the program (plus subcommand for tools like git), ignoring `cd dir &&`."""
-    command = re.sub(r"^\s*(cd\s+\S+\s*&&\s*)+", "", command)
+# `cd <plain path> &&` in front of a command: harmless, and models write it all the time.
+NOT_ASKED = (
+    "This needs the user's permission, and nobody can be asked in this run, so it was not allowed. Do without it "
+    "if you can; otherwise finish and say what permission you need."
+)
+LEADING_CD = re.compile(r"""^\s*(?:cd\s+(?:[\w./~@+,=:-]+|'[^']*'|"[^"$`\\]*")\s*&&\s*)+""")
+
+
+# Redirections that write nothing anyone keeps: stderr into stdout, or output thrown away.
+HARMLESS_REDIRECT = re.compile(r"(?<![\w>&])(?:[12]?>&[12]|[12]?>\s*/dev/null)(?=\s|$)")
+OPERATORS = {"|", "||", "&&", ";", "&", ">", ">>", "<", "<<", "<<<", ">&", "<&", ">|", "(", ")", ";;"}
+
+
+def split_command(command: str) -> tuple[list[list[str]], list[str]] | None:
+    """The command's segments (as words) and the operators between them, quotes respected. None when it can't be
+    read: command substitution, process substitution or unbalanced quotes."""
+    if any(tok in command for tok in ("`", "$(", "<(", ">(")) or "\n" in command.strip():
+        return None
+    lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+    lexer.whitespace_split = True
     try:
-        words = shlex.split(command)
+        tokens = list(lexer)
     except ValueError:
-        words = command.split()
+        return None
+    segments: list[list[str]] = [[]]
+    operators: list[str] = []
+    for token in tokens:
+        if token in OPERATORS or (token and set(token) <= set("|&;<>()")):
+            operators.append(token)
+            segments.append([])
+        else:
+            segments[-1].append(token)
+    return [s for s in segments if s], operators
+
+
+def segment_key(words: list[str]) -> str:
+    """The program, plus the subcommand for tools like git (`git commit`, `python -m pytest`)."""
+    while words and re.fullmatch(r"\w+=\S*", words[0]):
+        words = words[1:]  # VAR=value in front
     if not words:
-        return "bash:"
+        return ""
     if words[0] in MULTI_WORD and len(words) > 1:
         if words[1] in ("-m", "-c") and len(words) > 2:  # python -m <module>
-            return f"bash:{' '.join(words[:3])}"
-        return f"bash:{words[0]} {words[1]}"
-    return f"bash:{words[0]}"
+            return " ".join(words[:3])
+        return f"{words[0]} {words[1]}"
+    return words[0]
 
 
-# `cd <plain path> &&` in front of a command: harmless, and models write it all the time.
-NOT_ASKED = (
-    "This needs the user's permission, and nobody can be asked in this run, so it was not allowed. Do without it "
-    "if you can; otherwise finish and say what permission you need."
-)
-LEADING_CD = re.compile(r"""^\s*(?:cd\s+(?:[\w./~@+,=:-]+|'[^']*'|"[^"$`\\]*")\s*&&\s*)+""")
+def bash_key(command: str) -> str:
+    """What "always allow" remembers. For one program, the program (plus subcommand for git and the like); for a
+    chain such as `npm test && rm -rf build`, every program in it, so allowing `npm test` doesn't allow the chain.
+    `cd dir &&` in front doesn't count."""
+    command = HARMLESS_REDIRECT.sub(" ", LEADING_CD.sub("", command)).strip()
+    parsed = split_command(command)
+    if parsed is None:
+        return "bash:" + " ".join(command.split())  # can't be read: only this exact command
+    segments, operators = parsed
+    keys, redirected = [], False
+    for i, words in enumerate(segments):
+        before = operators[i - 1] if i else ""
+        if before and before not in ("|", "&&", "||", ";", "&"):
+            redirected = True  # a file name after > or <, not a program
+            continue
+        keys.append(segment_key(words))
+    key = " + ".join(k for k in keys if k) + (" (redirected)" if redirected else "")
+    return f"bash:{key}"
 
 
-def is_read_only(command: str) -> bool:
-    command = LEADING_CD.sub("", command)
-    if any(tok in command for tok in (";", "&", ">", "`", "$(", "<(")) or "\n" in command:
+def option_values(words: list[str], *options: str) -> list[str]:
+    """The values of options such as `-o FILE`, `-oFILE` or `--output=FILE`."""
+    found = []
+    for i, word in enumerate(words):
+        for option in options:
+            if word == option and i + 1 < len(words):
+                found.append(words[i + 1])
+            elif option.startswith("--") and word.startswith(option + "="):
+                found.append(word.split("=", 1)[1])
+            elif not option.startswith("--") and word.startswith(option) and len(word) > len(option):
+                found.append(word[len(option) :])
+    return found
+
+
+def flags(words: list[str]) -> list[str]:
+    return [w for w in words[1:] if w.startswith("-")]
+
+
+def positional(words: list[str]) -> list[str]:
+    return [w for w in words[1:] if not w.startswith("-")]
+
+
+# Branch and remote listing; anything else creates, deletes, renames or reconfigures.
+BRANCH_LISTING = {
+    "-a", "--all", "-r", "--remotes", "-l", "--list", "-v", "-vv", "--verbose", "--show-current", "--color",
+    "--no-color", "--column", "--no-column", "--abbrev", "--no-abbrev", "-i", "--ignore-case", "--omit-empty",
+}  # fmt: skip
+BRANCH_WITH_VALUE = {"--contains", "--no-contains", "--merged", "--no-merged", "--points-at", "--sort", "--format"}
+NVIDIA_QUERY = ("-q", "--query", "-L", "--list-gpus", "--format", "-i", "--id", "-d", "--display", "-x", "--xml-format",
+                "-h", "--help", "--query-gpu", "--query-compute-apps")  # fmt: skip
+
+
+def safe_git(words: list[str]) -> bool:
+    if len(words) < 2 or words[1] not in SAFE_GIT:
+        return False  # also `git -c …` and `git -C …`, which can run anything
+    sub, args = words[1], words[2:]
+    if sub in ("log", "show", "diff", "shortlog") and option_values(words, "--output"):
+        return False  # writes the output to a file
+    if sub == "branch":
+        listing = any(a in ("-l", "--list") for a in args)
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            name = arg.split("=", 1)[0]
+            if name in BRANCH_WITH_VALUE:
+                i += 1 if "=" in arg else 2
+                continue
+            if arg.startswith("-") and name not in BRANCH_LISTING:
+                return False  # -d, -D, -m, -c, -f, -u, --set-upstream-to, --edit-description, …
+            if not arg.startswith("-") and not listing:
+                return False  # `git branch name` creates a branch
+            i += 1
+    if sub == "remote":
+        return not args or all(a in ("-v", "--verbose") for a in args) or args[0] in ("show", "get-url")
+    return True
+
+
+def safe_segment(words: list[str]) -> bool:
+    program = words[0]
+    if program == "git":
+        return safe_git(words)
+    if program not in SAFE_COMMANDS:
         return False
-    if re.search(r"-exec|-delete|-ok\b|-fprint", command):
+    if program == "sort" and (
+        option_values(words, "-o", "--output") or any(f.startswith("--compress-program") for f in flags(words))
+    ):
         return False
-    for segment in command.split("|"):
-        try:
-            words = shlex.split(segment)
-        except ValueError:
-            return False
-        if not words:
-            return False
-        if words[0] == "git":
-            if len(words) < 2 or words[1] not in SAFE_GIT:
-                return False
-        elif words[0] not in SAFE_COMMANDS:
-            return False
+    if program == "uniq" and len(positional(words)) > 1:
+        return False  # `uniq in out` writes out
+    if program == "tree" and option_values(words, "-o"):
+        return False
+    if program == "rg" and any(f.split("=")[0] in ("--pre", "--pre-glob") for f in flags(words)):
+        return False  # runs a program on each file
+    if program == "find" and any(
+        w in ("-exec", "-execdir", "-ok", "-okdir", "-delete", "-fprint", "-fprint0", "-fprintf", "-fls") for w in words
+    ):
+        return False
+    if program == "date" and (option_values(words, "-s", "--set") or "-s" in words):
+        return False
+    if program == "file" and any(f in ("-C", "--compile") for f in flags(words)):
+        return False
+    if program == "nvidia-smi":
+        return all(f.split("=")[0] in NVIDIA_QUERY for f in flags(words))
     return True
 
 
+def is_read_only(command: str) -> bool:
+    """Whether a command only reads: known read-only programs with arguments that don't write, joined only by
+    pipes. `cd dir &&` in front, `2>&1` and `>/dev/null` are fine."""
+    command = HARMLESS_REDIRECT.sub(" ", LEADING_CD.sub("", command)).strip()
+    parsed = split_command(command)
+    if parsed is None:
+        return False
+    segments, operators = parsed
+    if not segments or any(op != "|" for op in operators):
+        return False
+    return all(safe_segment(words) for words in segments)
+
+
 class Permissions:
     def __init__(self, console: Console, mode: str = "ask"):
         from lcode.hooks import Rules