lcode-cli 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

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.10.0"

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, extensions, 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,
@@ -77,7 +78,7 @@ SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent runni
 
 # Top-level layout of the working directory
 {tree}
-{web}{agents}{project}{notes}"""
+{web}{agents}{skills}{project}{notes}"""
 
 WEB_PROMPT = """
 # Web access
@@ -170,6 +171,8 @@ class Settings:
     vision_model: str = "auto"  # auto, off or an Ollama model that can see images
     memory: str = "off"  # off, ask or auto: notes that carry over to later sessions (lcode.memory)
     subagents: bool = False  # the agent tool (lcode.subagents)
+    trust_project: bool = False  # use the repository's own commands, skills and agents (lcode.extensions)
+    skills: str = "off"  # all, lcode (only lcode's own skill folders) or off
     max_parallel_agents: int = 1
 
 
@@ -198,6 +201,9 @@ 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
+        self._extensions: tuple[Path, extensions.Extensions] | None = None
+        self.skills_loaded: set[str] = set()  # skills whose instructions are in the conversation
         # 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
@@ -234,8 +240,15 @@ class Agent:
             notes=self.memory().prompt(self.settings.context) if self.settings.memory != "off" else "",
             web=self.web_prompt(),
             agents=self.agents_prompt(),
+            skills=extensions.skills_prompt(self.extensions().skills, self.settings.context),
         )
 
+    def extensions(self) -> extensions.Extensions:
+        """Custom commands and skills for the current folder (a repository's only once approved)."""
+        if self._extensions is None or self._extensions[0] != self.cwd:
+            self._extensions = (self.cwd, extensions.load(self.cwd, self.settings.trust_project, self.settings.skills))
+        return self._extensions[1]
+
     def agents_prompt(self) -> str:
         if not self.settings.subagents:
             return ""
@@ -250,7 +263,7 @@ class Agent:
     def agent_types(self) -> dict[str, subagents.AgentType]:
         """Built-in and custom agent types for the current folder."""
         if self._agent_types is None or self._agent_types[0] != self.cwd:
-            types, problems = subagents.load_types(self.cwd)
+            types, problems = subagents.load_types(self.cwd, self.settings.trust_project)
             self._agent_types = (self.cwd, types, problems)
         return self._agent_types[1]
 
@@ -259,6 +272,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 +299,10 @@ 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.extensions().skills:
+            schemas.append(extensions.schema(self.extensions().skills))
         if self.mcp:
             schemas += self.mcp.schemas(self.settings.context)
         if self.allowed_tools is not None:
@@ -402,6 +422,7 @@ class Agent:
 
     def new_session(self) -> None:
         self.reset()
+        self.skills_loaded.clear()
         self.session_id = self.new_session_id()
         self.session_name = ""
         self.session_title = ""
@@ -599,6 +620,8 @@ class Agent:
             return f"list_dir({args.get('path', '.')})"
         if name == "memory":
             return f"memory({' '.join(str(args.get(k) or '') for k in ('action', 'name')).strip()})"
+        if name == "skill":
+            return f"skill({args.get('name', '')})"
         if name == "agent":
             return f"agent({args.get('type', '')}: {args.get('description') or str(args.get('task', ''))[:50]})"
         if name == "bash":
@@ -638,7 +661,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 +801,14 @@ 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}"
+        if self.skills_loaded:  # their instructions were in the old messages: load them again when needed
+            names = ", ".join(sorted(self.skills_loaded))
+            self.messages[1]["content"] += (
+                f"\n\n[Skills in use before the summary: {names}. Load them again with the skill tool if you still need them.]"
+            )
+            self.skills_loaded.clear()
         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.py

@@ -367,6 +367,20 @@ def cmd_doctor(args) -> None:
             line("", f"{n} × {slots[1]} context may not fit in memory here; {slots[0]} would", None)
         for problem in problems:
             line("", problem, None)
+    from lcode import extensions
+
+    project_state = extensions.status(Path.cwd())
+    ext = extensions.load(Path.cwd(), include_project=project_state == "approved", skills_from=cfg["skills"])
+    found = f"{len(ext.commands)} command(s), {len(ext.skills)} skill(s)"
+    note = {
+        "none": "",
+        "approved": " · this repository's are approved",
+        "new": " · this repository brings its own: approve them when lcode asks",
+        "changed": " · this repository's changed since you approved them: lcode asks again",
+    }[project_state]
+    line("Extras", found + note, None if project_state in ("new", "changed") else True)
+    for problem in ext.problems:
+        line("", problem, None)
     if cfg["memory"] == "off":
         line("Memory", "off (lcode config set memory ask)", True)
     else:
@@ -519,13 +533,18 @@ 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:
             num_batch = spec.num_batch
         else:  # the tuned batch size assumes the text-only variant; the vision projector needs that VRAM
             console.print(f"[dim]Tip: run `lcode setup {spec.key}` once to create the faster text-only variant.[/]")
+    from lcode import extensions
+
+    trust_project = extensions.trust_project(cwd, console, interactive=not args.prompt)
     settings = Settings(
         model=model,
         context=context,
@@ -545,6 +564,8 @@ def cmd_chat(args) -> None:
         memory="off" if args.no_memory else cfg["memory"],
         subagents=cfg["subagents"],
         max_parallel_agents=cfg["max_parallel_agents"],
+        trust_project=trust_project,
+        skills=cfg["skills"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
     agent.interactive = not args.prompt
@@ -589,6 +610,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/config.py

@@ -21,12 +21,13 @@ 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")
 SANDBOX_ENGINES = ("off", "docker", "podman")
 MEMORY_MODES = ("off", "ask", "auto")
+SKILL_SOURCES = ("all", "lcode", "off")
 
 # key -> (default, type, help)
 SETTINGS: dict[str, tuple[object, type, str]] = {
@@ -35,7 +36,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)"),
@@ -47,6 +48,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "vision_model": ("auto", str, "model that looks at images: auto | off | an Ollama model with vision"),
     "mcp_tools": ("auto", str, "how MCP tools reach the model: auto | direct | search (on demand, saves context)"),
     "memory": ("ask", str, "notes that carry over to later sessions: off | ask (confirm each) | auto"),
+    "skills": ("all", str, "skills to offer the model: all (also other agents' folders) | lcode | off"),
     "subagents": (True, bool, "let the model hand tasks to subagents that have their own context"),
     "max_parallel_agents": (1, int, "subagents that may run at the same time (more needs OLLAMA_NUM_PARALLEL)"),
 }
@@ -120,6 +122,10 @@ def coerce(key: str, value: object) -> object:
         if value not in MEMORY_MODES:
             raise ConfigError(f"memory must be one of {', '.join(MEMORY_MODES)}")
         return value
+    if key == "skills" and str(value).lower() not in SKILL_SOURCES:
+        raise ConfigError(f"skills must be one of {', '.join(SKILL_SOURCES)}")
+    if key == "skills":
+        return str(value).lower()
     if key == "mcp_tools" and value not in MCP_TOOL_MODES:
         raise ConfigError(f"mcp_tools must be one of {', '.join(MCP_TOOL_MODES)}")
     if key == "search_backend" and value not in SEARCH_BACKENDS:

lcode/extensions.py

@@ -0,0 +1,405 @@
+"""Custom slash commands and skills, and the approval of those a repository brings.
+
+Commands are prompt templates: `.lcode/commands/<name>.md` in a repository or
+`~/.config/lcode/commands/<name>.md`, run as `/name args`. `$ARGUMENTS` in the template becomes
+everything after the name, `$1`…`$9` single words. An optional frontmatter gives a description,
+an argument hint for /help and the tools the model may use for that request.
+
+Skills follow the Agent Skills format (https://agentskills.io): a folder with a SKILL.md
+(frontmatter with name and description, then instructions) and any scripts or reference files next
+to it. lcode looks in `.lcode/skills/`, `.agents/skills/` and `.claude/skills/` of the repository and
+the same places in the user's home (`~/.config/lcode/skills/` for lcode's own). Only the names and
+descriptions are in the system prompt; the instructions load when the model calls the skill tool for
+a task that matches, or when the user runs `/name`. Bundled files are listed, not read, until needed.
+
+A repository's commands, skills and agents can steer the model and bring scripts it may run, so
+lcode asks before using them the first time, and again whenever they change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.markup import escape
+
+from lcode import config
+from lcode.checkpoints import work_tree_for
+from lcode.frontmatter import split
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from lcode.agent import Agent
+
+SKILL_FOLDERS = (".lcode/skills", ".agents/skills", ".claude/skills")  # in a repository, first found wins
+PROJECT_FOLDERS = (".lcode/commands", ".lcode/agents", *SKILL_FOLDERS)  # what needs approval
+MAX_SKILLS_PROMPT = 6000  # characters of skill descriptions in the system prompt (~2K tokens)
+MAX_DESCRIPTION = 300  # characters of one skill's description in the system prompt
+MIN_DESCRIPTION = 40  # with many skills, descriptions are cut down to this rather than skills left out
+MAX_RESOURCES = 50
+MAX_FILES = 2000  # files looked at when fingerprinting a repository's extensions
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv"}
+
+SKILLS_PROMPT = """
+# Skills
+Skills are instructions for specific kinds of tasks. When a task matches a skill's description, call the skill tool with its name first, then follow the instructions it returns. Paths in a skill are relative to its folder; use the absolute paths it gives.
+{catalog}
+"""
+
+
+class ExtensionError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    description: str
+    template: str
+    path: Path
+    scope: str  # project | user
+    argument_hint: str = ""
+    tools: frozenset[str] | None = None
+
+    def render(self, args: str) -> str:
+        """The request: the template with $ARGUMENTS and $1…$9 filled in."""
+        words = args.split()
+        text = self.template
+        used = "$ARGUMENTS" in text or re.search(r"\$[1-9]", text)
+        text = text.replace("$ARGUMENTS", args)
+        text = re.sub(r"\$([1-9])", lambda m: words[int(m.group(1)) - 1] if int(m.group(1)) <= len(words) else "", text)
+        if args and not used:
+            text = f"{text.rstrip()}\n\n{args}"
+        return text.strip()
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    path: Path  # the SKILL.md
+    scope: str
+
+    @property
+    def folder(self) -> Path:
+        return self.path.parent
+
+    def instructions(self) -> str:
+        parts = split(self.path.read_text(errors="replace"))
+        return (parts[1] if parts else self.path.read_text(errors="replace")).strip()
+
+    def resources(self) -> list[str]:
+        found = []
+        for root, dirs, files in os.walk(self.folder):
+            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
+            for name in sorted(files):
+                path = Path(root) / name
+                if path != self.path:
+                    found.append(path.relative_to(self.folder).as_posix())
+                if len(found) > MAX_RESOURCES:
+                    return found
+        return found
+
+
+# ----------------------------------------------------------------------------- loading
+
+
+def user_skill_folders(which: str = "all") -> list[Path]:
+    home = Path.home()
+    other_agents = [home / ".agents" / "skills", home / ".claude" / "skills"] if which == "all" else []
+    return [config.CONFIG_DIR / "skills", *other_agents]
+
+
+def load_commands(cwd: Path, include_project: bool) -> tuple[dict[str, Command], list[str]]:
+    folders = [(config.CONFIG_DIR / "commands", "user")]
+    if include_project:
+        folders.append((work_tree_for(cwd) / ".lcode" / "commands", "project"))
+    commands: dict[str, Command] = {}
+    problems = []
+    for folder, scope in folders:  # the repository's override the user's
+        for f in sorted(folder.glob("*.md")) if folder.is_dir() else []:
+            try:
+                commands[f.stem] = parse_command(f, scope)
+            except (ExtensionError, OSError) as e:
+                problems.append(f"{f}: {e}")
+    return commands, problems
+
+
+def parse_command(path: Path, scope: str) -> Command:
+    from lcode.tools import TOOL_NAMES
+
+    name = path.stem
+    if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name):
+        raise ExtensionError("the file name must be lowercase letters, digits, - or _")
+    text = path.read_text(errors="replace")
+    fields, body = split(text) or ({}, text)
+    if not body.strip():
+        raise ExtensionError("the command has no prompt")
+    tools = None
+    listed = fields.get("allowed-tools") or fields.get("tools")
+    if listed:
+        tools = frozenset(t for t in re.split(r"[,\s]+", listed.strip("[]")) if t)
+        unknown = tools - TOOL_NAMES
+        if unknown:
+            raise ExtensionError(
+                f"unknown tools: {', '.join(sorted(unknown))} (lcode's tools: {', '.join(sorted(TOOL_NAMES))})"
+            )
+    first = next((line.strip() for line in body.strip().splitlines() if line.strip()), "")
+    return Command(
+        name=name,
+        description=" ".join(fields.get("description", "").split()) or first[:80],
+        template=body.strip(),
+        path=path,
+        scope=scope,
+        argument_hint=fields.get("argument-hint", ""),
+        tools=tools,
+    )
+
+
+def load_skills(cwd: Path, include_project: bool, which: str = "all") -> tuple[dict[str, Skill], list[str]]:
+    """Skills from lcode's folders and, with `which` = all, the folders other agents share."""
+    if which == "off":
+        return {}, []
+    places = [(folder, "user") for folder in user_skill_folders(which)]
+    if include_project:
+        root = work_tree_for(cwd)
+        places += [(root / folder, "project") for folder in (SKILL_FOLDERS if which == "all" else SKILL_FOLDERS[:1])]
+    skills: dict[str, Skill] = {}
+    problems = []
+    for folder, scope in places:
+        for skill_file in sorted(folder.glob("*/SKILL.md")) if folder.is_dir() else []:
+            try:
+                skill = parse_skill(skill_file, scope)
+            except (ExtensionError, OSError) as e:
+                problems.append(f"{skill_file}: {e}")
+                continue
+            existing = skills.get(skill.name)
+            if existing and existing.scope == scope:
+                if not same_file(existing.path, skill_file):  # the same skill installed twice is fine
+                    problems.append(f"{skill_file}: skipped, {existing.path} has the same name")
+                continue
+            skills[skill.name] = skill  # a repository's skill replaces the user's
+    return skills, problems
+
+
+def same_file(a: Path, b: Path) -> bool:
+    try:
+        return a.resolve() == b.resolve() or a.read_bytes() == b.read_bytes()
+    except OSError:
+        return False
+
+
+def parse_skill(path: Path, scope: str) -> Skill:
+    parts = split(path.read_text(errors="replace"))
+    if not parts:
+        raise ExtensionError("SKILL.md needs a frontmatter with a name and a description")
+    fields = parts[0]
+    description = " ".join(fields.get("description", "").split())
+    if not description:
+        raise ExtensionError("the frontmatter needs a description")
+    # Lenient, like other clients: a name that breaks the format rules still works, as the folder name.
+    name = fields.get("name", "").strip() or path.parent.name
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name) or len(name) > 64:
+        name = path.parent.name
+    return Skill(name=name, description=description, path=path, scope=scope)
+
+
+# ----------------------------------------------------------------------------- using skills
+
+
+def skills_prompt(skills: dict[str, Skill], context: int = 262144) -> str:
+    """The skill catalog for the system prompt: within ~5% of the context window, every skill listed
+    (descriptions are shortened first), and only then cut off."""
+    if not skills:
+        return ""
+    budget = min(MAX_SKILLS_PROMPT, context * 3 // 20)
+    room = budget // len(skills) - 6
+    lines, used = [], 0
+    for skill in skills.values():
+        limit = max(MIN_DESCRIPTION, min(MAX_DESCRIPTION, room - len(skill.name)))
+        description = skill.description
+        if len(description) > limit:
+            description = description[: limit - 1].rstrip() + "…"
+        line = f"- {skill.name}: {description}"
+        if used + len(line) > budget:
+            lines.append(f"- … and {len(skills) - len(lines)} more (the skill tool lists them all)")
+            break
+        lines.append(line)
+        used += len(line) + 1
+    return SKILLS_PROMPT.format(catalog="\n".join(lines))
+
+
+def schema(skills: dict[str, Skill]) -> dict:
+    from lcode.tools import _fn
+
+    return _fn(
+        "skill",
+        "Load a skill's instructions when the task matches its description (see Skills). Returns the "
+        "instructions, the skill's folder and the files in it.",
+        {"name": {"type": "string", "enum": sorted(skills)}},
+        ["name"],
+    )
+
+
+def content(skill: Skill) -> str:
+    """What the model gets when a skill is activated: instructions, folder and bundled files."""
+    files = skill.resources()
+    listing = "\n".join(f"  {f}" for f in files[:MAX_RESOURCES])
+    if len(files) > MAX_RESOURCES:
+        listing += "\n  … (more files; list the folder to see them)"
+    return (
+        f'<skill_content name="{skill.name}">\n{skill.instructions()}\n\n'
+        f"Skill folder: {skill.folder}\nRelative paths in this skill are relative to that folder: use "
+        "absolute paths in tool calls.\n"
+        + (f"<skill_resources>\n{listing}\n</skill_resources>\n" if files else "")
+        + "</skill_content>"
+    )
+
+
+def activate(agent: Agent, name: str) -> str:
+    skills = agent.extensions().skills
+    if name not in skills:
+        return f"Error: no skill {name!r}. Skills: {', '.join(sorted(skills)) or 'none'}"
+    if name in agent.skills_loaded:
+        return f"The {name} skill's instructions are already loaded above; follow them."
+    try:
+        text = content(skills[name])
+    except OSError as e:
+        return f"Error: can't read the {name} skill: {e}"
+    agent.skills_loaded.add(name)
+    return text
+
+
+# ----------------------------------------------------------------------------- approving a repository's extensions
+
+
+def approvals_path() -> Path:
+    return config.STATE_DIR / "extensions-approved.json"
+
+
+def project_files(cwd: Path) -> tuple[Path, list[Path]]:
+    """The repository's root and the files of its commands, skills and agents."""
+    root = work_tree_for(cwd)
+    files: list[Path] = []
+    for folder in PROJECT_FOLDERS:
+        base = root / folder
+        if not base.is_dir():
+            continue
+        for current, dirs, names in os.walk(base):
+            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
+            files += [Path(current) / n for n in sorted(names)]
+            if len(files) >= MAX_FILES:
+                return root, files[:MAX_FILES]
+    return root, files
+
+
+def fingerprint(root: Path, files: list[Path]) -> str:
+    digest = hashlib.sha256()
+    for f in files:
+        digest.update(f.relative_to(root).as_posix().encode() + b"\0")
+        try:
+            digest.update(hashlib.sha256(f.read_bytes()).digest())
+        except OSError:
+            digest.update(b"?")
+    return digest.hexdigest()
+
+
+def _approved() -> dict:
+    try:
+        data = json.loads(approvals_path().read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def status(cwd: Path) -> str:
+    """none (the repository brings nothing), approved, new or changed."""
+    root, files = project_files(cwd)
+    if not files:
+        return "none"
+    seen = _approved().get(str(root))
+    if seen is None:
+        return "new"
+    return "approved" if seen == fingerprint(root, files) else "changed"
+
+
+def approve(cwd: Path) -> None:
+    root, files = project_files(cwd)
+    data = _approved()
+    data[str(root)] = fingerprint(root, files)
+    approvals_path().parent.mkdir(parents=True, exist_ok=True)
+    approvals_path().write_text(json.dumps(data, indent=2))
+
+
+def describe(cwd: Path) -> list[str]:
+    """What the repository brings, one line per kind."""
+    from lcode.subagents import parse_agent
+
+    root = work_tree_for(cwd)
+    commands, _ = load_commands(cwd, include_project=True)
+    skills, _ = load_skills(cwd, include_project=True)
+    agents = []
+    for f in sorted((root / ".lcode" / "agents").glob("*.md")):
+        try:
+            agents.append(parse_agent(f.read_text(errors="replace"), f.stem, str(f)).name)
+        except (ValueError, OSError):
+            continue
+    lines = []
+    project_commands = [f"/{c.name}" for c in commands.values() if c.scope == "project"]
+    project_skills = [s.name for s in skills.values() if s.scope == "project"]
+    if project_commands:
+        lines.append(f"commands: {', '.join(project_commands)}")
+    if project_skills:
+        lines.append(f"skills: {', '.join(project_skills)}")
+    if agents:
+        lines.append(f"agents: {', '.join(agents)}")
+    return lines
+
+
+def trust_project(cwd: Path, console: Console, interactive: bool) -> bool:
+    """Whether to use the repository's commands, skills and agents; asks the first time."""
+    state = status(cwd)
+    if state in ("none", "approved"):
+        return state == "approved"
+    root = work_tree_for(cwd)
+    if not interactive:
+        console.print(
+            f"[dim]Not using the commands, skills and agents in {escape(str(root))} until you approve them in a session.[/]"
+        )
+        return False
+    changed = " [yellow](changed since you approved them)[/]" if state == "changed" else ""
+    console.print(f"This repository brings its own commands, skills or agents{changed}:")
+    for line in describe(cwd) or ["(files in " + ", ".join(PROJECT_FOLDERS) + ")"]:
+        console.print(f"  {escape(line)}")
+    console.print(
+        "[dim]They can steer the model and include scripts it may run (commands still ask first, unless "
+        "you allow them).[/]"
+    )
+    try:
+        answer = input("  Use them? [y/N] ").strip().lower()
+    except EOFError:
+        answer = ""
+    if answer in ("y", "yes"):
+        approve(cwd)
+        return True
+    console.print("[dim]Not using them in this session. You'll be asked again next time.[/]")
+    return False
+
+
+@dataclass
+class Extensions:
+    commands: dict[str, Command]
+    skills: dict[str, Skill]
+    problems: list[str]
+
+
+def load(cwd: Path, include_project: bool, skills_from: str = "all") -> Extensions:
+    commands, command_problems = load_commands(cwd, include_project)
+    skills, skill_problems = load_skills(cwd, include_project, skills_from)
+    return Extensions(commands, skills, command_problems + skill_problems)

lcode/frontmatter.py

@@ -0,0 +1,62 @@
+"""The `---` header of markdown files: memory notes, agents, commands and skills.
+
+A small, lenient subset of YAML, enough for these headers without a YAML dependency:
+`key: value` lines, quoted values, block scalars (`key: |` and `key: >`, with indented lines below),
+and nested maps or lists (kept as raw text). Skills written for other agents sometimes have values
+that strict YAML rejects, such as an unquoted colon in a description; those are read as plain text.
+"""
+
+from __future__ import annotations
+
+import re
+
+BLOCK = re.compile(r"^[|>][+-]?$")
+
+
+def split(text: str) -> tuple[dict[str, str], str] | None:
+    """The header fields and the body after them, or None when the text has no header."""
+    m = re.match(r"?---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|$)(.*)", text, re.S)
+    if not m:
+        return None
+    return parse(m.group(1)), m.group(2)
+
+
+def parse(header: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    lines = header.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        i += 1
+        if not line.strip() or line.lstrip().startswith("#") or line[:1].isspace():
+            continue
+        key, sep, value = line.partition(":")
+        if not sep:
+            continue
+        key, value = key.strip(), value.strip()
+        nested = []
+        while i < len(lines) and (not lines[i].strip() or lines[i][:1].isspace()):
+            nested.append(lines[i])
+            i += 1
+        while nested and not nested[-1].strip():
+            nested.pop()
+        if BLOCK.match(value):
+            indent = min((len(n) - len(n.lstrip()) for n in nested if n.strip()), default=0)
+            body = [n[indent:] for n in nested]
+            if value.startswith(">"):
+                value = re.sub(r"(?<!\n)\n(?!\n)", " ", "\n".join(body)).strip()
+            else:
+                value = "\n".join(body).rstrip()
+        elif not value and nested:
+            value = "\n".join(nested)  # a nested map or list, kept as text
+        elif nested:
+            value = " ".join([value, *(n.strip() for n in nested)]).strip()  # a plain value over several lines
+        fields[key] = unquote(value)
+    return fields
+
+
+def unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+        inner = value[1:-1]
+        return inner.replace("''", "'") if value[0] == "'" else inner.replace('\\"', '"').replace("\\n", "\n")
+    return value

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/memory.py

@@ -39,6 +39,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from lcode import config
+from lcode.frontmatter import split as frontmatter
 
 if TYPE_CHECKING:
     from lcode.agent import Agent
@@ -186,19 +187,6 @@ def project_dir(cwd: Path) -> Path:
     return memory_dir() / "projects" / f"{slugify(name, 40) or 'folder'}-{key}"
 
 
-def frontmatter(text: str) -> tuple[dict[str, str], str] | None:
-    """The `key: value` header between --- lines, and the body after it (None without a header)."""
-    m = re.match(r"---\r?\n(.*?)\r?\n---\r?\n?(.*)", text, re.S)
-    if not m:
-        return None
-    fields = {}
-    for line in m.group(1).splitlines():
-        key, sep, value = line.partition(":")
-        if sep:
-            fields[key.strip()] = value.strip()
-    return fields, m.group(2)
-
-
 def parse(text: str, scope: str, path: Path | None = None) -> Note | None:
     split = frontmatter(text)
     if not split:
@@ -507,7 +495,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/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", "skill",
+    }
+)  # 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/repl.py

@@ -18,13 +18,14 @@ 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
 from rich.table import Table
 from rich.text import Text
 
-from lcode import __version__, catalog, limits, sessions, web
+from lcode import __version__, catalog, extensions, limits, sessions, web
 from lcode import memory as memory_notes
 from lcode.agent import AUTO_COMPACT_RATIO, INIT_PROMPT, Agent
 from lcode.catalog import MIN_USEFUL_CONTEXT
@@ -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",
@@ -71,7 +73,7 @@ class InputCompleter(Completer):
     def get_completions(self, document, complete_event):
         text = document.text_before_cursor
         if text.startswith("/") and " " not in text:
-            for cmd, desc in COMMANDS.items():
+            for cmd, desc in {**COMMANDS, **custom_commands(self.agent)}.items():
                 if cmd.startswith(text):
                     yield Completion(cmd, start_position=-len(text), display_meta=desc)
             return
@@ -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) · "
@@ -380,6 +382,48 @@ def agents_command(agent: Agent, arg: str) -> None:
     )
 
 
