@ethlete/agent-rules 0.1.0-next.13 → 0.1.0-next.15

package/content/hooks/subagent-model-policy.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: make a subagent's model an explicit choice.
+
+A `Task` call that passes no `model` runs the subagent on the parent session's
+model. A session led by an expensive model therefore spends that model on every
+grep and every file read it delegates, which burns a usage limit in minutes for
+work a small model does just as well.
+
+So this hook gates the tool call rather than only advising:
+
+  * No `model` at all - denied, with the model table returned to the agent. The
+    agent then repeats the call with a model, so the cost of the mistake is one
+    tool call, not a whole subagent run.
+  * `model: fable` - the user is asked. Fable is the right pick for planning,
+    design, cross-cutting review and leading other subagents, and the wrong pick
+    for the twentieth mechanical lookup; only the user knows which this is.
+  * Any other model - allowed silently.
+
+Two cases are left alone, because the tool's `model` would change nothing:
+
+  * `subagent_type: fork`, which always inherits the parent model.
+  * An agent type whose own definition under `.claude/agents/` sets a model.
+
+Can be disabled per machine via a gitignored ethlete-agents.config.local.json at
+the repo root: {"disableHooks": true} or {"disableHooks": ["subagent-model-policy"]}.
+
+Fail-safe: any error exits 0 with no output - the hook must never block work
+because it could not read its own input.
+"""
+
+import json
+import os
+import sys
+
+HOOK_NAME = "subagent-model-policy"
+LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
+
+# The tool that spawns a subagent, under both names it has carried.
+SUBAGENT_TOOLS = ("Task", "Agent")
+
+POLICY = """A subagent's model is a choice, not an inheritance. This call passes no `model`, so the subagent \
+would run on the model leading this session - which is how one expensive model ends up doing every small job. \
+Call the tool again with `model` set:
+
+- `haiku` - mechanical lookups: grep, find, read a file, run a command and report what it said.
+- `opus` - the default for real work: code changes, tests, debugging, reviewing a diff.
+- `sonnet` - a middle ground where opus is more than the task needs.
+- `fable` - judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most \
+expensive of the four, so choosing it asks the user first.
+
+Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done" is, and say \
+"keep it brief" for a lookup. An agent type defined under `.claude/agents/` carries its own model and reasoning \
+effort, so a call that names one needs no `model` of its own."""
+
+FABLE_REASON = """This subagent would run on fable, the most expensive model. Approve it where the task is \
+judgment-heavy - planning, design, cross-cutting review, or leading other subagents. Deny it for implementation \
+(`model: "opus"`) or for a mechanical lookup (`model: "haiku"`), then repeat the call with that model."""
+
+
+def agent_name(argv):
+    """The --agent value, defaulting to claude — older registrations pass no flag."""
+    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):
+    """Repo root: the env var the agent sets, else the script's own location, else the cwd.
+
+    The script always lives at <root>/.<agent>/hooks/ethlete/subagent-model-policy.py, so
+    walking four levels up works for any agent that has no project-dir variable of its own.
+    """
+    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):
+    """Parsed ethlete-agents.config.local.json at the repo root, or {} if missing/unreadable."""
+    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):
+    """True when the local config disables this hook (or all hooks) on this machine."""
+    disabled = config.get("disableHooks")
+    return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
+
+
+def definition_sets_model(root, subagent_type):
+    """True when a project or user agent definition of that name declares its own model."""
+    if not subagent_type:
+        return False
+    file_name = f"{subagent_type.split(':')[-1]}.md"
+    candidates = [
+        os.path.join(root or ".", ".claude", "agents", file_name),
+        os.path.join(os.path.expanduser("~"), ".claude", "agents", file_name),
+    ]
+    for path in candidates:
+        try:
+            with open(path, encoding="utf-8") as f:
+                head = f.read(4096)
+        except OSError:
+            continue
+        for line in head.split("\n"):
+            key, separator, value = line.partition(":")
+            if separator and key.strip() == "model" and value.strip():
+                return True
+    return False
+
+
+def decision_for(tool_input, root):
+    """The (decision, reason) this call needs, or None when it may run untouched."""
+    subagent_type = str(tool_input.get("subagent_type") or "").strip().lower()
+    model = str(tool_input.get("model") or "").strip().lower()
+
+    if "fable" in model:
+        return "ask", FABLE_REASON
+    if model:
+        return None
+    if subagent_type == "fork" or definition_sets_model(root, subagent_type):
+        return None
+    return "deny", POLICY
+
+
+def main():
+    if agent_name(sys.argv[1:]) != "claude":
+        return
+
+    data = json.load(sys.stdin)
+
+    if data.get("tool_name") not in SUBAGENT_TOOLS:
+        return
+
+    tool_input = data.get("tool_input")
+
+    if not isinstance(tool_input, dict):
+        return
+
+    root = repo_root(data)
+
+    if disabled_locally(load_local_config(root)):
+        return
+
+    outcome = decision_for(tool_input, root)
+
+    if not outcome:
+        return
+
+    decision, reason = outcome
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": decision,
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/content/rules/subagent-models.md

