@ethlete/agent-rules 0.1.0-next.31 → 0.1.0-next.33

package/content/hooks/git-safety.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: git safety in a checkout several agents share.
+
+Denies, for a Bash call:
+- `git add -A`, `git add --all` and `git add .` (they stage other sessions' work)
+- every `git stash` that writes (bare, `push`, `save`, `pop`, `apply`, `drop`, `clear`, `branch`,
+  `create`, `store`); `git stash list` and `git stash show` stay allowed
+- `git commit --amend`
+- `git commit` without a ` -- <paths>` pathspec, except the commit that concludes a merge: while
+  `MERGE_HEAD` exists and every staged path changed between HEAD and MERGE_HEAD or is conflicted
+
+`git commit-tree` and `git update-index` stay allowed, so a merge commit built on a temporary
+GIT_INDEX_FILE works. Only real command positions count: commit messages (`-m`, `--message`), quoted text and heredoc
+bodies are ignored, so a grep pattern or message that mentions `git stash` does not trip the hook.
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json at the repo
+root: {"disableHooks": true} or {"disableHooks": ["git-safety"]}.
+
+Fail-safe: any error exits 0 with no output.
+"""
+
+import json
+import os
+import re
+import subprocess
+import sys
+
+HOOK_NAME = "git-safety"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+MESSAGE_ARG = re.compile(
+    r"""(?:^|(?<=\s))(?:-[a-zA-Z]*m|--message)(?:=|\s*)(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s;&|]*)"""
+)
+SEGMENT_SPLIT = re.compile(r"[;&|\n()`]+")
+HEREDOC = re.compile(r"<<-?[ \t]*(['\"]?)(\w+)\1([^\n]*)\n(?:.*?\n)?[ \t]*\2[ \t]*(?=\n|$)", re.DOTALL)
+QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
+GLOBAL_OPTS_WITH_VALUE = ("-C", "-c", "--git-dir", "--work-tree", "--namespace")
+ADD_ALL = ("-A", "--all", ".")
+
+def agent_name(argv):
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    if not root:
+        return {}
+    try:
+        with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
+            config = json.load(f)
+    except (OSError, ValueError, AttributeError):
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    disabled = config.get("disableHooks")
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def git_calls_in(command):
+    """Yield (subcommand, args) for every command-position git call in the shell string."""
+    stripped = MESSAGE_ARG.sub(" ", HEREDOC.sub(r"<<\3", command))
+    unquoted = QUOTED.sub(lambda m: re.sub(r"[\s;&|(`]", "_", m.group(0)[1:-1]), stripped)
+    for segment in SEGMENT_SPLIT.split(unquoted):
+        words = segment.split()
+        index = 0
+        while index < len(words) and re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", words[index]):
+            index += 1
+        if index < len(words) and (words[index] == "git" or words[index].endswith("/git")):
+            rest = words[index + 1 :]
+            directory = None
+            while rest and rest[0].startswith("-"):
+                if rest[0] == "-C" and len(rest) > 1:
+                    directory = rest[1]
+                skip = 2 if rest[0] in GLOBAL_OPTS_WITH_VALUE else 1
+                rest = rest[skip:]
+            if rest:
+                yield rest[0], rest[1:], directory
+
+
+STASH_READS = ("list", "show")
+
+
+def stash_subcommand_of(args):
+    """The stash subcommand `args` run; a bare `git stash` or one starting with an option is `push`."""
+    return args[0] if args and not args[0].startswith("-") else "push"
+
+
+def git_lines(cwd, *args):
+    result = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, timeout=10, check=True)
+    return {line for line in result.stdout.splitlines() if line}
+
+
+def concludes_merge(cwd):
+    """True while MERGE_HEAD exists and every staged path belongs to the merge. Any error is False."""
+    try:
+        merge_head = git_lines(cwd, "rev-parse", "--git-path", "MERGE_HEAD")
+        if not merge_head or not os.path.isfile(os.path.join(cwd, next(iter(merge_head)))):
+            return False
+        staged = git_lines(cwd, "diff", "--cached", "--name-only")
+        merge_paths = git_lines(cwd, "diff", "--name-only", "HEAD", "MERGE_HEAD") | git_lines(
+            cwd, "diff", "--name-only", "--diff-filter=U"
+        )
+        return staged <= merge_paths
+    except Exception:
+        return False
+
+
+def stages_everything(args):
+    return any(arg == "--all" or re.fullmatch(r"-[a-zA-Z]*a[a-zA-Z]*", arg) for arg in args if arg != "--")
+
+
+def violation_in(command, cwd=None):
+    """(rule, allowed form) for the first forbidden git call, or None."""
+    for sub, args, directory in git_calls_in(command):
+        if sub == "add":
+            if any(arg in ADD_ALL for arg in args):
+                return (
+                    "`git add -A`, `--all` and `.` stage other sessions' work",
+                    "stage named paths: `git add <path> ...`, or skip staging and use `git commit -m \"...\" -- <paths>`",
+                )
+        if sub == "stash" and stash_subcommand_of(args) not in STASH_READS:
+            return (
+                f"`git stash {stash_subcommand_of(args)}` hides or rewrites other sessions' uncommitted work",
+                "leave the working tree alone; commit your own paths with `git commit -m \"...\" -- <paths>`",
+            )
+        if sub == "commit":
+            if "--amend" in args:
+                return (
+                    "`git commit --amend` rewrites a commit another session may have built on",
+                    "make a new commit: `git commit -m \"...\" -- <paths>`",
+                )
+            if "--" not in args and not (
+                not stages_everything(args)
+                and concludes_merge(os.path.join(cwd or os.getcwd(), directory) if directory else cwd or os.getcwd())
+            ):
+                return (
+                    "`git commit` without a pathspec commits everything staged, including other sessions' work",
+                    "name the paths: `git commit -m \"...\" -- <paths>`",
+                )
+    return None
+
+
+def reason_for(rule, allowed):
+    return f"Denied: {rule}. Allowed form: {allowed}."
+
+
+def main():
+    if agent_name(sys.argv[1:]) != "claude":
+        return
+
+    data = json.load(sys.stdin)
+
+    if data.get("tool_name") != "Bash":
+        return
+
+    tool_input = data.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+
+    if not isinstance(command, str):
+        return
+
+    if disabled_locally(load_local_config(repo_root(data))):
+        return
+
+    cwd = data.get("cwd")
+    found = violation_in(command, cwd if isinstance(cwd, str) and cwd else None)
+
+    if not found:
+        return
+
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason_for(*found),
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/mods/plugins/e2e-progress/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "e2e-progress",
-  "version": "0.1.0-next.31",
+  "version": "0.1.0-next.33",
   "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane",
   "types": "./types/index.d.ts"
 }

package/content/rules/nx-layout.md

@@ -31,8 +31,11 @@ libs/
   reason, such as size or build time, and name that reason to the user.
   Never put features, queries, shared UI or theme in the app project.
 - Do not add Nx `feature/ui/data-access/util` folders or `type:*` tags.
-- Every lib has `src/index.ts` and explicit `build` (`@nx/angular:ng-packagr-lite`), `lint`
-  and `test` targets in `project.json`. Keep `plugins: []` in `nx.json`.
+- Every lib has `src/index.ts` and an explicit `build` target in `project.json`
+  (`@nx/angular:ng-packagr-lite`). `lint` and `test` are inferred by the plugins in `nx.json`
+  (`@nx/eslint/plugin`, and `@nx/vite/plugin` or `@nx/jest/plugin` for the test runner), so
+  do not write `@nx/eslint:lint` or `@nx/jest:jest` executor targets by hand. Nx 24 has no
+  such executors. Run `npx nx show project <name>` to see the inferred targets.
 - Alias = path with slashes: `@acme/domain/admin`, `@acme/queries`, `@acme/types`,
   `@acme/uikit`, `@acme/env`. Project name = path with dashes (`domain-admin`).
   Component `prefix` = the repo abbreviation.

package/content/rules/subagent-models.md

@@ -24,8 +24,8 @@ agent type carries the model and reasoning effort its own definition sets, and a
 inherits the parent's model.
 
 A subagent starts cold: it loads the full start context (about 50k tokens) before its first step,
-and measured subagents cost as much as the sessions that spawn them. Do a lookup of a few tool
-calls yourself. Give each subagent one large slice, not several small ones.
+and measured subagents cost as much as the sessions that spawn them. A lookup or job of under about 10 tool
+calls stays in the session. Give each subagent one large slice, not several small ones.
 
 A subagent has the same context budget as the session, measured on its own transcript, and the
 context-warning hook tells it to hand back at the critical tier. Size each prompt to fit: one

package/content/skills/agent-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-sessions
-description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt, and claim paths so two agents do not overwrite each other. Read before you edit a shared file while another agent may be active, and when the user says "mailbox", "coordinate with the other agent", "claim a file", "hand off to the other agent", or "restart the session".
+description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt (also your own, to clear yourself and resume after a handoff), and claim paths so two agents do not overwrite each other. Read before you edit a shared file while another agent may be active, and when the user says "mailbox", "coordinate with the other agent", "claim a file", "hand off to the other agent", or "restart the session".
 kind: skill
 scope: both
 ---
@@ -18,9 +18,9 @@ the `ethlete-agents` package is a dependency, `npx ethlete-agents sessions <comm
 script, so you do not need `<skill-dir>`. The older name `npx ethlete-agents mailbox` works too.
 
 ```bash
-node <skill-dir>/agent-sessions.mjs run <name> <command...>
+node <skill-dir>/agent-sessions.mjs run <name> <command...> [--role builder] [--dry-run]
 node <skill-dir>/agent-sessions.mjs up <name>[=<command>]...
-node <skill-dir>/agent-sessions.mjs restart <name> [--after <seconds>] <prompt...>
+node <skill-dir>/agent-sessions.mjs restart <name> [--after <seconds>] [--notify <agent,...>] [--process] [--role builder|none] <prompt...>
 node <skill-dir>/agent-sessions.mjs down [<name>...]
 node <skill-dir>/agent-sessions.mjs shell-install [<agent>...] [--file <path>] [--remove] [--dry-run]
 node <skill-dir>/agent-sessions.mjs shell-init [<agent>...]
@@ -45,11 +45,13 @@ Nothing runs until you start it, so a person who does not use this does nothing.
 
 ## Sessions
 
-`run <name> <command...>` starts the command in the `tmux` session `<name>@<repo>`, or attaches if it runs already. It also starts the dispatcher when none runs. Session names carry the repo name, so `codex` in two repos never collides. If that session has a terminal attached already, `run` starts `<name>-2`, then `<name>-3`, and so on. A detached session is attached again. So a second `claude` terminal gets its own agent.
+`run <name> <command...>` starts the command in the `tmux` session `<name>@<repo>`, or attaches if it runs already. It also starts the dispatcher when none runs. Session names carry the repo name, so `codex` in two repos never collides. If that session has a terminal attached already, `run` starts `<name>-2`, then `<name>-3`, and so on. A detached session is attached again. `--role builder` sets `ETHLETE_AGENT_ROLE=builder` and, for `claude`, appends a system prompt that keeps the chat silent and sends reports to the grill session. `--dry-run` prints the command instead of starting it. So a second `claude` terminal gets its own agent.
 
 `up codex=codex gemini=gemini` starts a detached `tmux` session per agent, named like its sender name, and runs the command in it. It also starts a session named `mailbox-dispatch` that runs `dispatch`. A running session is left alone. Attach to a session with `tmux attach -t <name>`. Detach with `Ctrl-b`, then `d`. The session and its agent keep running. Use `down` to stop the dispatcher and the named sessions.
 
-`restart <name> <prompt...>` types the clear command (`/clear`, or `/new` for a `codex` name) and then the prompt into the session `<name>@<repo>`, no sooner than `--after` seconds (default 5). It waits until that session ended its turn and its prompt holds no typed text, and gives up after 30 minutes. After the clear, a new turn does not hold the prompt back: a message can wake the fresh session, and Claude Code queues input typed during a turn. Only typed text in its prompt holds the prompt back. After 60 seconds of typed text, it saves the prompt to `.ethlete/restart.prompt.<session>.txt` and logs why in `.ethlete/restart.log`. The command returns at once, so end your turn after it. An agent uses it to clear itself and resume from its saved work state. It refuses any session other than the caller's own (from `$TMUX_PANE`), and the error names the caller's own sender name. Background commands of the old session still report into the new one.
+`restart <name> <prompt...>` types the clear command (`/clear`, or `/new` for a `codex` name) and then the prompt into the session `<name>@<repo>`, no sooner than `--after` seconds (default 5). It waits until that session ended its turn and its prompt holds no typed text, and gives up after 30 minutes. After the clear, a new turn does not hold the prompt back: a message can wake the fresh session, and Claude Code queues input typed during a turn. Only typed text in its prompt holds the prompt back. The prompt is the text between the two rules of the input box, so the background-agent panel below the footer does not count as typed text. When the focus sits in that panel, it presses Up until the prompt has the focus and clears the line with C-u before it types. After 2 minutes of typed text, and when it gives up, it sends one mailbox line to `<name>` and to each `--notify` agent. After 60 seconds of typed text, it saves the prompt to `.ethlete/restart.prompt.<session>.txt` and logs why in `.ethlete/restart.log`. The command returns at once, so end your turn after it. An agent uses it to clear itself and resume from its saved work state. It refuses any session other than the caller's own (from `$TMUX_PANE`) and the paired session (the builder session, started with `run --role builder`, and any session that is not one), and the error names the caller's own sender name. A restart of the paired session is logged to `restart.log` as `peer restart: <caller> restarted <target>`. Background commands of the old session still report into the new one. A pane counts as busy only when "esc to interrupt" or "Waiting for" shows in the spinner line right above the input box or in the footer below it (a turn that waits on background agents is busy). A chat line that starts with `●` or `⎿` never counts, so an agent that ends its turn with its own "Waiting for ..." text is idle. If the permission system denies your own `restart` (the command never runs), send one mailbox line to the grill/docs session, for example `send <you> --to <grill> 'restart denied, please /clear my pane and type: <prompt>'`. That session drives your pane: it types into it only when the pane is idle by the rule above.
+
+`restart --process` ends the agent process instead of clearing it: it types `/exit` (`/quit` for a `codex` name) and starts the agent command again in the same tmux pane, through a login shell, with the prompt as its first message. A `/clear` keeps the old process, so it never picks up a change to an installed plugin, a settings file, an MCP server or `PATH`; after such a change use `--process`. The agent command is the one `run` started, without its prompt, and the pane's start command for an older session. It starts with `command`, so the shell function of the same name does not start a new session. If the exit opens the background work dialog, the restart selects "exit and stop tasks" and writes the stopped jobs to `restart.log` and to a mailbox notice. The new process keeps the role: the session's own role, else `builder` from a prompt that resumes a `builder-*` handoff, else the one `--role` names. A builder process gets `ETHLETE_AGENT_ROLE=builder` and, for `claude`, the builder system prompt once. A session with no role next to another agent session in the repo, none of them a builder, is refused unless the prompt resumes a `builder-*` or `doc-agent-*` handoff or `--role` is passed (`--role none` restarts it without a role).
 
 `shell-install` writes one shell function per agent into `~/.zshrc` or `~/.bashrc`, between two marker lines. A second run replaces the block, and `--remove` deletes it. Use `--file` for another startup file and `--dry-run` to preview. After a new terminal opens, typing `claude` or `codex` in a repo with this skill runs the agent through `run`. Elsewhere the function starts the plain command. Run `shell-install` only when the user asks: it changes a file the user owns. `shell-init` prints the same functions without writing a file.
 
@@ -78,4 +80,6 @@ If the prompt of the agent holds typed text, the dispatcher waits until that tex
 4. After each larger step, run `inbox` again. Most agents cannot wake on new output, so you must pull messages yourself.
 5. When you finish, run `release`. A claim also expires after 4 hours, or after `--ttl` hours.
 
+In this repo commit with `yarn commit -m "..." -- <paths>`: it adds untracked paths and waits for `.git/index.lock`. Specs, lint and typecheck run in CI, not in the hook.
+
 A claim is advisory, not a lock. `--force` claims over another agent: use it only after the holder agreed. Silence is not approval. Acknowledge each handoff in words. No agent starts automatically. The user starts each one.