+def custom_commands(agent: Agent) -> dict[str, str]:
+    """The user's and the repository's commands and skills, as /name -> description (built-ins win)."""
+    ext = agent.extensions()
+    found = {f"/{name}": skill.description for name, skill in ext.skills.items()}
+    found.update({f"/{name}": command.description for name, command in ext.commands.items()})
+    return {name: description for name, description in found.items() if name not in COMMANDS}
+
+
+def help_extensions(agent: Agent) -> None:
+    c, ext = agent.console, agent.extensions()
+    if ext.commands:
+        table = Table(title="Your commands", title_justify="left", header_style="bold")
+        for column in ("Command", "Does", "From"):
+            table.add_column(column)
+        for command in ext.commands.values():
+            hidden = " [yellow](hidden by the built-in command)[/]" if f"/{command.name}" in COMMANDS else ""
+            usage = f"/{command.name}" + (f" {command.argument_hint}" if command.argument_hint else "")
+            table.add_row(escape(usage), escape(command.description) + hidden, escape(agent.tools.rel(command.path)))
+        c.print(table)
+    if ext.skills:
+        table = Table(
+            title="Skills (the model loads them when a task matches; /name runs one)",
+            title_justify="left",
+            header_style="bold",
+        )
+        for column in ("Skill", "Does", "From"):
+            table.add_column(column)
+        for skill in ext.skills.values():
+            description = skill.description if len(skill.description) <= 140 else skill.description[:139] + "…"
+            if f"/{skill.name}" in COMMANDS or skill.name in ext.commands:
+                description += f" [yellow](/{skill.name} runs the command; the model can still load the skill)[/]"
+            table.add_row(f"/{escape(skill.name)}", escape(description), escape(agent.tools.rel(skill.folder)))
+        c.print(table)
+    for problem in ext.problems:
+        c.print(f"[yellow]Skipped {escape(problem)}[/]")
+    if not agent.settings.trust_project and extensions.status(agent.cwd) in ("new", "changed"):
+        c.print(
+            "[dim]This repository's own commands, skills and agents aren't in use: you didn't approve them "
+            "(restart lcode here to be asked again).[/]"
+        )
+
+
 def memory_status(agent: Agent) -> str:
     project, user = agent.memory().counts()
     if not (project or user):
@@ -714,6 +758,7 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
             "@path = attach a file · Shift+Tab = cycle permission mode"
         )
         c.print(Panel(f"{rows}\n\n  [dim]{keys}[/]", title="lcode commands", border_style="cyan"))
+        help_extensions(agent)
     elif cmd == "/clear":
         memory_notes.reflect(agent)
         agent.new_session()
@@ -772,6 +817,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
@@ -791,6 +850,23 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
         agent.tools.show_todos()
     elif cmd == "/init":
         run_safely(agent, INIT_PROMPT)
+    elif cmd[1:] in agent.extensions().commands:
+        command = agent.extensions().commands[cmd[1:]]
+        c.print(f"[dim]/{escape(command.name)} from {escape(agent.tools.rel(command.path))}[/]")
+        c.print(Rule(style="dim"))
+        previous = agent.allowed_tools
+        if command.tools is not None:
+            agent.allowed_tools = set(command.tools)
+        try:
+            run_safely(agent, command.render(arg))
+        finally:
+            agent.allowed_tools = previous
+    elif cmd[1:] in agent.extensions().skills:
+        skill = agent.extensions().skills[cmd[1:]]
+        agent.skills_loaded.add(skill.name)
+        c.print(f"[dim]Using the {escape(skill.name)} skill from {escape(agent.tools.rel(skill.folder))}[/]")
+        c.print(Rule(style="dim"))
+        run_safely(agent, f"{arg or f'Use the {skill.name} skill.'}\n\n{extensions.content(skill)}")
     else:
         c.print(f"[red]Unknown command {cmd}.[/] Type /help.")
     return True

lcode/subagents.py

@@ -45,7 +45,7 @@ from rich.text import Text
 
 from lcode import config
 from lcode.checkpoints import _clean_env, work_tree_for
-from lcode.memory import frontmatter
+from lcode.frontmatter import split as frontmatter
 from lcode.ollama import OllamaError
 
 if TYPE_CHECKING:
@@ -53,7 +53,7 @@ if TYPE_CHECKING:
     from lcode.permissions import Permissions
 
 READ_ONLY_TOOLS = frozenset(
-    {"read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write"}
+    {"read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write", "skill"}
 )
 EDIT_TOOLS = frozenset({"write_file", "edit_file"})
 NOT_FOR_SUBAGENTS = frozenset({"agent", "memory"})  # no agents inside agents; only the main session remembers
@@ -123,9 +123,9 @@ BUILT_IN = {
 # ----------------------------------------------------------------------------- agent types
 
 
-def agent_dirs(cwd: Path) -> list[Path]:
-    """Where custom agents live, lowest priority first: the user's, then the repository's."""
-    return [config.CONFIG_DIR / "agents", work_tree_for(cwd) / ".lcode" / "agents"]
+def agent_dirs(cwd: Path, include_project: bool = True) -> list[Path]:
+    """Where custom agents live, lowest priority first: the user's, then the repository's (once approved)."""
+    return [config.CONFIG_DIR / "agents", *([work_tree_for(cwd) / ".lcode" / "agents"] if include_project else [])]
 
 
 def parse_agent(text: str, name: str, source: str) -> AgentType:
@@ -173,11 +173,11 @@ def parse_agent(text: str, name: str, source: str) -> AgentType:
     )
 
 
-def load_types(cwd: Path) -> tuple[dict[str, AgentType], list[str]]:
+def load_types(cwd: Path, include_project: bool = True) -> tuple[dict[str, AgentType], list[str]]:
     """The agent types for `cwd` (custom ones override built-in ones), and problems with custom ones."""
     types = dict(BUILT_IN)
     problems = []
-    for folder in agent_dirs(cwd):
+    for folder in agent_dirs(cwd, include_project):
         if not folder.is_dir():
             continue
         for f in sorted(folder.glob("*.md")):

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,9 +199,23 @@ 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]
+} | {"agent", "skill"}  # those two have schemas that depend on the session
 
 
 # ----------------------------------------------------------------------------- helpers
@@ -319,10 +334,15 @@ class Toolbox:
         p = Path(os.path.expanduser(path or "."))
         return (p if p.is_absolute() else self.agent.cwd / p).resolve()
 
-    def path(self, path: str | None) -> Path:
-        """Resolve a path from the model; with the sandbox on, it must be inside the project."""
+    def path(self, path: str | None, read: bool = False) -> Path:
+        """Resolve a path from the model; with the sandbox on, it must be inside the project (or, for
+        reading, inside a skill's folder)."""
         p = self.resolve(path)
         root = self.agent.sandbox_root()
