@ethlete/agent-rules 0.1.0-next.30 → 0.1.0-next.32

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @ethlete/agent-rules
 
+## 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
+
+- The design-exploration skill now describes the `ethlete-design` MCP server: its tools by job, when to use them instead of the `et design` CLI, and the `sketch_report` and `sketch_ready` rules.
+
+### Patch Changes
+
+- The Codex subagent skill lists gpt-6-luna, gpt-6.1-terra (the new default), gpt-6.1-sol and gpt-6-astra. The context hook gives gpt-6.1 a 500k pricing boundary.
+- `agent-sessions restart` types the prompt after the clear even when a message woke the fresh session. Only typed text in its prompt holds the prompt back.
+- The design exploration skill lists `et design sketch target add`.
+- `agent-sessions restart` no longer reads the Claude Code IDE context chip (`[⧉ In file]`) on the prompt line as a draft, so it types the resume prompt after the clear.
+- `control(markup, name)` from `@ethlete/components/design/control` renames a control that is already marked, so a design reuses a control part under its own control name.
+- CONTROL-STATE counts an interaction word only as the last word of a state name, drops modifier words from the element name, and asks a component without controls to declare them (Q164).
+- `et design check`, `sketch check`, `sketch ready` and `design complete` fail interaction states on a part that declares no control (`CONTROL-STATE`). `design complete` hints a state that changes under 10 % of its frame.
+- Design checks report a drawn button, link, input or control role without `data-et-control` as `CONTROL-PART-INPUT`: a hint on merged parts, an error when a sketch adds one.
+
 ## 0.1.0-next.30
 
 ### 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,140 @@
+#!/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. Quoted text is ignored, so a commit message 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"(?:^|[\s;&|])design\s+check(?=\s|$|[;&|])")),
+    ("design compare", re.compile(r"(?:^|[\s;&|])design\s+compare(?=\s|$|[;&|])")),
+    ("design ready", re.compile(r"(?:^|[\s;&|])design\s+ready(?=\s|$|[;&|])")),
+    ("design sketch ready", re.compile(r"(?:^|[\s;&|])design\s+sketch\s+ready(?=\s|$|[;&|])")),
+    ("design harness", re.compile(r"(?:^|[\s;&|])design\s+harness(?=\s|$|[;&|])")),
+    ("studio:e2e", re.compile(r"studio:e2e(?=\s|$|[;&|:])")),
+    ("--visible-change", re.compile(r"(?:^|\s)--visible-change(?=\s|=|$)")),
+)
+
+QUOTED = re.compile(r"\"(?:\\.|[^\"\\])*\"|'[^']*'")
+
+
+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, or None."""
+    unquoted = QUOTED.sub(" ", command)
+    for name, pattern in LONG_COMMANDS:
+        if pattern.search(unquoted):
+            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,74 @@
+#!/usr/bin/env python3
+"""Stop hook: logs how many chat words a builder session wrote in the turn that just ended.
+
+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. It never blocks,
+never prints and always exits 0.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+LOG_FILE = os.path.join(".claude", "builder-chat-words.jsonl")
+
+
+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 count_words(path):
+    words = 0
+    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):
+                words = 0
+            elif entry.get("type") == "assistant":
+                content = (entry.get("message") or {}).get("content")
+                if isinstance(content, str):
+                    words += len(content.split())
+                elif isinstance(content, list):
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            words += len(str(block.get("text", "")).split())
+    return words
+
+
+def main():
+    if os.environ.get("ETHLETE_AGENT_ROLE") != "builder":
+        return
+    payload = json.load(sys.stdin)
+    path = payload.get("transcript_path")
+    if not path or not os.path.isfile(path):
+        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)
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "session_id": payload.get("session_id"),
+        "words": count_words(path),
+    }
+    with open(log, "a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record) + "\n")
+
+
+try:
+    main()
+except Exception:
+    pass
+sys.exit(0)

package/content/hooks/context-warning.py

@@ -137,6 +137,7 @@ PREMIUM_BOUNDARY = 200_000
 # Codex models whose long-context pricing starts above 272k input tokens. Models
 # without that pricing rule use their reported context window instead.
 CODEX_PREMIUM_BOUNDARIES = (
+    ("gpt-6.1", 500_000),
     ("gpt-5.6", 272_000),
     ("gpt-5.5", 272_000),
     ("gpt-5.4-mini", None),
@@ -257,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()
     }
 
@@ -850,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:

package/content/hooks/git-safety.py

@@ -0,0 +1,181 @@
+#!/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
+- any `git add` or `git commit` whose paths name an `.ethlete/**/go.json` (a go is granted
+  in Studio, never committed by an agent)
+
+`git commit-tree` and `git update-index` stay allowed, so a merge commit built on a temporary
+GIT_INDEX_FILE works. Commit messages (`-m`, `--message`) and other quoted text are ignored for
+the command checks, so a 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 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]+")
+GLOBAL_OPTS_WITH_VALUE = ("-C", "-c", "--git-dir", "--work-tree", "--namespace")
+ADD_ALL = ("-A", "--all", ".")
+GO_JSON = re.compile(r"(?:^|/)go\.json$")
+
+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(" ", command)
+    unquoted = stripped.replace('"', " ").replace("'", " ")
+    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 :]
+            while rest and rest[0].startswith("-"):
+                skip = 2 if rest[0] in GLOBAL_OPTS_WITH_VALUE else 1
+                rest = rest[skip:]
+            if rest:
+                yield rest[0], rest[1:]
+
+
+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 violation_in(command):
+    """(rule, allowed form) for the first forbidden git call, or None."""
+    for sub, args 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:
+                return (
+                    "`git commit` without a pathspec commits everything staged, including other sessions' work",
+                    "name the paths: `git commit -m \"...\" -- <paths>`",
+                )
+        if sub in ("add", "commit") and any(GO_JSON.search(arg) for arg in args):
+            return (
+                "an agent never stages or commits a `go.json`; a go is granted in Studio",
+                "leave `go.json` out of the 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
+
+    found = violation_in(command)
+
+    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.30",
+  "version": "0.1.0-next.32",
   "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,7 +18,7 @@ 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 down [<name>...]
@@ -45,11 +45,11 @@ 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. 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. 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.
 
 `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 +78,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 runs the related specs first in a throwaway worktree of HEAD plus those paths, before it takes `.git/index.lock`, and the pre-commit hook then skips them for that exact tree (a plain `git commit` still runs them 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.