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

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.33
+
+### Minor Changes
+
+- `agent-sessions restart --process` starts the agent as a new process in its tmux pane, so a plugin, settings or `PATH` change takes effect.
+
+### Patch Changes
+
+- The builder Stop hook now blocks a turn that ends with more than one line of chat text. `restart --process` keeps the session's role. Resuming a role handoff loads its role skill.
+- The builder Stop hook now counts the final message of the turn from `last_assistant_message`. Claude Code calls the hook before that message reaches the transcript.
+- `agent-sessions restart` treats a pane that shows "Waiting for" background agents as busy, and the skill says to mail the grill session when a self-restart is denied.
+- `agent-sessions restart` accepts the paired builder or grill/docs session as target and logs each peer restart to `restart.log`.
+- `agent-sessions restart` no longer hangs when the background-agent panel is open, and it tells the caller and `--notify` agents when it waits or gives up.
+- `agent-sessions restart --process` keeps the tmux session of the agent, does not send the first prompt of `run` again, and answers the background work dialog of Claude Code with "exit and stop tasks".
+- `agent-sessions restart --process` no longer passes a stored prompt twice, and `run` switches only the client of the calling tmux session.
+- The design exploration skill documents `et design sketch covers` (ADR 0222).
+- `et design sketch covers` on a multi-target sketch takes the part, `<layer>/<name>:<state>[@x,y,w,h]`, and refuses a bare state; compare matches a covered DIFF against that part.
+- The `background-design-commands` hook matches long design commands only at command position, so a heredoc, an unquoted `echo` or a `git commit` message that names `design check` no longer gets denied.
+- The builder Stop hook now parses each Bash command into its simple commands. A heredoc body or a quoted string that names `agent-sessions.mjs send` or `git commit` no longer counts as a report or a commit.
+- The builder Stop hook also blocks a stop one time when the turn ran `git commit` or `git push` and sent no report with `SendMessage` or `agent-sessions send`.
+- The design-exploration skill now describes build-ready, a current check record from `design check`, instead of the removed `design go` and `design accept` commands.
+- The git-safety hook now allows a pathless `git commit` that concludes a merge, no longer denies commands that only mention `git commit` in a grep pattern or heredoc, and drops the obsolete `go.json` rule.
+- Fix `agent-sessions restart` never restarting an idle session whose own chat text said "Waiting for": only the spinner line and the footer count as busy.
+
+## 0.1.0-next.32
+
+### Minor Changes
+
+- Add the `background-design-commands` hook: it denies a Bash call that runs a long design command (`design check`, `compare`, `ready`, `sketch ready`, `harness`, `studio:e2e`, `--visible-change`) without `run_in_background`.
+- Add the `git-safety` hook: it denies `git add -A`, `git stash`, `git commit --amend`, a `git commit` without a pathspec and any `go.json` in a commit.
+
+### Patch Changes
+
+- Add `--role builder` to the agent-sessions `run` command and a `builder-chat-words` Stop hook that logs the chat words of each builder turn.
+- `ethlete-agents sync` and `et` write their JSON files (`.mcp.json`, design and update state) in the checkout's Prettier format.
+- The git-commit skill asks for one commit per finished slice (code, specs, changeset and plan note together), one per sketch round or merge, and no history rewrites in a shared checkout.
+- The design-exploration skill tells parts to use `data-et-auto-surface` and `data-et-surface-interactive` instead of a picked `et-surface--<name>` class.
+- The design-exploration skill keeps its hard rules in SKILL.md and moves the command details into reference files, and the subagent rule says a job of under about 10 tool calls stays in the session.
+- The design-exploration skill tells parts to use `data-et-semantic-color="<type>"` instead of a picked `et-color--<name>` class.
+- The design-exploration skill tells an agent to take every colour from the SDK surface and colour theming, never from its own tokens.
+- The `handoff` skill spawns no sub-agent from 70 %, and a self-restart no longer waits for sub-agents that report into a result file.
+- Fix the nx-layout rule to describe inferred lint and test targets instead of the removed `@nx/eslint:lint` and `@nx/jest:jest` executors.
+- The context-warning hook tells an agent in a tmux pane with the agent-sessions skill to save the handoff and run `restart` on its own session, instead of asking the user to clear. The skill description names self-restart.
+- Let `git stash list` and `git stash show` through the git-safety hook. Every writing stash subcommand stays refused, and the refusal names it.
+- `sync` keeps the existing order of hook events and entries in `.claude/settings.json` and only updates, appends or removes its own entries, so a second run is a no-op.
+- The design skill now says visible UI is built only from a picked sketch, and the grilling skill says to decide technical questions yourself.
+- The agent-sessions skill notes that `yarn commit` runs the related specs before it takes the index lock.
+- `et design check` fails a frame-loaded design module that awaits at the top level (`TOP-LEVEL-AWAIT`), which can hang WebKit; a call variant may default-export a promise of its drawing instead.
+- `et design sketch report` refuses a ready sketch. Add `--reopen` to move it back to in progress when the user asks for a change.
+
 ## 0.1.0-next.31
 
 ### Minor Changes