@@ -0,0 +1,29 @@
+---
+name: subagent-models
+description: A subagent's model is an explicit choice on every call - haiku for lookups, opus for work, fable for judgment.
+kind: rule
+scope: both
+---
+
+## Delegating: name the subagent's model
+
+A subagent spawned without a `model` runs on the model leading the session, so an expensive
+model ends up doing every small job it delegates. **Set `model` on every call**, matched to the
+task:
+
+| Model    | The work it fits                                                                                                                                         |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `haiku`  | Mechanical lookups: grep, find, read a file, run a command and report what it said.                                                                      |
+| `sonnet` | A middle ground where opus is more than the task needs.                                                                                                  |
+| `opus`   | The default for real work: code changes, tests, debugging, reviewing a diff.                                                                             |
+| `fable`  | Judgment-heavy work: planning, design, cross-cutting review, leading other subagents. The most expensive of the four, so ask the user before picking it. |
+
+Effort follows the prompt, not a parameter: scope the prompt to one question, name what "done"
+means, and say "keep it brief" for a lookup. Two calls need no `model` of their own - a named
+agent type carries the model and reasoning effort its own definition sets, and a fork always
+inherits the parent's model.
+
+A subagent does not have to be a Claude one. Delegate to a Codex agent where another model
+family would answer better - a second opinion, a review of your own diff, a bug hunt your own
+reading failed - and whenever the Claude usage limit is close, because a Codex run does not draw
+on it. Read {%skill:codex-subagent%} first.

package/content/skills/codex-subagent/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: codex-subagent
+description: Delegate a task to a Codex agent (gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-6-astra) instead of a Claude subagent - a second opinion from another model family, a review, or a cheap parallel lookup. Read before spawning a subagent when another model would answer better, and whenever the user says codex, GPT, or "second opinion".
+kind: skill
+scope: both
+---
+
+# Codex as a subagent
+
+`codex exec` runs one Codex agent to completion without a terminal. It is a subagent with its
+own context, its own tools and its own model family. It reads the repository's `AGENTS.md` by
+itself, so it starts with the same rules you have.
+
+Use it when the task gains from a model that is not Claude: a second opinion on a design, a
+review of your own diff, a bug hunt that your reading already failed, or work you want to run
+beside your own. Use it also when the Claude usage limit is close, because a Codex run does not
+draw on it - move the delegatable work there and keep the limit for the work you lead. For
+everything else, a Claude subagent stays the cheaper choice.
+
+## The call
+
+The wrapper is {%resource:codex-agent.mjs%}. It keeps the Codex trace in a log file and prints
+only the final message, so one run costs you a few hundred tokens instead of the whole trace.
+Below, `<skill-dir>` is the directory this file sits in.
+
+```bash
+node <skill-dir>/codex-agent.mjs -m gpt-5.6-terra -e medium "<prompt>"
+```
+
+Options: `-m` model, `-e` effort (`low`, `medium`, `high`, `xhigh`), `-C` working root,
+`--write`, `--resume <thread>`, `--prompt-file <file>`, `--schema <json-schema-file>`,
+`--timeout <seconds>`, `--trace`. Run it with `--help` for the full list.
+
+The run prints a footer with the model, the sandbox, the time, the output tokens, the resume
+id and the log path. Read the log only when a run fails.
+
+## Pick the model
+
+| Model           | The work it fits                                                                                                 |
+| --------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `gpt-5.6-luna`  | Fast and cheap: a lookup, a grep, a question about one file.                                                     |
+| `gpt-5.6-terra` | Balanced agentic coding. The default for real work, and the wrapper's default.                                   |
+| `gpt-5.6-sol`   | A reliable workhorse for a straight task. It costs about what `fable` costs, so ask the user before you pick it. |
+| `gpt-6-astra`   | Complex, demanding work. The most expensive of the four, so ask the user before you pick it.                     |
+
+Effort follows both the flag and the prompt. Pass `-e low` for a lookup and `-e high` for a
+hard bug. Say "keep it brief" in the prompt when you want a short answer.
+
+## Read-only by default
+
+A run without `--write` gets the `read-only` sandbox. Codex can read and run commands, but it
+cannot change a file. This is the right mode for a review, a second opinion and research.
+
+Pass `--write` only when the user asked for a code change from Codex. Two rules hold then:
+
+1. **Codex must not commit, push, or run `git add`.** Say so in the prompt. Other sessions
+   share this checkout, so a broad stage takes work that is not yours.
+2. **Name the files it may touch.** An open brief in a shared checkout is how two agents edit
+   the same file.
+
+`--resume` carries the sandbox and the working root of the thread it resumes. A thread that
+started read-only stays read-only, so start a new run when you need write access.
+
+## Run several at once
+
+The wrapper blocks until the agent is done, which takes minutes for real work. Start each run
+as a background command, and collect the answers when they arrive. Give each run its own
+question. Two agents on one question waste a model.
+
+## Write the prompt for a stranger
+
+The Codex agent shares no context with you. It sees your prompt, the repository and
+`AGENTS.md`. So:
+
+- State the task as one question, and name what "done" means.
+- Give the file paths you already know. It costs a model minutes to find what you can name.
+- Ask for the shape of the answer: a verdict, a list of findings with `file:line`, a patch in
+  a fenced block.
+- Do not paste the repository rules. It reads them itself.
+
+Pass `--schema` with a JSON Schema file when you want the answer as JSON you can parse.
+
+## Before you reach for it
+
+- `codex` must be on `PATH` and logged in. If it is not, tell the user and stop. Do not
+  install it, and do not write a token into the repository.
+- If Codex reports that the project is not trusted, ask the user to run `codex` once in the
+  repository and trust it there.
+- A Codex run is not free. Prefer it where a second model earns its cost, not for the
+  twentieth grep.

package/content/skills/codex-subagent/codex-agent.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Run one Codex agent to completion and print only its final message.
+ *
+ * `codex exec` streams its whole reasoning and command trace to stdout. That trace costs a
+ * calling agent more context than the answer is worth, so it stays in a log file here.
+ *
+ * Usage: node codex-agent.mjs [options] "<prompt>"
+ */
+
+import { spawn } from 'node:child_process';
+import { createWriteStream, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const DEFAULT_MODEL = 'gpt-5.6-terra';
+const DEFAULT_TIMEOUT_SECONDS = 900;
+
+const USAGE = `Usage: node codex-agent.mjs [options] "<prompt>"
+
+  -m, --model <id>        Model id (default ${DEFAULT_MODEL})
+  -e, --effort <level>    Reasoning effort: low | medium | high | xhigh
+  -w, --write             Let the agent edit the working tree (default: read-only)
+  -C, --cd <dir>          Working root for the agent (default: the current directory)
+      --resume <thread>   Continue an earlier thread instead of starting one
+      --prompt-file <f>   Read the prompt from a file
+      --schema <file>     JSON Schema the final message must match
+      --timeout <sec>     Give up after this many seconds (default ${DEFAULT_TIMEOUT_SECONDS})
+      --trace             Also print the command and file-change trace
+  -h, --help              Print this help`;
+
+const parseArgs = (argv) => {
+  const options = {
+    model: DEFAULT_MODEL,
+    effort: '',
+    write: false,
+    cd: process.cwd(),
+    resume: '',
+    promptFile: '',
+    schema: '',
+    timeout: DEFAULT_TIMEOUT_SECONDS,
+    trace: false,
+    prompt: '',
+  };
+
+  const rest = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = () => {
+      index += 1;
+      if (index >= argv.length) throw new Error(`${arg} needs a value.`);
+      return argv[index];
+    };
+
+    if (arg === '-m' || arg === '--model') options.model = next();
+    else if (arg === '-e' || arg === '--effort') options.effort = next();
+    else if (arg === '-w' || arg === '--write') options.write = true;
+    else if (arg === '-C' || arg === '--cd') options.cd = next();
+    else if (arg === '--resume') options.resume = next();
+    else if (arg === '--prompt-file') options.promptFile = next();
+    else if (arg === '--schema') options.schema = next();
+    else if (arg === '--timeout') options.timeout = Number(next());
+    else if (arg === '--trace') options.trace = true;
+    else if (arg === '-h' || arg === '--help') options.help = true;
+    else if (arg.startsWith('-') && arg !== '-') throw new Error(`Unknown option ${arg}.`);
+    else rest.push(arg);
+  }
+
+  options.prompt = options.promptFile ? readFileSync(options.promptFile, 'utf8') : rest.join(' ');
+
+  return options;
+};
+
+const readStdin = () =>
+  new Promise((resolve) => {
+    let buffer = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (buffer += chunk));
+    process.stdin.on('end', () => resolve(buffer));
+  });
+
+const buildArgs = (options, lastMessageFile) => {
+  const args = ['exec'];
+
+  if (options.resume) args.push('resume');
+
+  args.push('--json', '--skip-git-repo-check', '-o', lastMessageFile, '-m', options.model);
+
+  // `codex exec resume` carries the sandbox and the working root of the session it resumes,
+  // and rejects both flags, so only a fresh run may pass them.
+  if (!options.resume) {
+    args.push('-C', options.cd, '--sandbox', options.write ? 'workspace-write' : 'read-only');
+  }
+
+  if (options.effort) args.push('-c', `model_reasoning_effort="${options.effort}"`);
+  if (options.schema) args.push('--output-schema', options.schema);
+  if (options.resume) args.push(options.resume);
+
+  args.push('-');
+
+  return args;
+};
+
+const describeItem = (item) => {
+  if (item.type === 'command_execution') return `$ ${String(item.command ?? '').split('\n')[0]}`;
+  if (item.type === 'file_change') {
+    const changes = Array.isArray(item.changes) ? item.changes : [];
+    return `~ ${changes.map((change) => `${change.kind ?? 'edit'} ${change.path ?? ''}`).join(', ')}`;
+  }
+  if (item.type === 'error') return `! ${item.message ?? 'unknown error'}`;
+  return '';
+};
+
+const duration = (milliseconds) => {
+  const seconds = Math.round(milliseconds / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`;
+};
+
+const run = async () => {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  if (!options.prompt.trim() && !process.stdin.isTTY) options.prompt = await readStdin();
+
+  if (!options.prompt.trim()) {
+    process.stderr.write(`${USAGE}\n`);
+    return 2;
+  }
+
+  const logDir = join(tmpdir(), 'codex-agent');
+  mkdirSync(logDir, { recursive: true });
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logFile = join(logDir, `${stamp}.jsonl`);
+  const lastMessageFile = join(logDir, `${stamp}.last.md`);
+  const log = createWriteStream(logFile);
+  const started = Date.now();
+
+  const child = spawn('codex', buildArgs(options, lastMessageFile), {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: process.env,
+  });
+
+  child.stdin.end(options.prompt);
+
+  const state = { thread: '', usage: null, errors: [], trace: [], failed: false };
+
+  createInterface({ input: child.stdout }).on('line', (line) => {
+    log.write(`${line}\n`);
+
+    let event;
+
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    if (event.type === 'thread.started') state.thread = event.thread_id ?? '';
+    else if (event.type === 'turn.completed') state.usage = event.usage ?? null;
+    else if (event.type === 'turn.failed') {
+      state.failed = true;
+      state.errors.push(event.error?.message ?? 'the turn failed');
+    } else if (event.type === 'item.completed') {
+      const description = describeItem(event.item ?? {});
+      if (description) state.trace.push(description);
+      if (event.item?.type === 'error') state.errors.push(event.item.message ?? 'unknown error');
+    }
+  });
+
+  let stderrText = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => (stderrText += chunk));
+
+  const timer = setTimeout(() => child.kill('SIGKILL'), Math.max(1, options.timeout) * 1000);
+  const code = await new Promise((resolve) => child.on('close', resolve));
+
+  clearTimeout(timer);
+  log.end();
+
+  let finalMessage;
+
+  try {
+    finalMessage = readFileSync(lastMessageFile, 'utf8').trim();
+    rmSync(lastMessageFile, { force: true });
+  } catch {
+    finalMessage = '';
+  }
+
+  const failed = code !== 0 || state.failed || (!finalMessage && state.errors.length > 0);
+
+  if (options.trace && state.trace.length > 0) process.stdout.write(`${state.trace.join('\n')}\n\n`);
+  if (finalMessage) process.stdout.write(`${finalMessage}\n`);
+
+  if (failed) {
+    const reason = state.errors.join('\n') || stderrText.trim() || `codex exited with code ${code}`;
+    process.stdout.write(`\ncodex agent FAILED: ${reason}\n`);
+  }
+
+  const parts = [
+    `codex ${options.model}`,
+    options.write ? 'workspace-write' : 'read-only',
+    duration(Date.now() - started),
+  ];
+
+  if (state.usage) parts.push(`${state.usage.output_tokens ?? 0} out tok`);
+
+  process.stdout.write(`\n--- ${parts.join(' · ')}\n`);
+
+  if (state.thread) process.stdout.write(`resume: --resume ${state.thread}\n`);
+
+  process.stdout.write(`log: ${logFile}\n`);
+
+  return failed ? 1 : 0;
+};
+
+run().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(2);
+  },
+);