lcode-cli 0.14.0__tar.gz → 0.15.0__tar.gz

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/CHANGELOG.md

@@ -6,6 +6,27 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-05
+
+### Added
+
+- Hooks: shell commands that run on lcode's events (`before_tool`, `after_tool`, `after_request`,
+  `session_start`, `notification`), filtered by tool and file, with the event as JSON on stdin. A
+  `before_tool` hook that exits with code 2 blocks the call and tells the model why; an
+  `after_tool` hook's output reaches the model when it fails (a linter) or with `feedback = true`.
+  Notification hooks run when lcode waits for you and when a long request is done.
+- Permission rules: `[permissions]` allow and deny lists for shell commands, file edits, web
+  domains and MCP tools, checked before lcode asks. Deny always wins, even in `yolo` mode and for
+  read-only commands, and is enforced for subagents too.
+- Both go in `config.toml` or a repository's `.lcode/settings.toml`, which is used only once
+  approved (and approved again after any change). `lcode doctor` lists them. See
+  [Hooks and permission rules](https://nasser1941.github.io/lcode/hooks/), with recipes for ruff,
+  prettier, blocking force-pushes, running tests and desktop notifications.
+
+### Fixed
+
+- `lcode config set` no longer drops tables you added to `config.toml` by hand.
+
 ## [0.14.0] - 2026-10-05
 
 ### Added
@@ -364,7 +385,8 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/nasser1941/lcode/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/nasser1941/lcode/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/nasser1941/lcode/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/nasser1941/lcode/compare/v0.11.1...v0.12.0

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.14.0
+Version: 0.15.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/
@@ -89,6 +89,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   and sees the errors an edit introduced right away.
 - **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.
+- **Hooks and rules.** Format every edited file, block force-pushes, run the tests after each
+  request: shell hooks on lcode's events, and allow and deny lists that hold even in `yolo` mode.
 - **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
@@ -206,7 +208,8 @@ 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:
 
-- [Hooks and permission rules](https://github.com/nasser1941/lcode/issues/43)
+- [More local backends: LM Studio, llama.cpp, vLLM and MLX](https://github.com/nasser1941/lcode/issues/47)
+- [Git workflow: /commit, /review, /pr and parallel worktrees](https://github.com/nasser1941/lcode/issues/50)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 
 ## Contributing

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/README.md

@@ -53,6 +53,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   and sees the errors an edit introduced right away.
 - **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.
+- **Hooks and rules.** Format every edited file, block force-pushes, run the tests after each
+  request: shell hooks on lcode's events, and allow and deny lists that hold even in `yolo` mode.
 - **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
@@ -170,7 +172,8 @@ 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:
 
-- [Hooks and permission rules](https://github.com/nasser1941/lcode/issues/43)
+- [More local backends: LM Studio, llama.cpp, vLLM and MLX](https://github.com/nasser1941/lcode/issues/47)
+- [Git workflow: /commit, /review, /pr and parallel worktrees](https://github.com/nasser1941/lcode/issues/50)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 
 ## Contributing

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/docs/configuration.md

@@ -40,6 +40,10 @@ lcode config path                      # print the file location
 | `max_parallel_agents` | `1` | Subagents that run at the same time; more needs `OLLAMA_NUM_PARALLEL` on the Ollama server ([details](agents.md#several-at-once)) |
 | `checkpoints` | `true` | Save a checkpoint before the model changes files, so [`/undo`](usage.md#undo-and-checkpoints) can restore them |
 
+Besides these settings, `config.toml` can hold [hooks](hooks.md) (`[[hooks]]`) and
+[permission rules](hooks.md#permission-rules) (`[permissions]`); a repository can have its own in
+`.lcode/settings.toml`. `lcode config set` keeps them when it rewrites the file.
+
 Example file:
 
 ```toml

lcode_cli-0.15.0/docs/hooks.md

@@ -0,0 +1,134 @@
+# Hooks and permission rules
+
+Some things should happen whatever the model does: format every edited file, never force-push,
+run the tests when a request is done. Hooks and permission rules do that without relying on the
+model to follow instructions.
+
+They go in `~/.config/lcode/config.toml` (yours, for every repository) or in a repository's
+`.lcode/settings.toml` (shared with everyone who works on it). A repository's settings are used only
+after you [approve them](commands.md#approving-a-repositorys-commands-skills-and-agents), because
+hooks run commands; lcode asks again whenever the file changes.
+
+## Permission rules
+
+Rules are checked before lcode asks for permission. An **allow** rule lets an action through
+without asking; a **deny** rule blocks it, even in `yolo` mode and even for commands that are
+otherwise read-only. Deny always wins.
+
+```toml
+[permissions]
+allow = ["bash:pytest *", "bash:npm test", "bash:ruff *", "edit:src/**", "web:docs.python.org"]
+deny = ["bash:git push --force*", "bash:git push -f*", "bash:rm -rf /*", "edit:.env", "edit:**/*.pem"]
+```
+
+| Rule | Matches |
+|---|---|
+| `bash:<pattern>` | Shell commands, with `*` and `?` wildcards. A leading `cd <folder> &&` is ignored. A deny rule matches any part of a chained command (`git add . && git push --force`); an allow rule needs the whole command, or every part of it, to be allowed |
+| `edit:<pattern>` | Files the model writes or edits, relative to the repository's root. A pattern without a `/` matches the file name anywhere (`.env`, `*.pem`); `src/**` matches everything under `src` |
+| `web:<domain>` | Pages fetched from a domain; `web:search` for searches (only asked about with `web = "ask"`) |
+| `mcp:<server>:<tool>` | An [MCP](mcp.md) server's tools, e.g. `mcp:github:list_*` |
+
+When a rule blocks something, the model is told which rule, and not to work around it.
+
+## Hooks
+
+```toml
+[[hooks]]
+event = "after_tool"
+tools = ["edit_file", "write_file"]
+paths = ["*.py"]
+command = "ruff format {path} && ruff check --fix {path}"
+```
+
+| Event | Runs | What it can do |
+|---|---|---|
+| `before_tool` | Before a tool call | Exit with code **2** to block the call; what the hook printed tells the model why |
+| `after_tool` | After a tool call | Its output goes to the model when it exits with an error, or always with `feedback = true` |
+| `after_request` | When a request is done | Its output is shown to you |
+| `session_start` | When a session starts | Its output is shown, and with `feedback = true` given to the model |
+| `notification` | When lcode waits for your answer, and when a request that took over 30 seconds is done | Show a desktop notification, ring a bell |
+
+| Key | |
+|---|---|
+| `event` | One of the events above (required) |
+| `command` | Run with `bash -c` in the working directory (required). `{path}` and `{tool}` are replaced, quoted |
+| `tools` | Only for these tools (wildcards allowed), e.g. `["edit_file", "write_file"]` or `["mcp__*"]` |
+| `paths` | Only for these files, like the `edit:` rules: `["*.py"]`, `["src/**"]` |
+| `timeout` | Seconds before the hook is stopped (default 60) |
+| `feedback` | `true` to give the hook's output to the model even when it succeeds |
+
+Each hook gets the event as JSON on its standard input (the tool, its arguments, the file's full
+path, the result for `after_tool`, the working directory), and in the environment variables
+`LCODE_EVENT`, `LCODE_TOOL` and `LCODE_PATH`. Hooks run on your machine, also with the
+[sandbox](sandbox.md) on.
+
+## Recipes
+
+**Format and lint Python files after every edit** (lint problems go back to the model):
+
+```toml
+[[hooks]]
+event = "after_tool"
+tools = ["edit_file", "write_file"]
+paths = ["*.py"]
+command = "ruff format --quiet {path} && ruff check --fix --quiet {path}"
+```
+
+**Prettier for JavaScript and TypeScript:**
+
+```toml
+[[hooks]]
+event = "after_tool"
+tools = ["edit_file", "write_file"]
+paths = ["*.ts", "*.tsx", "*.js", "*.jsx", "*.css", "*.json"]
+command = "npx --no-install prettier --write {path} > /dev/null"
+```
+
+**Never force-push.** A rule is enough:
+
+```toml
+[permissions]
+deny = ["bash:git push --force*", "bash:git push -f*", "bash:git push * --force*"]
+```
+
+or, with a hook that explains the house rule to the model:
+
+```toml
+[[hooks]]
+event = "before_tool"
+tools = ["bash"]
+command = '''
+if jq -r .arguments.command | grep -Eq 'git push.*(--force|-f)'; then
+  echo "Force-pushing isn't allowed here: push to a new branch and open a pull request instead."
+  exit 2
+fi
+'''
+```
+
+**Run the tests when a request is done:**
+
+```toml
+[[hooks]]
+event = "after_request"
+command = "pytest -q -x 2>&1 | tail -3"
+timeout = 300
+```
+
+**A desktop notification** when lcode needs you or finishes a long request:
+
+```toml
+[[hooks]]
+event = "notification"
+command = "notify-send lcode \"$(jq -r .message)\""   # macOS: osascript -e "display notification \"…\""
+```
+
+**Tell the model what branch it's on** at the start of every session:
+
+```toml
+[[hooks]]
+event = "session_start"
+command = "git status --short --branch | head -20"
+feedback = true
+```
+
+`lcode doctor` lists the hooks and rules it found, and any it couldn't read.

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/docs/how-it-works.md

@@ -106,6 +106,7 @@ the Ollama server you configure, it only contacts the web when the model searche
 | `bench.py` | `lcode bench`: the benchmark tasks, their checks and the reports |
 | `vision.py` | Looking at images with a model that can see |
 | `subagents.py` | Subagents: agent types, running them (also in parallel), worktrees for workers |
+| `hooks.py` | Hooks on lcode's events, and allow and deny rules for permissions |
 | `repomap.py`, `codesearch.py` | The repository map, and semantic code search with an embedding model |
 | `lsp.py` | Language servers: the `lsp` tool and errors after edits |
 | `extensions.py` | Custom commands and skills, and approving a repository's own |

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/docs/quickstart.md

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

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/docs/usage.md

@@ -147,7 +147,8 @@ Read-only commands run without asking: `ls`, `cat`, `head`, `tail`, `grep`, `rg`
 output, chain commands or run subshells. A `cd <folder> &&` in front is fine.
 
 When asked, answer ++y++ (once), ++a++ (always, for this command or for all edits, until you quit)
-or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests with -x first`.
+or ++n++. For lasting answers, write [permission rules](hooks.md#permission-rules): allow lists and
+deny lists, per user or per repository; deny always wins, even in `yolo`. Text after ++n++ goes to the model as instructions: `n run the tests with -x first`.
 
 !!! warning "yolo mode"
 

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/mkdocs.yml

@@ -101,6 +101,7 @@ nav:
       - Benchmarking models: bench.md
       - MCP servers: mcp.md
       - Sandbox: sandbox.md
+      - Hooks and permission rules: hooks.md
       - Configuration: configuration.md
   - Reference:
       - How it works: how-it-works.md

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/src/lcode/__init__.py

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

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/src/lcode/agent.py

@@ -216,6 +216,9 @@ class Agent:
         self.checkpoints = Checkpoints(self.console, settings.checkpoints)
         self.mcp: McpManager | None = None  # set by the CLI when MCP servers are configured
         self.lsp = None  # an lcode.lsp.Manager, set by the CLI when language servers are installed
+        from lcode.hooks import HookSet
+
+        self.hooks = HookSet()  # set by the CLI from the settings (lcode.hooks)
         self._repo_map: tuple[Path, repomap.RepoMap, str] | None = None
         self._code_index: tuple[Path, codesearch.Index | None] | None = None
         self.sandbox = (
@@ -722,6 +725,14 @@ class Agent:
             self._run_turn(user_text)
         finally:
             self.checkpoints.end_turn()
+            if self.hooks.hooks and self.allowed_tools is None:
+                payload = {"request": user_text[:2000], "cwd": str(self.cwd), "session": self.session_id}
+                for outcome in self.hooks.run("after_request", payload, self.cwd):
+                    style = "dim" if outcome.code == 0 else "yellow"
+                    if outcome.output or outcome.code:
+                        self.console.print(
+                            Text(f"  ⎿ after_request hook ({outcome.code}): {outcome.output[:500]}", style=style)
+                        )
 
     def sandbox_root(self) -> Path | None:
         """The folder the model is limited to while the sandbox is on (None when it's off)."""

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/src/lcode/cli.py

@@ -368,7 +368,16 @@ 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 codesearch, extensions, lsp
+    from lcode import codesearch, extensions, hooks, lsp
+
+    hook_set, rules = hooks.load(Path.cwd(), extensions.status(Path.cwd()) == "approved")
+    if hook_set.hooks or rules or hook_set.problems:
+        events = sorted({h.event for h in hook_set.hooks})
+        summary = f"{len(hook_set.hooks)} hook(s) ({', '.join(events)})" if hook_set.hooks else "no hooks"
+        summary += f", {len(rules.allow)} allow and {len(rules.deny)} deny rule(s)"
+        line("Hooks", summary, not hook_set.problems or None)
+        for problem in hook_set.problems:
+            line("", problem, None)
     from lcode.checkpoints import work_tree_for
 
     if cfg["embed_model"] == "off":
@@ -602,6 +611,13 @@ def cmd_chat(args) -> None:
     )
     agent = Agent(ollama, settings, cwd, console=console)
     agent.interactive = not args.prompt
+    from lcode import hooks
+
+    agent.hooks, agent.perms.rules = hooks.load(cwd, trust_project)
+    for problem in agent.hooks.problems:
+        console.print(f"[yellow]Settings: {problem}[/]")
+    if agent.hooks.for_event("notification"):
+        agent.perms.on_prompt = lambda title: agent.hooks.notify(f"lcode needs you: {title}", agent.cwd)
     if cfg["lsp"] == "auto":
         from lcode import lsp
         from lcode.checkpoints import work_tree_for

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/src/lcode/config.py

@@ -187,5 +187,10 @@ def save(updates: dict, path: Path | None = None, remove: tuple[str, ...] = ())
         if data.get(k) is not None:
             v = data[k]
             lines.append(f"{k} = {str(v).lower() if isinstance(v, bool) else json.dumps(v)}")
+    tables = ""  # [[hooks]], [permissions] and anything else after the settings stay as they were
+    if path.is_file():
+        text = path.read_text()
+        m = re.search(r"^\s*\[", text, re.M)
+        tables = text[m.start() :] if m else ""
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text("\n".join(lines) + "\n")
+    path.write_text("\n".join(lines) + "\n" + ("\n" + tables.rstrip() + "\n" if tables.strip() else ""))

{lcode_cli-0.14.0 → lcode_cli-0.15.0}/src/lcode/extensions.py

@@ -286,7 +286,7 @@ def approvals_path() -> Path:
 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] = []
+    files: list[Path] = [root / ".lcode" / "settings.toml"] if (root / ".lcode" / "settings.toml").is_file() else []
     for folder in PROJECT_FOLDERS:
         base = root / folder
         if not base.is_dir():
@@ -359,6 +359,21 @@ def describe(cwd: Path) -> list[str]:
         lines.append(f"skills: {', '.join(project_skills)}")
     if agents:
         lines.append(f"agents: {', '.join(agents)}")
+    settings = root / ".lcode" / "settings.toml"
+    if settings.is_file():
+        from lcode.hooks import HookError, HookSet, Rules, read_toml
+
+        try:
+            data = read_toml(settings)
+            hook_set, rules = HookSet(), Rules()
+            hook_set.add(data, "")
+            rules.add(data, "")
+            commands = sorted({h.command.split()[0] for h in hook_set.hooks if h.command.split()})
+            parts = [f"{len(hook_set.hooks)} hook(s) running {', '.join(commands)}" if hook_set.hooks else ""]
+            parts.append(f"{len(rules.allow)} allow and {len(rules.deny)} deny rule(s)" if rules else "")
+            lines.append("settings: " + "; ".join(p for p in parts if p) if any(parts) else "settings: (empty)")
+        except HookError as e:
+            lines.append(f"settings: {e}")
     return lines
 
 
@@ -378,8 +393,8 @@ def trust_project(cwd: Path, console: Console, interactive: bool) -> bool:
     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).[/]"
+        "[dim]They can steer the model and include scripts it may run, and its settings can run hooks "
+        "(shell commands) on lcode's events.[/]"
     )
     try:
         answer = input("  Use them? [y/N] ").strip().lower()

lcode_cli-0.15.0/src/lcode/hooks.py

@@ -0,0 +1,241 @@
+"""Hooks and permission rules: what should always happen, whatever the model does.
+
+Hooks are shell commands that run on lcode's events, set in `~/.config/lcode/config.toml` or, per
+repository, in `.lcode/settings.toml` (used once you approve it, like the repository's commands):
+
+    [[hooks]]
+    event = "after_tool"              # before_tool | after_tool | after_request | session_start | notification
+    tools = ["edit_file", "write_file"]
+    paths = ["*.py"]
+    command = "ruff format {path} && ruff check --fix {path}"
+
+The event comes as JSON on stdin (and `{path}`, `{tool}` in the command are replaced, quoted). A
+`before_tool` hook that exits with code 2 blocks the call, and what it printed tells the model why.
+An `after_tool` hook's output reaches the model when it fails, or always with `feedback = true`.
+
+Permission rules are checked before lcode asks, and deny always wins, even in yolo mode:
+
+    [permissions]
+    allow = ["bash:pytest *", "bash:npm test", "edit:src/**"]
+    deny = ["bash:git push --force*", "edit:.env"]
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+from lcode import config
+from lcode.checkpoints import work_tree_for
+
+EVENTS = ("before_tool", "after_tool", "after_request", "session_start", "notification")
+BLOCK = 2  # exit code of a before_tool hook that blocks the call
+MAX_OUTPUT = 4000
+FILE_TOOLS = {"read_file", "write_file", "edit_file", "view_image", "list_dir"}
+
+
+class HookError(ValueError):
+    pass
+
+
+def project_settings(cwd: Path) -> Path:
+    return work_tree_for(cwd) / ".lcode" / "settings.toml"
+
+
+def read_toml(path: Path) -> dict:
+    try:
+        return tomllib.loads(path.read_text())
+    except OSError:
+        return {}
+    except tomllib.TOMLDecodeError as e:
+        raise HookError(f"{path} isn't valid TOML: {e}") from e
+
+
+# ----------------------------------------------------------------------------- permission rules
+
+
+def strip_cd(command: str) -> str:
+    return re.sub(r"^\s*(cd\s+\S+\s*&&\s*)+", "", command).strip()
+
+
+def matches_path(pattern: str, path: str) -> bool:
+    """gitignore-like: a pattern without a slash matches the file name anywhere."""
+    if "/" not in pattern.rstrip("/"):
+        return fnmatch.fnmatch(Path(path).name, pattern) or fnmatch.fnmatch(path, pattern)
+    pattern = pattern.removeprefix("./").removeprefix("/")
+    return fnmatch.fnmatch(path, pattern) or (pattern.startswith("**/") and fnmatch.fnmatch(path, pattern[3:]))
+
+
+@dataclass
+class Rules:
+    allow: list[tuple[str, str]] = field(default_factory=list)  # (rule, where it's from)
+    deny: list[tuple[str, str]] = field(default_factory=list)
+
+    def add(self, data: dict, source: str) -> None:
+        section = data.get("permissions") or {}
+        for kind in ("allow", "deny"):
+            values = section.get(kind) or []
+            if not isinstance(values, list) or not all(isinstance(v, str) and ":" in v for v in values):
+                raise HookError(f'{source}: permissions.{kind} must be a list of rules like "bash:pytest *"')
+            getattr(self, kind).extend((v, source) for v in values)
+
+    def _matches(self, rule: str, kind: str, target: str) -> bool:
+        rule_kind, _, pattern = rule.partition(":")
+        if rule_kind != kind or not target:
+            return False
+        if kind == "bash":
+            return fnmatch.fnmatch(strip_cd(target), pattern)
+        if kind == "edit":
+            return matches_path(pattern, target)
+        return fnmatch.fnmatch(target, pattern)
+
+    def check(self, kind: str, target: str) -> tuple[str | None, str]:
+        """("deny" or "allow", the rule and where it's from), or (None, "")."""
+        if kind == "bash":  # a denied command stays denied inside a chain: git add . && git push --force
+            parts = [p for p in re.split(r"\s*(?:&&|\|\||;|\|)\s*", strip_cd(target)) if p]
+            for rule, source in self.deny:
+                if any(self._matches(rule, kind, part) for part in [target, *parts]):
+                    return "deny", f"{rule} ({source})"
+            for rule, source in self.allow:
+                if self._matches(rule, kind, target):
+                    return "allow", f"{rule} ({source})"
+            if parts and all(any(self._matches(r, kind, part) for r, _ in self.allow) for part in parts):
+                return "allow", "every part of the command is allowed"
+            return None, ""
+        for rule, source in self.deny:
+            if self._matches(rule, kind, target):
+                return "deny", f"{rule} ({source})"
+        for rule, source in self.allow:
+            if self._matches(rule, kind, target):
+                return "allow", f"{rule} ({source})"
+        return None, ""
+
+    def __bool__(self) -> bool:
+        return bool(self.allow or self.deny)
+
+
+# ----------------------------------------------------------------------------- hooks
+
+
+@dataclass
+class Hook:
+    event: str
+    command: str
+    source: str
+    tools: list[str] = field(default_factory=list)
+    paths: list[str] = field(default_factory=list)
+    timeout: float = 60.0
+    feedback: bool = False
+
+    def applies(self, tool: str = "", path: str = "") -> bool:
+        if self.tools and not any(fnmatch.fnmatch(tool, t) for t in self.tools):
+            return False
+        return not self.paths or bool(path and any(matches_path(p, path) for p in self.paths))
+
+
+@dataclass
+class Outcome:
+    hook: Hook
+    code: int
+    output: str
+
+
+@dataclass
+class HookSet:
+    hooks: list[Hook] = field(default_factory=list)
+    problems: list[str] = field(default_factory=list)
+
+    def add(self, data: dict, source: str) -> None:
+        entries = data.get("hooks") or []
+        if not isinstance(entries, list):
+            raise HookError(f"{source}: hooks must be [[hooks]] tables")
+        for entry in entries:
+            event, command = entry.get("event"), entry.get("command")
+            if event not in EVENTS or not isinstance(command, str) or not command.strip():
+                self.problems.append(f"{source}: a hook needs an event ({', '.join(EVENTS)}) and a command")
+                continue
+            self.hooks.append(
+                Hook(
+                    event=event,
+                    command=command,
+                    source=source,
+                    tools=list(entry.get("tools") or []),
+                    paths=list(entry.get("paths") or []),
+                    timeout=float(entry.get("timeout") or 60),
+                    feedback=bool(entry.get("feedback", False)),
+                )
+            )
+
+    def for_event(self, event: str, tool: str = "", path: str = "") -> list[Hook]:
+        return [h for h in self.hooks if h.event == event and h.applies(tool, path)]
+
+    def run(self, event: str, payload: dict, cwd: Path, tool: str = "", path: str = "") -> list[Outcome]:
+        outcomes = []
+        for hook in self.for_event(event, tool, path):
+            outcomes.append(run_hook(hook, {"event": event, **payload}, cwd, tool, path))
+        return outcomes
+
+    def notify(self, message: str, cwd: Path) -> None:
+        """Notification hooks, in the background: lcode doesn't wait for them."""
+        hooks = self.for_event("notification")
+        if hooks:
+
+            def go() -> None:
+                for hook in hooks:
+                    run_hook(hook, {"event": "notification", "message": message}, cwd, "", "")
+
+            threading.Thread(target=go, daemon=True).start()
+
+
+def run_hook(hook: Hook, payload: dict, cwd: Path, tool: str, path: str) -> Outcome:
+    command = hook.command.replace("{path}", shlex.quote(path) if path else "").replace("{tool}", shlex.quote(tool))
+    env = {**os.environ, "LCODE_EVENT": payload.get("event", ""), "LCODE_TOOL": tool, "LCODE_PATH": path}
+    try:
+        r = subprocess.run(
+            ["bash", "-c", command],
+            input=json.dumps(payload, default=str),
+            capture_output=True,
+            text=True,
+            timeout=hook.timeout,
+            cwd=cwd,
+            env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return Outcome(hook, 124, f"the hook took longer than {hook.timeout:.0f}s and was stopped")
+    except OSError as e:
+        return Outcome(hook, 127, str(e))
+    output = (r.stdout + ("\n" if r.stdout and r.stderr else "") + r.stderr).strip()
+    return Outcome(hook, r.returncode, output[:MAX_OUTPUT])
+
+
+# ----------------------------------------------------------------------------- loading
+
+
+def load(cwd: Path, trust_project: bool) -> tuple[HookSet, Rules]:
+    """The user's hooks and rules, plus the repository's when its settings are approved."""
+    hooks, rules = HookSet(), Rules()
+    sources = [(config.CONFIG_PATH, str(config.CONFIG_PATH))]
+    if trust_project:
+        project = project_settings(cwd)
+        sources.append((project, str(project)))
+    for path, label in sources:
+        try:
+            data = read_toml(path)
+            hooks.add(data, label)
+            rules.add(data, label)
+        except HookError as e:
+            hooks.problems.append(str(e))
+    return hooks, rules