package/README.md

@@ -312,7 +312,13 @@ per hook in the config:
 
 ```json
 {
-  "hooks": ["context-warning", "subagent-model-policy"]
+  "hooks": [
+    "context-warning",
+    "subagent-model-policy",
+    "background-design-commands",
+    "git-safety",
+    "builder-chat-words"
+  ]
 }
 ```
 

package/content/hooks/background-design-commands.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: long design commands must run in the background.
+
+`design check`, `design compare`, `design ready`, `design sketch ready`, `design harness`,
+the `studio:e2e` target and the `--visible-change` gate each take minutes. In the foreground
+they block the whole session, so a Bash call that runs one without `run_in_background: true`
+is denied and the agent repeats it in the background.
+
+Matches the `yarn design ...`, `node dist/libs/cli/src/index.js design ...` and
+`npx nx ... studio:e2e` forms at command position only. Quoted text, heredoc bodies and
+arguments of other commands (`echo`, `git commit`, `grep`) are ignored, so free text that
+mentions a command 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": ["background-design-commands"]}.
+
+Fail-safe: any error exits 0 with no output.
+"""
+
+import json
+import os
+import re
+import sys
+
+HOOK_NAME = "background-design-commands"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+LONG_COMMANDS = (
+    ("design check", re.compile(r"\bdesign\s+check(?=\s|$)")),
+    ("design compare", re.compile(r"\bdesign\s+compare(?=\s|$)")),
+    ("design ready", re.compile(r"\bdesign\s+ready(?=\s|$)")),
+    ("design sketch ready", re.compile(r"\bdesign\s+sketch\s+ready(?=\s|$)")),
+    ("design harness", re.compile(r"\bdesign\s+harness(?=\s|$)")),
+    ("studio:e2e", re.compile(r"studio:e2e(?=\s|$|:)")),
+    ("--visible-change", re.compile(r"(?:^|\s)--visible-change(?=\s|=|$)")),
+)
+
+LAUNCHERS = frozenset(
+    ("yarn", "npx", "pnpm", "pnpx", "npm", "node", "nx", "bun", "bunx", "et", "ethlete-agents", "bash", "sh", "zsh", "time", "env", "nohup", "timeout", "sudo", "exec", "xargs")
+)
+
+QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
+HEREDOC = re.compile(r"<<-?\s*(?:\"(\w+)\"|'(\w+)'|\\?(\w+))")
+SEPARATORS = re.compile(r"&&|\|\||[;&|\n(){}`]")
+ASSIGNMENT = re.compile(r"^[A-Za-z_]\w*=")
+
+
+def without_heredoc_bodies(command):
+    lines = command.split("\n")
+    kept = []
+    delimiter = None
+    for line in lines:
+        if delimiter is not None:
+            if line.strip() == delimiter:
+                delimiter = None
+            continue
+        kept.append(line)
+        match = HEREDOC.search(line)
+        if match:
+            delimiter = match.group(1) or match.group(2) or match.group(3)
+    return "\n".join(kept)
+
+
+def command_segments(command):
+    """The shell string split into simple commands, with heredoc bodies and quoted text removed."""
+    text = QUOTED.sub(" ", without_heredoc_bodies(command))
+    text = text.replace("$(", ";")
+    return [segment.strip() for segment in SEPARATORS.split(text) if segment.strip()]
+
+
+def at_command_position(segment):
+    words = [word for word in segment.split() if not ASSIGNMENT.match(word)]
+    return bool(words) and os.path.basename(words[0]) in LAUNCHERS
+
+
+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 long_command_in(command):
+    """The name of the first long command the shell string runs at a command position, or None."""
+    for segment in command_segments(command):
+        if not at_command_position(segment):
+            continue
+        for name, pattern in LONG_COMMANDS:
+            if pattern.search(segment):
+                return name
+    return None
+
+
+def reason_for(name):
+    return (
+        f"`{name}` takes minutes and blocks the session when it runs in the foreground. "
+        "Call Bash again with the same command and `run_in_background: true`, then read its output "
+        "when the completion notice arrives."
+    )
+
+
+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")
+
+    if not isinstance(tool_input, dict) or tool_input.get("run_in_background") is True:
+        return
+
+    command = tool_input.get("command")
+
+    if not isinstance(command, str):
+        return
+
+    if disabled_locally(load_local_config(repo_root(data))):
+        return
+
+    name = long_command_in(command)
+
+    if not name:
+        return
+
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason_for(name),
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/hooks/builder-chat-words.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Stop hook: logs the chat text of a builder turn and blocks a turn that ends with more than one line.
+
+Only runs in a session started with `--role builder` (ETHLETE_AGENT_ROLE=builder). Appends one
+JSON line to .claude/builder-chat-words.jsonl: timestamp, session_id, words, lines, committed, reported, blocked.
+It blocks the stop once (not again while stop_hook_active is set) when the turn's text blocks and
+last_assistant_message hold more than one non-empty line, or when the turn ran `git commit` or `git push` and sent
+no report (no SendMessage, no `agent-sessions send`). It always exits 0.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+LOG_FILE = os.path.join(".claude", "builder-chat-words.jsonl")
+BLOCK_REASON = (
+    "builder: no chat text. Send the report with SendMessage to the grill session; "
+    "end the turn with at most one line."
+)
+REPORT_REASON = (
+    "builder: this turn committed or pushed and sent no report. Send it to the grill session with SendMessage "
+    "or `agent-sessions.mjs send`, then end the turn."
+)
+SEPARATORS = ";&|()\n"
+GIT_OPTIONS_WITH_VALUE = {"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path"}
+
+
+def is_prompt(entry):
+    if entry.get("type") != "user":
+        return False
+    content = (entry.get("message") or {}).get("content")
+    if isinstance(content, str):
+        return True
+    return isinstance(content, list) and not any(
+        isinstance(block, dict) and block.get("type") == "tool_result" for block in content
+    )
+
+
+def turn_entries(path):
+    texts = []
+    tools = []
+    with open(path, encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                entry = json.loads(line)
+            except ValueError:
+                continue
+            if not isinstance(entry, dict):
+                continue
+            if is_prompt(entry):
+                texts = []
+                tools = []
+            elif entry.get("type") == "assistant":
+                content = (entry.get("message") or {}).get("content")
+                if isinstance(content, str):
+                    texts.append(content)
+                elif isinstance(content, list):
+                    for block in content:
+                        if not isinstance(block, dict):
+                            continue
+                        if block.get("type") == "text":
+                            texts.append(str(block.get("text", "")))
+                        elif block.get("type") == "tool_use":
+                            tools.append(block)
+    return texts, tools
+
+
+def bash_commands(tools):
+    for tool in tools:
+        if tool.get("name") == "Bash":
+            command = (tool.get("input") or {}).get("command")
+            if isinstance(command, str):
+                yield command
+
+
+def read_heredoc_delimiter(command, index):
+    strip_tabs = command.startswith("-", index)
+    if strip_tabs:
+        index += 1
+    while index < len(command) and command[index] in " \t":
+        index += 1
+    delimiter = []
+    while index < len(command) and command[index] not in " \t" + SEPARATORS + "<>":
+        char = command[index]
+        if char in "'\"":
+            end = command.find(char, index + 1)
+            end = len(command) if end == -1 else end
+            delimiter.append(command[index + 1 : end])
+            index = end + 1
+        else:
+            if char != "\\":
+                delimiter.append(char)
+            index += 1
+    return "".join(delimiter), strip_tabs, index
+
+
+def skip_heredoc_bodies(command, index, heredocs):
+    for delimiter, strip_tabs in heredocs:
+        while index < len(command):
+            end = command.find("\n", index)
+            end = len(command) if end == -1 else end
+            row = command[index:end]
+            index = end + 1
+            if (row.lstrip("\t") if strip_tabs else row) == delimiter:
+                break
+    return index
+
+
+def simple_commands(command):
+    commands = [[]]
+    word = None
+    heredocs = []
+    index = 0
+
+    def end_word():
+        nonlocal word
+        if word is not None:
+            commands[-1].append(word)
+            word = None
+
+    def end_command():
+        end_word()
+        if commands[-1]:
+            commands.append([])
+
+    while index < len(command):
+        char = command[index]
+        if char == "\\":
+            if command.startswith("\n", index + 1):
+                index += 2
+                continue
+            word = (word or "") + command[index + 1 : index + 2]
+            index += 2
+        elif char == "'":
+            end = command.find("'", index + 1)
+            end = len(command) if end == -1 else end
+            word = (word or "") + command[index + 1 : end]
+            index = end + 1
+        elif char == '"':
+            index += 1
+            chars = []
+            while index < len(command) and command[index] != '"':
+                if command[index] == "\\" and index + 1 < len(command):
+                    index += 1
+                chars.append(command[index])
+                index += 1
+            word = (word or "") + "".join(chars)
+            index += 1
+        elif char == "#" and word is None:
+            end = command.find("\n", index)
+            index = len(command) if end == -1 else end
+        elif command.startswith("<<<", index):
+            end_word()
+            index += 3
+        elif command.startswith("<<", index):
+            end_word()
+            delimiter, strip_tabs, index = read_heredoc_delimiter(command, index + 2)
+            heredocs.append((delimiter, strip_tabs))
+        elif char == "\n":
+            end_command()
+            index = skip_heredoc_bodies(command, index + 1, heredocs)
+            heredocs = []
+        elif char in SEPARATORS:
+            end_command()
+            index += 1
+        elif char in " \t":
+            end_word()
+            index += 1
+        else:
+            word = (word or "") + char
+            index += 1
+    end_command()
+    return [words for words in commands if words]
+
+
+def command_words(words):
+    index = 0
+    while index < len(words) and "=" in words[index] and not words[index].startswith("-"):
+        index += 1
+    return words[index:]
+
+
+def is_git_commit(words):
+    words = command_words(words)
+    if not words or os.path.basename(words[0]) != "git":
+        return False
+    index = 1
+    while index < len(words) and words[index].startswith("-"):
+        index += 2 if words[index] in GIT_OPTIONS_WITH_VALUE else 1
+    return index < len(words) and words[index] in ("commit", "push")
+
+
+def is_report_send(words):
+    words = command_words(words)
+    if len(words) < 3:
+        return False
+    if words[0] == "yarn":
+        return words[1:3] == ["agents:sessions", "send"]
+    if os.path.basename(words[0]) != "node":
+        return False
+    scripts = [word for word in words[1:] if not word.startswith("-")]
+    return len(scripts) >= 2 and os.path.basename(scripts[0]) == "agent-sessions.mjs" and scripts[1] == "send"
+
+
+def bash_simple_commands(tools):
+    for command in bash_commands(tools):
+        yield from simple_commands(command)
+
+
+def has_commit(tools):
+    return any(is_git_commit(words) for words in bash_simple_commands(tools))
+
+
+def has_report(tools):
+    return any(tool.get("name") == "SendMessage" for tool in tools) or any(
+        is_report_send(words) for words in bash_simple_commands(tools)
+    )
+
+
+def with_final(texts, final):
+    if not isinstance(final, str) or not final.strip():
+        return texts
+    if texts and texts[-1].strip() == final.strip():
+        return texts
+    return [*texts, final]
+
+
+def main():
+    if os.environ.get("ETHLETE_AGENT_ROLE") != "builder":
+        return
+    payload = json.load(sys.stdin)
+    path = payload.get("transcript_path")
+    final = payload.get("last_assistant_message")
+    has_transcript = bool(path) and os.path.isfile(path)
+    if not has_transcript and not isinstance(final, str):
+        return
+    root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
+    log = os.path.join(root, LOG_FILE)
+    os.makedirs(os.path.dirname(log), exist_ok=True)
+    # Claude Code calls the Stop hook before the final text block reaches the transcript.
+    texts, tools = turn_entries(path) if has_transcript else ([], [])
+    texts = with_final(texts, final)
+    lines = sum(1 for text in texts for row in text.splitlines() if row.strip())
+    committed = has_commit(tools)
+    reported = has_report(tools)
+    unreported = committed and not reported
+    blocked = (lines > 1 or unreported) and not payload.get("stop_hook_active")
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "session_id": payload.get("session_id"),
+        "words": sum(len(text.split()) for text in texts),
+        "lines": lines,
+        "committed": committed,
+        "reported": reported,
+        "blocked": blocked,
+    }
+    with open(log, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record) + "\n")
+    if blocked:
+        reason = REPORT_REASON if unreported else BLOCK_REASON
+        print(json.dumps({"decision": "block", "reason": reason}))
+
+
+try:
+    main()
+except Exception:
+    pass
+sys.exit(0)

package/content/hooks/context-warning.py

@@ -258,37 +258,65 @@ def handoff_skill(root):
 
 
 SELF_RESTART = (
-    "you run in an agent-sessions tmux session, so do not hand this step to the user: apply the {handoff} skill's save "
-    "test, save if it calls for a file, then follow its 'Clear and resume on your own' section "
-    "and restart this session yourself with the agent-sessions `restart` command - with no file, "
+    "you run in an agent-sessions tmux session, so do not hand this step to the user and never ask them to clear: "
+    "apply the {handoff} skill's save test and save the handoff if it calls for a file, then run "
+    '`node {script} restart {name} "/{handoff} resume"` yourself and end the turn - with no file, '
     "restart with a prompt that names the next step"
 )
+SELF_RESTART_ACT_NOW = (
+    "Save the handoff, then run `node {script} restart {name} \"/{handoff} resume\"` yourself and end the turn. "
+    "Never ask the user to clear."
+)
 USER_DIRECTED_KEYS = ("recommend", "suggest", "save_now", "save_at_stop")
 
 
-def can_self_restart(root):
-    """True only in a tmux session the agent-sessions `restart` command can find and drive."""
-    if not os.environ.get("TMUX") or not root:
-        return False
-    if not any(
-        os.path.isfile(os.path.join(root, ".agents/skills", name, "agent-sessions.mjs"))
-        for name in ("ethlete-agent-sessions", "agent-sessions")
-    ):
-        return False
+def self_restart_target(root):
+    """The agent-sessions script path and own session name, or None outside a tmux session `restart` can drive."""
+    pane = os.environ.get("TMUX_PANE")
+    if not pane or not root:
+        return None
+    script = next(
+        (
+            path
+            for path in (
+                os.path.join(".agents/skills", name, "agent-sessions.mjs")
+                for name in ("ethlete-agent-sessions", "agent-sessions")
+            )
+            if os.path.isfile(os.path.join(root, path))
+        ),
+        None,
+    )
+    if not script:
+        return None
     try:
         session = subprocess.run(
-            ["tmux", "display-message", "-p", "#S"], capture_output=True, text=True, timeout=2
+            ["tmux", "display-message", "-p", "-t", pane, "#{session_name}"],
+            capture_output=True,
+            text=True,
+            timeout=2,
         ).stdout.strip()
     except (OSError, subprocess.SubprocessError):
-        return False
-    return session.endswith("@" + re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root))))
+        return None
+    if not session:
+        return None
+    slug = re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root)))
+    return {"script": script, "name": session.removesuffix("@" + slug)}
 
 
-def resolve_profile(profile, skill, self_restart=False):
+def resolve_profile(profile, skill, self_restart=None):
     """Fills the installed handoff skill's name into a profile's message fragments."""
-    resolved = {**profile, **{key: SELF_RESTART for key in USER_DIRECTED_KEYS}} if self_restart else profile
+    resolved = profile
+    if self_restart:
+        resolved = {
+            **profile,
+            **{key: SELF_RESTART for key in USER_DIRECTED_KEYS},
+            "act_now": SELF_RESTART_ACT_NOW,
+        }
+    values = {"handoff": skill, **(self_restart or {})}
     return {
-        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        key: re.sub(r"\{(handoff|script|name)\}", lambda m: values.get(m.group(1), m.group(0)), value)
+        if isinstance(value, str)
+        else value
         for key, value in resolved.items()
     }
 
@@ -851,7 +879,7 @@ def main():
     if disabled_locally(local_config):
         return
 
-    profile = resolve_profile(profile, handoff_skill(root), self_restart=can_self_restart(root))
+    profile = resolve_profile(profile, handoff_skill(root), self_restart=self_restart_target(root))
 
     claude_subagent = agent == "claude" and bool(data.get("agent_id"))
     if claude_subagent: