@veda-hq/kavach 0.5.6 → 0.6.4

package/README.md

@@ -8,7 +8,7 @@ judged before it runs. Part of [Veda](https://github.com/veda-hq/veda).
 | Guard | Refuses | Entry point |
 | --- | --- | --- |
 | Worktree boundary | Any write outside the agent's own git worktree: a Bash command, an Edit or a Write; and, while a push runs, any write into it (below). Read-only commands pass from any checkout. | `python3 python/kavach/worktree_guard.py` |
-| Command guard | Git-hook bypasses (`--no-verify`, `core.hooksPath`…), history-destroying pushes, and the project's own command rules (settings below). | `python3 python/kavach/command_guard.py` |
+| Command guard | Git-hook bypasses (`--no-verify`, `core.hooksPath`…), history-destroying pushes, and the project's own command rules (settings below). On trial, it warns of a message the shell would change (below). | `python3 python/kavach/command_guard.py` |
 | Rule checks | The project's own checks, written in TypeScript, refusing or warning with the rule's reason. | `kavach-rule-checks` (`dist/rule-checks/cli.js`) |
 
 The two Python guards read one Claude Code `PreToolUse` event on stdin. Exit
@@ -50,6 +50,20 @@ the worktree, bypass hooks or force-push, each executed in real bash to prove
 it does what its row says, and near-miss commands that must pass. Each guard
 must refuse every attack row and pass every near-miss.
 
+## What a refusal says
+
+Each refusal names the way out. "mutation targets could not be resolved"
+goes on to name what in the command the guard could not read (a redirection
+into a file, a heredoc, a pipeline, a `;`/`&&` chain, `$(...)` or backticks,
+an interpreter running a file such as `node <file>`, a program it does not
+know), then the alternative: one plain command per call, files written with
+the Edit or Write tools, and anything more as a script under the worktree's
+`.tmp/` run through the repository's package runner (`pnpm exec tsx
+.tmp/x.ts`). A write outside the worktree says where it aimed (the main
+checkout, another worktree or its git folder, the repository's git folder, a
+system temp folder) and where it belongs instead. The leading words of each
+refusal are unchanged, so searches of older logs still match.
+
 ## Settings
 
 `KAVACH_CONFIG` names a JSON file; unset, every project rule is off. A file
@@ -60,6 +74,10 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   "worktree": {
     "trustedCommands": [
       { "script": "scripts/worktree.py", "pattern": "python3 scripts/worktree\\.py (?:status|retire --pr [1-9][0-9]*)" }
+    ],
+    "readOnlyCommands": [
+      { "pattern": "pnpm (?:health:check|(?:ls|list|why)(?: [A-Za-z0-9@][A-Za-z0-9@/._-]*)*(?: --depth [0-9]+)?)",
+        "env": { "AGENT_REMOTE": ["true"] }, "reason": "the script and pnpm's listing commands only read" }
     ]
   },
   "command": {
@@ -67,7 +85,9 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
     "protectedVariablesReason": "it marks a hosted session; leave it as the session set it",
     "pairedChanges": [
       { "changes": "schema.sql", "requires": "changesets/", "reason": "a schema change needs its changeset" }
-    ]
+    ],
+    "shellExpansion": "warn",
+    "shellExpansionRefusesFrom": "2026-11-21"
   }
 }
 ```
@@ -77,6 +97,14 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   pattern must match the whole command; trust only command lines of plain
   words (a whole line with any shell metacharacter is never trusted by its
   pattern alone).
+- `readOnlyCommands`: a command line you reviewed as only reading, though
+  the guard cannot prove it (a package runner's script, say). It runs with no
+  owned worktree, from a checkout's root only, and only while the hook's own
+  environment holds one of the listed values for every variable in `env`,
+  which is required. The pattern is matched as a trusted command's is. Keep
+  the list to commands that write nothing however they are called, and
+  name each option a pattern allows: a runner's own options after the
+  subcommand (`pnpm ls -C elsewhere`, `--pnpmfile`) move or widen what runs.
 - `protectedVariables`: environment variables a command may not assign, declare or
   export.
 - `pairedChanges`: a commit that may record a path ending in `changes` must
@@ -85,6 +113,45 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   longer refused for that reason alone (`--no-verify` and the rest still are).
   Keep a CI check behind it: the guard reads one command line, not the files
   other programs change.
+- `shellExpansion`: `"warn"` (the default) or `"refuse"`, the mode of the
+  rule on trial below. `shellExpansionRefusesFrom` (a day, `YYYY-MM-DD`) is
+  only shown in its warning; nothing switches on that day. A kavach older
+  than this rule refuses every call on these unknown keys, so add them only
+  once the pinned kavach knows them.
+
+## A rule on trial: messages the shell changes
+
+In bash and zsh a double-quoted (or unquoted) message is expanded before git
+reads it: ``git commit -m "fix `parse`"`` runs `parse` and commits "fix ",
+`$(...)` does the same, and an interactive shell replaces `!word` from its
+history. commitlint reads only the header, so the loss ships. The command
+guard finds backticks, `$(...)` and `!word` (a `!` before a blank, `=`, `(`,
+a closing quote or the end is left alone) in the value of `git commit` and
+`git tag`'s `-m`/`--message`, and of `--body`/`-b` on `gh pr create`,
+`comment`, `edit` and `review` and `gh issue create`, `comment` and `edit`.
+Single quotes, an escaped `` \` ``, `-F <file>` and `--body-file` are fine,
+and so is a value that is wholly one command substitution
+(`-m "$(cat file)"`, `--body "$(git log -1 --format=%s)"`): its author meant
+the expansion, so nothing is lost. A substitution or backticks inside other
+text (`-m "fix $(foo) bar"`) still fire, except `$(cat <<'EOF' ... EOF)`,
+the heredoc whose text arrives whole (with an unquoted delimiter only while
+its body runs nothing). This rule lets that heredoc pass; the worktree
+boundary still refuses any heredoc, so from a worktree use `-F <file>`.
+
+A new refusal starts by warning, since a wrong one would stop every session
+at once. In `"warn"` the command runs, and the guard answers on stdout:
+
+```json
+{"hookSpecificOutput": {"hookEventName": "PreToolUse",
+  "additionalContext": "kavach warning (refuses from 2026-11-21): the shell expands the backticks `parse` inside this double-quoted -m before git sees it, ..."}}
+```
+
+In `"refuse"` it exits 2 with the same reason. Either way each fire is a row
+of the refusal log naming the rule (`commit-message-shell-expansion`) and the
+mode, so the trial's fires can be read for wrong ones before it refuses. Any
+other refusal of the same command comes first. While it warns, an error in
+the rule's own detection allows the call and logs a warning row naming the
+error's type; refusing, it fails closed, as every other check always does.
 
 ## While a push runs
 
@@ -117,7 +184,8 @@ Without the marker, nothing here changes.
 
 Each refusal of the two Python guards appends a row (time, guard, tool, first
 line of the reason, start of the command) to
-`<git common dir>/kavach/refusals.jsonl`. It is best effort and never changes
+`<git common dir>/kavach/refusals.jsonl`; a rule on trial adds a row for
+each warning too, and names itself in its rows (`rule`, `mode`). It is best effort and never changes
 a verdict; `KAVACH_REFUSAL_LOG_OFF=1` turns it off. The rule-check engine
 keeps its own fire log (`--fires-dir`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/kavach",
-  "version": "0.5.6",
+  "version": "0.6.4",
   "description": "Guards for coding agents: refuses writes outside the agent's worktree, git-hook bypasses and history-destroying pushes, and runs a project's own rule checks on each tool call. Read-only commands pass.",
   "keywords": [
     "coding agents",

package/python/kavach/boundary.py

@@ -16,7 +16,7 @@ import stat
 import subprocess
 import sys
 from pathlib import Path
-from typing import Protocol, Sequence
+from typing import Mapping, Protocol, Sequence
 
 
 # Admission to this set means one thing: NO invocation of the command mutates
@@ -3246,22 +3246,10 @@ def trusted_request(
 
     if not trusted:
         return False
-    # A loose pattern (`.*`) must not trust a whole line that hides another
-    # command: the whole-line match holds only for plain words.
-    plain = TRUSTED_LINE_UNSAFE.search(command) is None
-    opening: tuple[str, list[list[str]]] | None = None
-    rest_is_inert: bool | None = None
+    line = ReviewedLine(command)
     for entry in trusted:
-        if not (plain and entry.pattern.fullmatch(command)):
-            if opening is None:
-                opening = trusted_opening(command)
-            first, rest = opening
-            if not first or not entry.pattern.fullmatch(first):
-                continue
-            if rest_is_inert is None:
-                rest_is_inert = all(segment_is_read_only(words) for words in rest)
-            if not rest_is_inert:
-                continue
+        if not line.matches(entry.pattern):
+            continue
         resolved = root.resolve()
         script = resolved / entry.script
         if cwd.resolve() == resolved and script.is_file() and script.resolve() == script:
@@ -3269,6 +3257,78 @@ def trusted_request(
     return False
 
 
+class ReviewedLine:
+    """One command line, as a consumer's reviewed pattern is matched to it.
+
+    A whole line of plain words matches when the pattern matches all of it. A
+    loose pattern (`.*`) must not admit a line that hides another command, so
+    any other line matches only by its first segment, as plain words, followed
+    by nothing but read-only segments (reviewed redirections included). The
+    parse is done once, for the first pattern that needs it.
+    """
+
+    def __init__(self, command: str) -> None:
+        self.command = command
+        self.plain = TRUSTED_LINE_UNSAFE.search(command) is None
+        self.opening: tuple[str, list[list[str]]] | None = None
+        self.rest_is_inert: bool | None = None
+
+    def matches(self, pattern: re.Pattern[str]) -> bool:
+        if self.plain and pattern.fullmatch(self.command):
+            return True
+        if self.opening is None:
+            self.opening = trusted_opening(self.command)
+        first, rest = self.opening
+        if not first or not pattern.fullmatch(first):
+            return False
+        if self.rest_is_inert is None:
+            self.rest_is_inert = all(segment_is_read_only(words) for words in rest)
+        return self.rest_is_inert
+
+
+class ReadOnlyEntry(Protocol):
+    """One reviewed read-only command, as `config.ReadOnlyCommand` carries it:
+    `pattern` must match the whole command line, and `env` pairs each
+    variable with the values the hook's environment may hold for it."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+
+
+def read_only_request(
+    command: str,
+    cwd: Path,
+    root: Path,
+    entries: Sequence[ReadOnlyEntry],
+    environ: Mapping[str, str],
+) -> bool:
+    """Recognize a command line the consumer reviewed as only reading.
+
+    Such a command reads although this parser cannot prove it: a package
+    runner's script, say, whose writes are the consumer's to review, not
+    kavach's. It needs no owned worktree, so the match is held as tight as a
+    trusted command's (``ReviewedLine``), and two more conditions apply:
+
+    - It runs from the checkout's root (``root``), so a relative script or
+      a package manifest means the root's own, never a subfolder's.
+    - Every variable the entry names holds one of its listed values in
+      ``environ``, the hook's own environment, which the command line cannot
+      set.
+
+    No entries: nothing is admitted here.
+    """
+
+    if not entries or cwd.resolve() != root.resolve():
+        return False
+    line = ReviewedLine(command)
+    for entry in entries:
+        if all(environ.get(name) in values for name, values in entry.env) and line.matches(
+            entry.pattern
+        ):
+            return True
+    return False
+
+
 def trusted_opening(command: str) -> tuple[str, list[list[str]]]:
     """The first segment of ``command`` as plain words, and the segments after.
 

package/python/kavach/command_guard.py

@@ -10,6 +10,12 @@ command that sets a protected variable, and a commit that records one path
 of a paired change without the other. Each is read from the repository the
 command actually targets.
 
+One rule is on trial: a message the shell would change before git or gh
+reads it (backticks, ``$(...)`` or ``!word`` in a double-quoted ``-m`` or
+``--body``). Until the settings say ``"shellExpansion": "refuse"`` it allows
+the command and prints a PreToolUse answer on stdout that puts the warning in
+front of the agent; either way each fire is a row of the refusal log.
+
 Two checks, and the command runs only when both allow it: bash_guard.py
 first, then git_safety.py, which reads the code the first cannot (below)
 and runs against the adversarial corpus in ``corpus/``, every row of which
@@ -124,7 +130,28 @@ def cannot_name_git():
         command = json.loads(os.environ["HOOK_INPUT"])["tool_input"]["command"]
     except Exception:
         return False
-    return isinstance(command, str) and not re.search(r"(?i)git|[\\\x27\"$`*?\[{|<>(]", command)
+    if not isinstance(command, str) or re.search(r"(?i)git|[\\\x27\"$`*?\[{|<>(]", command):
+        return False
+    # `gh pr comment 1 -b fix!now` has a message git_safety.py reads; a `!`
+    # anywhere else (`if ! make; then ...`) keeps the fast exit it had.
+    return not ("!" in command and re.search(r"(?<![\w.-])gh(?![\w.-])", command))
+
+
+def fired(rule, mode, message):
+    """Log one fire of a rule on trial (git_safety.hook_main's ``fired``): a
+    refusal's row is written as it ends, named here; a warning's now, since
+    an allowed call writes no row of its own. Logging never changes a
+    verdict."""
+    try:
+        import refusal_log
+        if mode == "refuse":
+            refusal_log.label(rule, mode)
+        else:
+            refusal_log.record(
+                "command", os.environ.get("HOOK_INPUT", ""), "WARNING: " + message, rule=rule, mode=mode
+            )
+    except BaseException:
+        return
 
 
 def main():
@@ -146,7 +173,7 @@ def main():
         return 0
     return verdict(
         "the shell-code check",
-        lambda: __import__("git_safety").hook_main(loaded),
+        lambda: __import__("git_safety").hook_main(loaded, fired),
         "git_safety.py",
         "git_safety",
     )

package/python/kavach/config.py

@@ -2,9 +2,10 @@
 the environment variable KAVACH_CONFIG.
 
 kavach knows no product. What one product trusts or requires (a script its
-agents may run from any checkout, environment variables an agent must leave
-alone, a file whose change needs another in the same commit) comes from this
-file, and with no file every such rule is off.
+agents may run from any checkout, a command it reviewed as only reading and allows in one
+environment, environment variables an agent must leave alone, a file whose change needs another in the same commit) comes from this
+file, and with no file every such rule is off. So does the mode of a rule on
+trial (`command.shellExpansion`), which warns until the file says "refuse".
 
 A file that cannot be read, is not JSON, has a key this module does not know,
 or a value of the wrong shape raises ConfigError. Each guard's entry point
@@ -38,6 +39,18 @@ class TrustedCommand:
     pattern: re.Pattern[str]
 
 
+@dataclass(frozen=True)
+class ReadOnlyCommand:
+    """A command line the consumer reviewed as only reading, allowed from a
+    checkout's root without an owned worktree, and only where the hook's own
+    environment holds one of the listed values for every variable in `env`.
+    `pattern` must match the whole command; `reason` says what was checked."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+    reason: str
+
+
 @dataclass(frozen=True)
 class PairedChange:
     """A commit that may record a path ending in `changes` must also certainly
@@ -54,14 +67,27 @@ class Config:
     protected_variables: tuple[str, ...] = ()
     protected_variables_reason: str = ""
     paired_changes: tuple[PairedChange, ...] = ()
+    read_only_commands: tuple[ReadOnlyCommand, ...] = ()
+    # The shell-expansion rule (git_safety.py): "warn" allows with a warning,
+    # "refuse" blocks. A new refusal warns first, so the default is "warn".
+    shell_expansion: str = "warn"
+    # The day it is to start refusing, shown in its warning (YYYY-MM-DD).
+    # Shown only: what makes it refuse is "refuse" above, set once its log
+    # shows no wrong fire.
+    shell_expansion_refuses_from: str = ""
 
 
 DEFAULT = Config()
+SHELL_EXPANSION_MODES = ("warn", "refuse")
+DAY = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
 
 SHAPE: dict[str, set[str]] = {
     "": {"worktree", "command"},
-    "worktree": {"trustedCommands"},
-    "command": {"protectedVariables", "protectedVariablesReason", "pairedChanges"},
+    "worktree": {"trustedCommands", "readOnlyCommands"},
+    "command": {
+        "protectedVariables", "protectedVariablesReason", "pairedChanges",
+        "shellExpansion", "shellExpansionRefusesFrom",
+    },
 }
 
 
@@ -100,6 +126,32 @@ def _trusted(value: Any, index: int) -> TrustedCommand:
     return TrustedCommand(script, pattern)
 
 
+def _read_only(value: Any, index: int) -> ReadOnlyCommand:
+    where = f"worktree.readOnlyCommands[{index}]"
+    entry = _object(value, where, {"pattern", "env", "reason"})
+    source = _text(entry.get("pattern"), f"{where}.pattern")
+    try:
+        pattern = re.compile(source)
+    except re.error as error:
+        raise ConfigError(f"{where}.pattern is not a regular expression: {error}") from None
+    # The environment is required: an entry with no condition would widen the
+    # guard on every machine, which is what kavach's own read-only list is
+    # kept narrow to avoid.
+    raw_env = entry.get("env")
+    if not isinstance(raw_env, dict) or not raw_env:
+        raise ConfigError(f"{where}.env must be a non-empty JSON object of variable names")
+    env: list[tuple[str, tuple[str, ...]]] = []
+    for name, values in raw_env.items():
+        if not VARIABLE_NAME.fullmatch(name):
+            raise ConfigError(f"{where}.env has a key that is not a variable name: {name!r}")
+        listed = _list(values, f"{where}.env.{name}")
+        if not listed:
+            raise ConfigError(f"{where}.env.{name} must list at least one value")
+        env.append((name, tuple(_text(item, f"{where}.env.{name}[{at}]") for at, item in enumerate(listed))))
+    reason = _text(entry.get("reason"), f"{where}.reason")
+    return ReadOnlyCommand(pattern, tuple(env), reason)
+
+
 def _paired(value: Any, index: int) -> PairedChange:
     where = f"command.pairedChanges[{index}]"
     entry = _object(value, where, {"changes", "requires", "reason"})
@@ -135,7 +187,17 @@ def parse(data: Any) -> Config:
         _paired(entry, index)
         for index, entry in enumerate(_list(command.get("pairedChanges", []), "command.pairedChanges"))
     )
-    return Config(trusted, variables, reason, paired)
+    read_only = tuple(
+        _read_only(entry, index)
+        for index, entry in enumerate(_list(worktree.get("readOnlyCommands", []), "worktree.readOnlyCommands"))
+    )
+    mode = command.get("shellExpansion", "warn")
+    if mode not in SHELL_EXPANSION_MODES:
+        raise ConfigError(f"command.shellExpansion must be one of {', '.join(SHELL_EXPANSION_MODES)}")
+    refuses_from = command.get("shellExpansionRefusesFrom", "")
+    if refuses_from != "" and not (isinstance(refuses_from, str) and DAY.fullmatch(refuses_from)):
+        raise ConfigError("command.shellExpansionRefusesFrom must be a day, YYYY-MM-DD")
+    return Config(trusted, variables, reason, paired, read_only, mode, refuses_from)
 
 
 def load(environ: Mapping[str, str] | None = None) -> Config:

package/python/kavach/git_safety.py

@@ -44,7 +44,7 @@ import shlex
 import subprocess
 import sys
 from dataclasses import dataclass, field
-from typing import Any, Sequence
+from typing import Any, Callable, Sequence
 
 MAX_DEPTH = 6
 
@@ -74,6 +74,11 @@ class Blocked(Exception):
     """Raised with the reason a command is refused."""
 
 
+class DetectionError(Exception):
+    """The shell-expansion detection failed while lexing a message word;
+    its text is the type of the error the lexer met."""
+
+
 # ---------------------------------------------------------------------------
 # Lexing: the subset of bash that decides which words a command receives.
 # ---------------------------------------------------------------------------
@@ -103,6 +108,10 @@ class Word:
     glob_leading: bool = False
     # An unquoted `{a,b}` / `{1..3}`: bash turns the word into several.
     braces: bool = False
+    # What the shell replaces in this word that a message's author likely
+    # meant as text (Analyzer.shell_expansion): (kind, the fragment as typed).
+    # Kinds: "backticks", "substitution" (`$(...)`), "history" (`!word`).
+    hazards: list[tuple[str, str]] = field(default_factory=list)
 
     def could_be_flag(self) -> bool:
         """Might the shell turn this word into something starting with '-'/'+'?"""
@@ -373,6 +382,34 @@ class Lexer:
 
     # -- expansions ----------------------------------------------------------
 
+    def hazard(self, find: Callable[[], tuple[str, str] | None]) -> None:
+        """Note what ``find`` finds the shell would change in this word. The
+        finding is the shell-expansion rule's alone, so an error in it never
+        stops the lexing the other checks need: it is noted as an ("error",
+        <type>) hazard, which the rule turns into its own failure if the word
+        is a message (Analyzer.message_value)."""
+
+        try:
+            found = find()
+        except Exception as error:
+            found = ("error", type(error).__name__)
+        if found is not None:
+            self.word.hazards.append(found)
+
+    def history(self, index: int) -> None:
+        """Note a `!` at ``index`` that an interactive shell's history
+        expansion would replace: one followed by a word, not by a blank, `=`,
+        `(`, a closing quote or the end (`fix!`, `a != b` stay text)."""
+
+        def find() -> tuple[str, str] | None:
+            following = self.text[index + 1 : index + 2]
+            if not following or following in " \t\n=(\"":
+                return None
+            fragment = re.match(r"![^\s\"';&|()<>]*", self.text[index:])
+            return ("history", fragment.group(0) if fragment else "!")
+
+        self.hazard(find)
+
     def dollar(self, in_double: bool) -> None:
         text, index = self.text, self.index
         following = text[index + 1 : index + 2]
@@ -380,7 +417,15 @@ class Lexer:
             # `$((...))` arithmetic closes the same way; its body, analysed as
             # a program, is a harmless subshell unless it nests a `$(...)`.
             end = matching_close(text, index + 2, "(", ")")
-            self.word.bodies.append(text[index + 2 : end - 1])
+            body = text[index + 2 : end - 1]
+            # Arithmetic gives a number, never lost text; a heredoc read by
+            # `cat` is how a message is meant to be substituted.
+            self.hazard(
+                lambda: None
+                if body.startswith("(") or heredoc_message(body)
+                else ("substitution", text[index:end])
+            )
+            self.word.bodies.append(body)
             self.add(text[index:end], dynamic=True)
             self.index = end
             return
@@ -421,6 +466,8 @@ class Lexer:
         if end < 0:
             raise Blocked("unterminated backquote")
         body = self.text[self.index + 1 : end].replace("\\`", "`")
+        fragment = self.text[self.index : end + 1]
+        self.hazard(lambda: ("backticks", fragment))
         self.word.bodies.append(body)
         self.add(self.text[self.index : end + 1], dynamic=True)
         self.index = end + 1
@@ -538,6 +585,8 @@ class Lexer:
                 self.add(char)
                 self.index += 1
                 continue
+            if char == "!":
+                self.history(self.index)
             self.add(char)
             self.index += 1
         self.finish_command(";")
@@ -571,12 +620,19 @@ class Lexer:
                     self.add(text[self.index + 1], quoted=True)
                 self.index += 2
                 continue
+            if char == "\\" and text[self.index + 1 : self.index + 2] == "!":
+                # `\!` stops history expansion; bash keeps the backslash.
+                self.add("\\!", quoted=True)
+                self.index += 2
+                continue
             if char == "$":
                 self.dollar(in_double=True)
                 continue
             if char == "`":
                 self.backquote()
                 continue
+            if char == "!":
+                self.history(self.index)
             self.add(char, quoted=True)
             self.index += 1
         raise Blocked("unterminated double quote")
@@ -597,6 +653,30 @@ def parse(script: str) -> list[Command]:
     return Lexer(script).run()
 
 
+def heredoc_message(body: str) -> bool:
+    """Whether a `$(...)` body is the heredoc idiom for a message,
+    `cat <<'EOF' ... EOF`: one plain `cat` reading one heredoc whose body
+    runs nothing. Its text arrives whole; that is what the idiom is for. With
+    an unquoted delimiter a `$(...)` or backtick in the body still runs, so
+    that body is no exemption."""
+
+    try:
+        commands = parse(body)
+    except Blocked:
+        return False
+    if len(commands) != 1:
+        return False
+    (command,) = commands
+    return (
+        [(word.text, word.dynamic, word.quoted) for word in command.words] == [("cat", False, False)]
+        and len(command.heredocs) == 1
+        and not command.expanded_bodies
+        and not command.redirect_targets
+        and not command.input_targets
+        and not command.herestrings
+    )
+
+
 # ---------------------------------------------------------------------------
 # Analysis.
 # ---------------------------------------------------------------------------
@@ -721,6 +801,86 @@ def dangerous_long(word: str) -> str | None:
     return None
 
 
+# The shell-expansion rule (`command.shellExpansion` in config.py): a message
+# given on the command line in double quotes (or none) loses what the shell
+# expands in it. `git commit -m "fix `parse`"` runs `parse` and commits "fix ";
+# `!word` is replaced by an interactive shell's history. commitlint reads only
+# the header, so the loss ships. A message from a file (`-F`, `--body-file`),
+# in single quotes, or read by `$(cat <<'EOF' ... EOF)` arrives whole.
+SHELL_EXPANSION_RULE = "commit-message-shell-expansion"
+SHELL_EXPANSION_MODES = ("warn", "refuse")
+# gh's commands whose `--body`/`-b` is the text written; elsewhere `-b` may
+# mean another thing (`gh pr checkout -b <branch>`).
+GH_BODY_COMMANDS = {
+    ("pr", "create"), ("pr", "comment"), ("pr", "edit"), ("pr", "review"),
+    ("issue", "create"), ("issue", "comment"), ("issue", "edit"),
+}
+# Their other options that take a value, so a value is never read as `-b`.
+GH_VALUE_OPTIONS = {
+    "-t", "--title", "-B", "--base", "-H", "--head", "-a", "--assignee", "-l", "--label",
+    "-m", "--milestone", "-p", "--project", "-r", "--reviewer", "-R", "--repo", "-F",
+    "--body-file", "-T", "--template", "--add-label", "--remove-label", "--add-assignee",
+    "--remove-assignee", "--add-reviewer", "--remove-reviewer", "--add-project", "--remove-project",
+}
+# git tag's long options that take the next word as their value.
+TAG_VALUE_LONG = {
+    "--file", "--local-user", "--cleanup", "--sort", "--format", "--contains", "--no-contains",
+    "--points-at", "--merged", "--no-merged", "--trailer",
+}
+EXPANSION_KINDS = {
+    "backticks": "the backticks {}",
+    "substitution": "the command substitution {}",
+    "history": "the history expansion {}",
+}
+FRAGMENT_LIMIT = 60
+
+
+def is_message_option(name: str) -> bool:
+    """`--message` or an abbreviation git resolves to it (`--mes`)."""
+
+    return len(name) > 2 and "--message".startswith(name)
+
+
+@dataclass(frozen=True)
+class Expansion:
+    """One expansion the shell makes in a message value: the program
+    (`git commit`, `gh pr create`), the option, what is expanded (a kind of
+    EXPANSION_KINDS and the text as typed), and whether the value was quoted."""
+
+    program: str
+    flag: str
+    kind: str
+    fragment: str
+    quoted: bool
+
+
+def shell_expansion_message(found: Sequence[Expansion]) -> str:
+    """The rule's reason, naming each expansion of the first option found."""
+
+    first = found[0]
+    named: list[str] = []
+    for item in found:
+        if (item.program, item.flag) != (first.program, first.flag):
+            continue
+        fragment = item.fragment.replace("\n", " ")
+        if len(fragment) > FRAGMENT_LIMIT:
+            fragment = fragment[: FRAGMENT_LIMIT - 3] + "..."
+        named.append(EXPANSION_KINDS[item.kind].format(fragment))
+    what = named[0] if len(named) == 1 else ", ".join(named[:-1]) + " and " + named[-1]
+    quoting = "double-quoted" if first.quoted else "unquoted"
+    tool = first.program.split(" ", 1)[0]
+    if first.program == "git commit":
+        remedy = "Write the message to a file and use `git commit -F <file>` (or `gh ... --body-file <file>`)."
+    elif first.program == "git tag":
+        remedy = "Write the message to a file and use `git tag -F <file>`."
+    else:
+        remedy = f"Write the body to a file and use `{first.program} --body-file <file>`."
+    return (
+        f"the shell expands {what} inside this {quoting} {first.flag} before {tool} sees it, "
+        f"so that text silently disappears from the message. {remedy}"
+    )
+
+
 @dataclass
 class Scope:
     """What earlier commands in the same script changed for later ones."""
@@ -812,7 +972,12 @@ def expand_braces(words: list[Word]) -> list[Word]:
             continue
         alternatives = None if word.first_quoted is not None else brace_alternatives(word.text)
         if alternatives is None:
-            out.append(Word(text=word.text, dynamic=True, quoted=word.quoted, bodies=word.bodies, started=True, first_dynamic=0))
+            out.append(
+                Word(
+                    text=word.text, dynamic=True, quoted=word.quoted, bodies=word.bodies, started=True,
+                    first_dynamic=0, hazards=word.hazards,
+                )
+            )
             continue
         for index, text in enumerate(alternatives):
             out.append(
@@ -825,14 +990,28 @@ def expand_braces(words: list[Word]) -> list[Word]:
                     first_dynamic=word.first_dynamic,
                     glob=any(char in text for char in "*?["),
                     glob_leading=text[:1] in ("*", "?", "["),
+                    hazards=word.hazards if index == 0 else [],
                 )
             )
     return out
 
 
 class Analyzer:
-    def __init__(self, base_cwd: str | None, read_config: bool = True, paired_changes: Sequence[Any] = ()) -> None:
+    def __init__(
+        self,
+        base_cwd: str | None,
+        read_config: bool = True,
+        paired_changes: Sequence[Any] = (),
+        tolerate_detection: bool = False,
+    ) -> None:
         self.base_cwd = base_cwd
+        # The shell-expansion rule on trial ("warn") must not stop a call by
+        # failing: an error in its detection is then noted in
+        # `detection_failures` (the error's type) and the analysis goes on.
+        # Refusing, it fails closed like every other check: the error
+        # propagates and the entry blocks.
+        self.tolerate_detection = tolerate_detection
+        self.detection_failures: list[str] = []
         self.read_config = read_config
         # The consumer's paired changes (config.PairedChange: `changes`,
         # `requires`, `reason`); empty turns the env -C half of that rule off.
@@ -846,6 +1025,48 @@ class Analyzer:
         # The current command (or a program it runs) was moved by `env -C`,
         # which bash_guard.py's paired-change model does not follow.
         self.chdir_by_env = False
+        # Messages the shell would change before git or gh reads them, in the
+        # order found, each once (a program may be read twice).
+        self.expansions: list[Expansion] = []
+
+    def detect(self, step: Callable[[], None]) -> None:
+        """Run one step of the shell-expansion detection, which is nothing
+        the other checks rely on; see ``tolerate_detection``."""
+
+        try:
+            step()
+        except Exception as error:
+            if not self.tolerate_detection:
+                raise
+            name = str(error) if isinstance(error, DetectionError) else type(error).__name__
+            self.detection_failures.append(name)
+
+    def message_value(
+        self, program: str, flag: str, word: Word, value: str | None = None, option: str | None = None
+    ) -> None:
+        """Note what the shell expands in ``word``, the value of ``flag``;
+        ``value`` is the value's text when the word also holds the option
+        (`-m"$(x)"`, `--body=$(x)`). With ``option``, only when that option
+        is `--message` (or git's abbreviation of it).
+
+        A value that is wholly one command substitution (`"$(cat file)"`,
+        `` "`git log -1`" ``) is the author's own choice: its output is the
+        message, and nothing is lost. One inside other text is the slip."""
+
+        def step() -> None:
+            if option is not None and not is_message_option(option):
+                return
+            text = word.text if value is None else value
+            for kind, fragment in word.hazards:
+                if kind == "error":
+                    raise DetectionError(fragment)
+                if kind in ("substitution", "backticks") and text == fragment:
+                    continue
+                found = Expansion(program, flag, kind, fragment, word.quoted)
+                if found not in self.expansions:
+                    self.expansions.append(found)
+
+        self.detect(step)
 
     # -- entry -------------------------------------------------------------
 
@@ -1047,6 +1268,8 @@ class Analyzer:
                         raise Blocked(f"'{name}' on '{word.text}' can disable the repository hooks. {HOOK_REMEDY}")
         if name == "git":
             self.git(words, scope, depth)
+        elif name == "gh":
+            self.detect(lambda: self.gh(words))
 
     @staticmethod
     def written_operands(name: str, operands: list[Word]) -> list[Word]:
@@ -1420,6 +1643,8 @@ class Analyzer:
         elif name == "config":
             self.config(args)
         else:
+            if name == "tag":
+                self.detect(lambda: self.tag(args))
             for word in args:
                 if word.text == "--":
                     break
@@ -1565,6 +1790,9 @@ class Analyzer:
                 # `--message="$MSG"`: the option NAME is literal, only its value is not.
                 if is_no_verify(literal):
                     raise Blocked(f"--no-verify is forbidden on all git commands. {HOOK_REMEDY}")
+                self.message_value(
+                    "git commit", "--message", word, text.split("=", 1)[1], option=literal.split("=", 1)[0]
+                )
                 index += 1
                 continue
             if literal.startswith("-") and len(literal) > 1 and not literal.startswith("--"):
@@ -1578,7 +1806,11 @@ class Analyzer:
                     if flag in "mFCct":
                         consumed = True
                         if position == len(cluster) - 1 and literal == text:
+                            if flag == "m" and index + 1 < len(args):
+                                self.message_value("git commit", "-m", args[index + 1])
                             index += 1  # the value is the next word
+                        elif flag == "m":
+                            self.message_value("git commit", "-m", word, text[position + 2 :])
                         break
                     if flag in "Su":
                         consumed = True
@@ -1596,11 +1828,84 @@ class Analyzer:
                 # git takes any unambiguous abbreviation (`--mes '-n'` is a
                 # message); an ambiguous one is an error and nothing runs.
                 takes_value = len(text) > 2 and any(option.startswith(text) for option in value_long)
+                if takes_value and index + 1 < len(args):
+                    self.message_value("git commit", "--message", args[index + 1], option=text)
                 index += 2 if takes_value else 1
                 continue
             index += 1
         return stages_all
 
+    def tag(self, args: list[Word]) -> None:
+        """Note the shell's expansions in git tag's message values."""
+
+        index = 0
+        while index < len(args):
+            word = args[index]
+            text = word.text
+            literal = text if word.first_dynamic is None else text[: word.first_dynamic]
+            index += 1
+            if text == "--":
+                return
+            if literal.startswith("--"):
+                name, attached, _value = literal.partition("=")
+                if is_message_option(name):
+                    if attached:
+                        self.message_value("git tag", "--message", word, text.split("=", 1)[1])
+                    elif index < len(args):
+                        self.message_value("git tag", "--message", args[index])
+                        index += 1
+                elif not attached and len(name) > 2 and any(option.startswith(name) for option in TAG_VALUE_LONG):
+                    index += 1
+                continue
+            if literal.startswith("-") and len(literal) > 1:
+                cluster = literal[1:]
+                for position, flag in enumerate(cluster):
+                    if flag not in "mFu":
+                        continue
+                    last = position == len(cluster) - 1 and literal == text
+                    if flag == "m":
+                        if not last:
+                            self.message_value("git tag", "-m", word, text[position + 2 :])
+                        elif index < len(args):
+                            self.message_value("git tag", "-m", args[index])
+                    if last:
+                        index += 1
+                    break
+
+    def gh(self, words: list[Word]) -> None:
+        """Note the shell's expansions in the body of a gh pull request or
+        issue, created, edited, reviewed or commented on."""
+
+        command: list[str] = []
+        index = 1
+        while index < len(words) and len(command) < 2:
+            text = words[index].text
+            index += 1
+            if text in ("-R", "--repo"):
+                index += 1
+            elif not text.startswith("-"):
+                command.append(text)
+        if tuple(command) not in GH_BODY_COMMANDS:
+            return
+        program = "gh " + " ".join(command)
+        while index < len(words):
+            word = words[index]
+            text = word.text
+            literal = text if word.first_dynamic is None else text[: word.first_dynamic]
+            index += 1
+            if text == "--":
+                return
+            if literal in ("-b", "--body") and literal == text:
+                if index < len(words):
+                    self.message_value(program, literal, words[index])
+                    index += 1
+            elif literal.startswith("--body="):
+                self.message_value(program, "--body", word, text.split("=", 1)[1])
+            elif literal.startswith("-b") and not literal.startswith("--"):
+                self.message_value(program, "-b", word, text[2:])
+            elif literal in GH_VALUE_OPTIONS and literal == text:
+                index += 1
+
     def push(
         self,
         args: list[Word],
@@ -1917,12 +2222,38 @@ def check(
     ``paired_changes`` are the consumer's (config.PairedChange); none turns
     that rule off."""
 
-    analyzer = Analyzer(cwd, read_config=read_config, paired_changes=paired_changes)
+    return analyse(command, cwd, read_config=read_config, paired_changes=paired_changes)[0]
+
+
+def analyse(
+    command: str, cwd: str | None, *, read_config: bool = True, paired_changes: Sequence[Any] = ()
+) -> tuple[str | None, list[Expansion]]:
+    """``check``'s reason, and the expansions the shell would make in the
+    command's messages (the shell-expansion rule, judged by ``hook_main``)."""
+
+    reason, analyzer = analysed(command, cwd, read_config=read_config, paired_changes=paired_changes)
+    return reason, analyzer.expansions
+
+
+def analysed(
+    command: str,
+    cwd: str | None,
+    *,
+    read_config: bool = True,
+    paired_changes: Sequence[Any] = (),
+    tolerate_detection: bool = False,
+) -> tuple[str | None, Analyzer]:
+    """``check``'s reason and the Analyzer that read the command, whose
+    ``expansions`` and ``detection_failures`` the shell-expansion rule reads."""
+
+    analyzer = Analyzer(
+        cwd, read_config=read_config, paired_changes=paired_changes, tolerate_detection=tolerate_detection
+    )
     try:
         analyzer.script(command, cwd)
     except Blocked as reason:
-        return str(reason)
-    return None
+        return str(reason), analyzer
+    return None, analyzer
 
 
 # ---------------------------------------------------------------------------
@@ -1961,20 +2292,86 @@ def read_hook_input(raw: str) -> tuple[str, str]:
     return command, cwd if isinstance(cwd, str) and os.path.isabs(cwd) else os.getcwd()
 
 
-def hook_main(settings: Any = None) -> None:
+# The way out for a refusal that names none: what this guard can read is a
+# git command written out plainly.
+PLAIN_REMEDY = (
+    "Run the git command as a plain command of its own, with literal words: no eval, "
+    "`bash -c`, pipe into a shell or wrapper option around it, and nothing computed at run time."
+)
+REMEDIES = (HOOK_REMEDY, FORCE_REMEDY, AMBIGUOUS_REMEDY, PAIRED_REMEDY, "Write the flags literally")
+
+
+def with_way_out(reason: str) -> str:
+    """``reason``, ending in the way out when it names none of its own."""
+
+    if any(remedy in reason for remedy in REMEDIES):
+        return reason
+    return f"{reason.rstrip('.')}. {PLAIN_REMEDY}"
+
+
+def warning(message: str, refuses_from: str) -> str:
+    """The PreToolUse answer that allows the call and puts ``message`` in
+    front of the agent: one JSON object, the whole of stdout."""
+
+    when = f"refuses from {refuses_from}" if refuses_from else "refuses after its trial"
+    context = (
+        f"kavach warning ({when}): {message} This call still runs while the rule is on trial: "
+        "check the text it wrote and correct it."
+    )
+    return json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": context}})
+
+
+def hook_main(settings: Any = None, fired: Any = None) -> None:
     """command_guard.py's second check: the hook input is in ``HOOK_INPUT``,
-    ``settings`` the consumer's config.Config (None: no paired changes).
+    ``settings`` the consumer's config.Config (None: no paired changes, the
+    shell-expansion rule warns).
 
     Always ends in SystemExit(0) or SystemExit(2); the entry blocks on any
     other end, an exception included. The paired-change rule is
     bash_guard.py's, whose index model the command-guard suite holds, except
     for commits moved by `env -C` (Analyzer.env_chdir_paired).
+
+    The shell-expansion rule runs in the mode ``settings`` gives it: "refuse"
+    blocks, "warn" allows with the warning (``warning``) on stdout. Any other
+    refusal comes first. ``fired(rule, mode, message)``, when given, hears of
+    each fire before the verdict, so the entry can log it.
+
+    While it warns, the rule cannot stop a call by failing: an error in its
+    detection (finding message values and what the shell expands in them,
+    building its reason) allows the call and is reported to ``fired`` as a
+    warning that names the error's type, so the trial's log shows it. Every
+    other check fails closed as before, and so does the rule once it refuses.
     """
 
     paired = tuple(getattr(settings, "paired_changes", ()))
+    mode = getattr(settings, "shell_expansion", "warn")
+    refuses_from = getattr(settings, "shell_expansion_refuses_from", "")
+    tolerate = mode != "refuse"
     command, cwd = read_hook_input(os.environ.get("HOOK_INPUT", ""))
     if command.strip():
-        reason = check(command, cwd, paired_changes=paired)
+        reason, analyzer = analysed(command, cwd, paired_changes=paired, tolerate_detection=tolerate)
         if reason is not None:
-            block(f"BLOCKED: {reason}")
+            block(f"BLOCKED: {with_way_out(reason)}")
+        failures = list(analyzer.detection_failures)
+        message = None
+        if analyzer.expansions:
+            try:
+                message = shell_expansion_message(analyzer.expansions)
+            except Exception as error:
+                if not tolerate:
+                    raise
+                failures.append(type(error).__name__)
+        if failures and fired is not None:
+            named = ", ".join(dict.fromkeys(failures))
+            fired(
+                SHELL_EXPANSION_RULE,
+                mode,
+                f"the shell-expansion check failed ({named}), so it did not judge this command; the call was allowed.",
+            )
+        if message is not None:
+            if fired is not None:
+                fired(SHELL_EXPANSION_RULE, mode, message)
+            if mode == "refuse":
+                block(f"BLOCKED: {message}")
+            print(warning(message, refuses_from))
     raise SystemExit(0)

package/python/kavach/refusal_log.py

@@ -4,7 +4,10 @@ say which refusals a guard made and how often.
 Where: ``<git common dir>/kavach/refusals.jsonl`` of the repository the
 event's ``cwd`` belongs to, shared by all of its worktrees. Each row holds the
 time, the guard, the tool, the first line of the reason and the start of the
-command or path. Commands can hold secrets typed on a command line, so the log
+command or path. A rule on trial also writes a row each time it only warns,
+and names itself in both kinds of row (``rule``, ``mode``: "warn" or
+"refuse"), so its trial can be read for wrong fires before it refuses.
+Commands can hold secrets typed on a command line, so the log
 stays inside the repository's git directory, never in the working tree.
 
 Best effort: logging never changes a verdict. Any failure (no git, no
@@ -75,8 +78,30 @@ def excerpt(tool_input: Any) -> str:
     return ""
 
 
-def record(guard: str, raw_input: str, stderr_text: str, now: Callable[[], float] = time.time) -> None:
-    """Append one row for a refusal; never raises."""
+# The rule and mode the next refusal row names (``label``), taken by it.
+_LABEL: dict[str, str] = {}
+
+
+def label(rule: str, mode: str) -> None:
+    """Name the rule and mode of the refusal about to be made, so its one
+    row says which rule fired and in which mode."""
+
+    _LABEL.clear()
+    _LABEL.update(rule=rule, mode=mode)
+
+
+def record(
+    guard: str,
+    raw_input: str,
+    stderr_text: str,
+    now: Callable[[], float] = time.time,
+    *,
+    rule: str | None = None,
+    mode: str | None = None,
+) -> None:
+    """Append one row for a refusal, or for a warning (``mode`` "warn");
+    never raises. ``rule`` and ``mode`` are written only when given, so the
+    rows of rules with no name keep their shape."""
 
     try:
         if os.environ.get(OFF_VAR):
@@ -102,6 +127,10 @@ def record(guard: str, raw_input: str, stderr_text: str, now: Callable[[], float
             "reason": reason,
             "excerpt": excerpt(event.get("tool_input")),
         }
+        if rule is not None:
+            row["rule"] = rule
+        if mode is not None:
+            row["mode"] = mode
         directory.mkdir(parents=True, exist_ok=True)
         with open(directory / FILE, "a", encoding="utf-8") as handle:
             handle.write(json.dumps(row, ensure_ascii=False) + "\n")
@@ -140,9 +169,13 @@ def guarded(guard: str, body: Callable[[], Any], raw_input: Callable[[], str] |
     previous = sys.stderr, sys.stdin
     sys.stderr, sys.stdin = stderr, stdin  # type: ignore[assignment]
 
+    _LABEL.clear()
+
     def log() -> None:
         text = raw_input() if raw_input is not None else stdin.copy.getvalue()
-        record(guard, text, stderr.copy.getvalue())
+        named = dict(_LABEL)
+        _LABEL.clear()
+        record(guard, text, stderr.copy.getvalue(), rule=named.get("rule"), mode=named.get("mode"))
 
     try:
         result = body()

package/python/kavach/worktree_guard.py

@@ -22,8 +22,10 @@ import importlib.util
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 from types import ModuleType
 from typing import Any, NoReturn
@@ -399,7 +401,227 @@ def denial(target: Path, root: Path, primary: Path) -> str:
             f"; agent memory is writable only when {expected} is a real directory"
             " (it is missing, or it or its parent is a symlink)"
         )
-    return message
+        return message
+    try:
+        return message + where_instead(target, root, primary)
+    except Exception:
+        # Words only: a hint that fails must not turn the denial into a crash.
+        return message + GENERIC_INSTEAD
+
+
+GENERIC_INSTEAD = "; write only inside this worktree, and keep scratch files in its .tmp/"
+
+
+def system_temp_roots() -> list[Path]:
+    """The system's temp folders, resolved: where scratch files go by habit."""
+
+    roots = [Path("/tmp"), Path("/var/tmp"), Path(tempfile.gettempdir())]
+    if os.environ.get("TMPDIR"):
+        roots.append(Path(os.environ["TMPDIR"]))
+    return [root.resolve() for root in roots]
+
+
+def linked_worktrees(git_dir: Path) -> list[tuple[Path, Path]]:
+    """Each linked worktree's own git folder and its work tree, read from
+    ``<git dir>/worktrees/*/gitdir``; what cannot be read is left out."""
+
+    found: list[tuple[Path, Path]] = []
+    try:
+        entries = sorted((git_dir / "worktrees").iterdir())
+    except OSError:
+        return found
+    for entry in entries:
+        try:
+            pointer = (entry / "gitdir").read_text(encoding="utf-8").strip()
+        except (OSError, ValueError):
+            continue
+        if pointer:
+            found.append((entry.resolve(), Path(pointer).parent.resolve()))
+    return found
+
+
+def where_instead(target: Path, root: Path, primary: Path) -> str:
+    """Where the write belongs instead, after naming the place it aimed at.
+
+    Only words: the verdict is already made. Generic on purpose, since every
+    consumer's checkout differs: the main checkout, another worktree or its
+    git folder, the repository's git folder, a system temp folder, elsewhere.
+    """
+
+    resolved, checkout, own = target.resolve(), primary.resolve(), root.resolve()
+    git_dir = checkout / ".git"
+    own_git_dir = git_dir_of(root)
+    worktrees = linked_worktrees(git_dir)
+    if own_git_dir is not None and boundary.is_inside(resolved, own_git_dir.resolve()):
+        return "; that is this worktree's git folder: change it only through git commands run in this worktree"
+    if boundary.is_inside(resolved, git_dir / "worktrees"):
+        return (
+            "; that is another worktree's git folder: for this worktree's own branch run git here, and "
+            "for anything else write a script under this worktree's .tmp/ and run it from this worktree"
+        )
+    if boundary.is_inside(resolved, git_dir):
+        return "; that is the repository's git folder: change it only through git commands run in this worktree"
+    if any(boundary.is_inside(resolved, tree) for _gitdir, tree in worktrees if tree != own):
+        return (
+            "; that is another worktree, which another session may own: make the change in this "
+            "worktree, or ask the user to make it there"
+        )
+    if boundary.is_inside(resolved, checkout):
+        relative = resolved.relative_to(checkout)
+        return (
+            f"; that is the main checkout: make the change in this worktree's own copy, {own / relative}"
+        )
+    if any(boundary.is_inside(resolved, temp) for temp in system_temp_roots()):
+        return (
+            "; that is a system temp folder: keep scratch files in this worktree's .tmp/ "
+            "(keep it git-ignored) and write them with the Edit or Write tools"
+        )
+    return GENERIC_INSTEAD
+
+
+UNRESOLVED = "mutation targets could not be resolved"
+WAY_OUT = (
+    "Run one plain command per call; write files with the Edit or Write tools; for more, write a "
+    "script under this worktree's .tmp/ and run it through the repository's package runner "
+    "(for example `pnpm exec tsx .tmp/x.ts`)."
+)
+REDIRECTION_WAY_OUT = (
+    " A redirection into a file is never read, wherever it points: drop it and read the output, "
+    "or write the file with Write."
+)
+HEREDOC_WAY_OUT = (
+    " Write a heredoc's text to a file with Write instead (for a commit message, `git commit -F <file>`)."
+)
+INTERPRETERS = {
+    "python", "python2", "python3", "node", "nodejs", "bun", "deno", "perl", "ruby", "php", "lua",
+    "tsx", "ts-node", "osascript", "pwsh", "bash", "sh", "zsh", "dash", "ksh", "mksh", "fish",
+}
+SHELL_NAMES = {"bash", "sh", "zsh", "dash", "ksh", "mksh", "fish"}
+# The option that makes each interpreter run its next word as a program.
+INLINE_FLAGS = {"-e", "--eval", "-p", "--print"}
+SHOWN = 80
+
+
+def inline_flags(head: str) -> set[str]:
+    if head in SHELL_NAMES or head.startswith("python"):
+        return {"-c"}
+    if head == "osascript":
+        return {"-e"}
+    if head == "pwsh":
+        return {"-c", "-Command"}
+    return INLINE_FLAGS
+
+
+def shell_reader() -> ModuleType | None:
+    """git_safety.py's shell lexer, which sees quoting, to name what a
+    refused command holds; None when it cannot load (the refusal then names
+    nothing). Loaded only for a refusal, so an allowed call never pays."""
+
+    name = "kavach_worktree_shell"
+    if name in sys.modules:
+        return sys.modules[name]
+    try:
+        spec = importlib.util.spec_from_file_location(name, HERE / "git_safety.py")
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        spec.loader.exec_module(module)
+    except (Exception, SystemExit):
+        sys.modules.pop(name, None)
+        return None
+    return module
+
+
+def shown(text: str) -> str:
+    text = text.replace("\n", " ")
+    return text if len(text) <= SHOWN else text[: SHOWN - 3] + "..."
+
+
+def unreadable_constructs(command: str, cwd: Path) -> list[str]:
+    """What in ``command`` keeps its writes from being read, most specific
+    first: a heredoc, a redirection into a file, a substitution, an
+    interpreter, a program the guard does not know, then a pipeline or a
+    chain. Words for a refusal only: the verdict is ``mutation_directories``'s."""
+
+    reader = shell_reader()
+    if reader is None:
+        return []
+    try:
+        commands = reader.parse(command)
+    except Exception:
+        return []
+    found: list[str] = []
+
+    def add(text: str) -> None:
+        if text not in found:
+            found.append(text)
+
+    for each in commands:
+        if each.heredocs:
+            add("a heredoc (`<<`)")
+    for each in commands:
+        for target in each.redirect_targets:
+            if target.text != os.devnull and not re.fullmatch(r"[0-9]+|-", target.text):
+                add(f"an output redirection (`>` to {shown(target.text)})")
+    if any(
+        word.bodies
+        for each in commands
+        for word in (*each.words, *each.redirect_targets, *each.input_targets, *each.herestrings)
+    ) or any(each.expanded_bodies for each in commands):
+        add("a command substitution (`$(...)`, backticks or `<(...)`)")
+    for each in commands:
+        words = list(each.words)
+        while words and words[0].is_assignment() is not None:
+            words.pop(0)
+        if not words or words[0].dynamic:
+            continue
+        head = os.path.basename(words[0].text)
+        if head in INTERPRETERS or re.fullmatch(r"python[0-9]+(\.[0-9]+)*", head):
+            inline = next((word.text for word in words[1:] if word.text in inline_flags(head)), None)
+            if inline is not None:
+                add(f"an inline {head} program (`{head} {inline}`)")
+            elif any(not word.text.startswith("-") for word in words[1:]):
+                typed = " ".join(word.text for word in words)
+                add(f"an interpreter running a file or module (`{shown(typed)}`)")
+            continue
+        own = each.heredocs or each.redirect_targets or any(word.bodies or word.dynamic for word in words)
+        if not own and boundary.mutation_directories(shlex.join(word.text for word in words), cwd) is None:
+            add(f"`{head}`, a program whose writes the guard does not know")
+    if any(each.piped_from is not None for each in commands):
+        add("a pipeline (`|`)")
+    if any(each.follows in (";", "&&", "||", "\n", "&") for each in commands[1:]):
+        add("a chain of commands (`;`, `&&` or `||`)")
+    return found
+
+
+def unresolved(tool: object, values: dict[str, object], cwd: Path) -> str:
+    """The refusal for a call whose writes could not be read, naming what in
+    it could not be read and the way out. The leading words stay as they
+    were, so earlier logs and searches still match."""
+
+    if tool != "Bash":
+        return (
+            f"{UNRESOLVED}: the file path cannot be read as one place. "
+            "Give the tool an absolute path inside this worktree."
+        )
+    command = boundary.tool_command(values)
+    try:
+        found = unreadable_constructs(command, cwd) if command else []
+    except Exception:
+        found = []
+    if not found:
+        return f"{UNRESOLVED}: the guard cannot read off this command what it writes. {WAY_OUT}"
+    named = found[0] if len(found) == 1 else ", ".join(found[:-1]) + " and " + found[-1]
+    extra = ""
+    if any(item.startswith("an output redirection") for item in found):
+        extra += REDIRECTION_WAY_OUT
+    if "a heredoc (`<<`)" in found:
+        extra += HEREDOC_WAY_OUT
+    return (
+        f"{UNRESOLVED}: this command uses {named}, so the guard cannot read off it what it writes. "
+        f"{WAY_OUT}{extra}"
+    )
 
 
 # A push in progress (0086 P-06). A pre-push hook that runs kavach's
@@ -594,7 +816,8 @@ def refuse_during_push(tool: object, targets: list[Path], root: Path) -> None:
 def main() -> None:
     # First, so a misread settings file refuses every event, a read-only one
     # included.
-    trusted = settings().trusted_commands
+    loaded = settings()
+    trusted = loaded.trusted_commands
     data = boundary.read_input()
     cwd = Path(data.get("cwd") or Path.cwd()).resolve()
     state = boundary.checkout_state(cwd)
@@ -616,6 +839,13 @@ def main() -> None:
         command = boundary.tool_command(values)
         if command and boundary.shell_is_read_only(command):
             return
+        # A read the consumer reviewed (`worktree.readOnlyCommands`), from the
+        # checkout's root and only in the environment its entry names: like a
+        # proven read, it needs no owned worktree and waits for no push.
+        if command and boundary.read_only_request(
+            command, cwd, root, loaded.read_only_commands, os.environ
+        ):
+            return
     # Only the shell parser reads these (a file tool is never given them), and
     # finding them costs git starts, so an Edit or Write does not pay for them.
     read_namespaces = harness_state_roots(root, primary) if tool == "Bash" else ()
@@ -644,7 +874,7 @@ def main() -> None:
         refuse_during_push(tool, [root], root)
         return
     if targets is None:
-        boundary.deny("mutation targets could not be resolved")
+        boundary.deny(unresolved(tool, values, cwd))
     for target in targets:
         # From inside an owned worktree the two allowances compose, so
         # `touch <memory>/note.md` works while the same command with a second