+        if read and root is not None:
+            skills = self.agent.extensions().skills.values()
+            if any(p == s.folder or s.folder in p.parents for s in skills):
+                return p
         if root is not None and p != root and root not in p.parents:
             raise ToolError(f"{path} is outside the project ({root}); with the sandbox on, that's all you can use")
         return p
@@ -337,6 +357,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 +400,26 @@ 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)
+
+    # -- skills
+    def t_skill(self, name: str) -> str:
+        from lcode.extensions import activate
+
+        result = activate(self.agent, name)
+        if not result.startswith("Error:"):
+            self.console.print(Text(f"  ⎿ loaded the {name} skill", style="dim"))
+        return result
+
     # -- memory
     def t_memory(
         self, action: str, name: str = "", type: str = "", description: str = "", details: str = "", scope: str = ""
@@ -431,7 +473,7 @@ class Toolbox:
 
     # -- read-only
     def t_read_file(self, path: str, offset: int = 1, limit: int = 2000) -> str:
-        p = self.path(path)
+        p = self.path(path, read=True)
         if not p.exists():
             raise ToolError(f"{path} does not exist")
         if p.is_dir():
@@ -453,7 +495,7 @@ class Toolbox:
         return truncate(out, 120_000)
 
     def t_list_dir(self, path: str = ".", depth: int = 2) -> str:
-        p = self.path(path)
+        p = self.path(path, read=True)
         if not p.is_dir():
             raise ToolError(f"{path} is not a directory")
         return tree(p, depth=max(1, min(int(depth or 2), 6)))
@@ -605,6 +647,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.dist-info → lcode_cli-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.8.0
+Version: 0.10.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,10 @@ 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.
+- **Commands and skills.** Your own `/commands` as prompt templates, and skills in the
+  [Agent Skills](https://agentskills.io) format that the model loads only when a task needs them.
+- **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 +199,6 @@ 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)
 - [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.dist-info → lcode_cli-0.10.0.dist-info}/RECORD

@@ -1,23 +1,26 @@
-lcode/__init__.py,sha256=1p3bazCEuQ0WZP-SgRA-g8KVP4Avchrem5OtlxRTRHc,117
+lcode/__init__.py,sha256=Vt4u1brdsy5UMBysZVsHXtLIwN6S7GISlXj5GAGQI1w,118
 lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
-lcode/agent.py,sha256=uNQx8pcTzs4k05100wJedoPCZ7dUFjJz2OD2e__49VM,38597
+lcode/agent.py,sha256=5vSYZYFg-5doSF1yx3YRWI8hKSMCxPnSNzJiIwicY_8,40626
 lcode/bench.py,sha256=FCn94Gs7L8bpq4hzf6ILoQG8dKrbbd5WC4BRwrTp4LM,37950
 lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
 lcode/checkpoints.py,sha256=eqPtmPe44-aweWqc2H21ROogwzIt3NpvcUobsaCHoGY,18354
-lcode/cli.py,sha256=uc9F2HDflhu6cZbb2wARjllmM7KpN0FB9UfnyyFx_9U,29450
-lcode/config.py,sha256=KYgBRO-WN0Sl_YWd-XudqfE5NkV34w9OzQQJ3Apg2bs,7898
+lcode/cli.py,sha256=2xSELCKgYyqvJUAwG6P6qimZq6wmZGxwYAxCYfeZ7rk,30509
+lcode/config.py,sha256=HwOAz-9LFkH9hOlQwPPG26oIGtOfd0b2Wq2I09WxIAE,8297
+lcode/extensions.py,sha256=1MkCmfvQvcJt1XaqIEOYUruCTsrfQVI5TXOTWBkkJtI,15882
+lcode/frontmatter.py,sha256=Bx0n4vLPhp7ZCWx-g7xqzqNy5VoKBxyeeikh5UFB_gA,2441
 lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
 lcode/limits.py,sha256=oJzVQoMyTZ0_Fkpu5t3qxrf9v7Hv9S8U8BRQR5M1aKA,1237
-lcode/memory.py,sha256=ocr_2zDzmH1OCwrVjC-UmzRn4Sr1I_OeazhbIoSdIf0,22359
+lcode/memory.py,sha256=WZEHTp-lVxAwS-yyLQR2xB3TMZ9sejmX2Ivg7T-tl3w,21949
 lcode/models.toml,sha256=lt2G64zzo_Ryxv2ISRSNZoVD_JqCqYqsM01n8WoXGs8,4098
 lcode/ollama.py,sha256=0f2rkrm3_5Xcnuyvaxcfx5SeYVyRvHjiROXryHKmRUw,7085
 lcode/permissions.py,sha256=m8YNtCladVAmXB20ca8AwyfEOzHKS557B0SOvx1oHeM,4528
+lcode/planning.py,sha256=Z30K2tbqoy2XimKwth1lYYz7OVaQUXGdDvBgops7pGE,6076
 lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
-lcode/repl.py,sha256=0v_b5fFpxdAQU3TreTpDXdAUjWwePMkDW9MGIPiefNU,39521
+lcode/repl.py,sha256=FnyYpRuvpqmIVWQbMSvagrFBvFcLjIAedFeF32u5Vp4,43612
 lcode/sandbox.py,sha256=u_pkrVRXhCGhh-wFDPwuZ3jGG7UeXxXRAeBNsm37ZvE,8608
 lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
-lcode/subagents.py,sha256=L5U-USz2fnGOx3Z28_sOA6btWmMKSGXVbFKQYcrZSDM,28147
-lcode/tools.py,sha256=179FscWa9zmFGWEpbJekdpuBwheH2Oh_H9XTAP48yxM,33391
+lcode/subagents.py,sha256=ILGFwdFWfwKqExl2D5h_AArqlOris2N0aqh3Ccj895Q,28295
+lcode/tools.py,sha256=Af2pbx8KIR4uLaWk2opbzMY8ZFQ22mGcu8FnRbX9DsM,35486
 lcode/vision.py,sha256=w33QPmdGwP33wM4mvmAH4amFDZ1xzeXhEsSLJ-STSHY,4243
 lcode/web.py,sha256=vyxKbSRJTl1Lj3hj7Yd_NwTgbv0Xi6dup2YfUXjqp-Y,14579
 lcode/mcp/__init__.py,sha256=XujtAmRoXW9S0uq1XPf_CAeCkHh_UvA8FCmoAKP9j1Y,171
@@ -25,14 +28,14 @@ lcode/mcp/auth.py,sha256=vyH3oolgIBNJLYabr2h5Soui99NTY1QxjQEgtczfF6A,16655
 lcode/mcp/catalog.py,sha256=GnIF1fyeHSut9h2y_VJNAHc2FCJT81EIhLFM40V780k,3504
 lcode/mcp/catalog.toml,sha256=_kFzKD2FD78KD2URuE5B-kcQehW9Y3Zi2xf5tu3v4Xc,9230
 lcode/mcp/client.py,sha256=3Gen7zRvWehngXn_dAMOAdKqFkFkQZIQW96hQcW4N4k,7119
-lcode/mcp/commands.py,sha256=Rlnc-LFydRjHTiW-CSxjmQqX0d2MSiEViLF9kczYIi4,16420
+lcode/mcp/commands.py,sha256=mnp0G-GW5ZsARi2tkHuT3hl883sBGFUVRAV3AapA5oU,16478
 lcode/mcp/config.py,sha256=Ej6WX2b_55a84H5WdAwSk9DzERKoq5ifUBQ9uDgSG_o,8780
 lcode/mcp/http.py,sha256=sG9MajwU4_6sqvZhwD4WfyzRKzaR_Lc8C02jwePz18E,7380
 lcode/mcp/manager.py,sha256=79nNWoT5pxgoQD_Pv4ZH0obHIm7rQ-LyB8OmJnQgc6k,15104
 lcode/mcp/protocol.py,sha256=-xwhA2Tz-vzR2zdSdbPx4IjTu29uRrXMaePg0vEz_Vc,5223
 lcode/mcp/stdio.py,sha256=kC6KHwzMMDjBr-yCZLmyVKS7PZXU299WpZdYRoX5eRQ,6292
-lcode_cli-0.8.0.dist-info/METADATA,sha256=R2rlCNEpaoajSJzoThzX77UeTvAV_jv2qwQUlGeOoBI,11282
-lcode_cli-0.8.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-lcode_cli-0.8.0.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
-lcode_cli-0.8.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
-lcode_cli-0.8.0.dist-info/RECORD,,
+lcode_cli-0.10.0.dist-info/METADATA,sha256=qlFYNWlZjDePi7kqZ2JnRUVasJODV0Emqu6SDFhKvhI,11487
+lcode_cli-0.10.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lcode_cli-0.10.0.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
+lcode_cli-0.10.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
+lcode_cli-0.10.0.dist-info/RECORD,,