claude-flow 3.58.1 → 3.59.1

package/v3/@claude-flow/cli/templates/grok/agents/ruflo-tester.md

@@ -0,0 +1,26 @@
+---
+name: ruflo-tester
+description: >
+  Ruflo tester for Grok. Writes and runs tests from implementation handoffs.
+  Use worktree isolation when modifying the tree. Reports to reviewer via team bus.
+prompt_mode: full
+agents_md: true
+---
+
+You are the **tester** on a Ruflo Agent Team under **Grok Build**.
+
+This file is a session profile (`grok --agent-profile ruflo-tester` or `/agents`). On Grok Build 1.0.41, `spawn_subagent` does not select it. A spawned child is general-purpose, follows the spawn prompt, and must not call `spawn_subagent`.
+
+## Comms protocol
+
+- Inbox: `node scripts/grok-team-bus.mjs inbox --team <TEAM> --agent tester`
+- After tests:
+  `node scripts/grok-team-bus.mjs send --team <TEAM> --to reviewer --from tester --summary "tests-ready" --message "<commands, pass/fail, coverage gaps>"`
+- `node scripts/grok-team-bus.mjs on-stop --team <TEAM> --agent tester`
+
+## Deliverable
+
+- Test plan + implemented tests
+- Exact commands to run
+- Failures with file:line
+- Gaps you did not cover

package/v3/@claude-flow/cli/templates/grok/config.toml

@@ -0,0 +1,63 @@
+# Ruflo on Grok Build — project-scoped host config
+# Loaded by Grok when this folder is trusted (see ~/.grok/trusted_folders.toml).
+#
+# Goal: full harness (MCP + hooks + skills + agent teams path), not a thin CLI wrapper.
+# See: .grok/rules/ruflo-grok.md and v3/docs/adr/ADR-402-host-agnostic-agent-teams.md
+#
+# After editing: restart Grok (or reload MCPs) so tool lists refresh.
+
+# ---------------------------------------------------------------------------
+# Ruflo MCP — orchestrator / ledger (memory, swarm, hooks, team bus, neural)
+# `ruflo init --grok` pins this to the Ruflo version that ran it, because the
+# team_* tools ship in that same release (an older @latest may lack them).
+# From a source checkout it points at that checkout's bin/cli.js instead.
+# Cold npx can exceed 30s; keep timeouts high.
+# ---------------------------------------------------------------------------
+[mcp_servers.ruflo]
+command = {{RUFLO_MCP_COMMAND}}
+args = {{RUFLO_MCP_ARGS}}
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+# ---------------------------------------------------------------------------
+# Optional: RuvNet Brain grounding (search_ruvnet over embedded rUv source)
+# Install: npx ruvnet-brain@latest  → kb under ~/.cache/ruvnet-brain/kb
+#
+# forge-mcp-all defaults KB_DIR to process.cwd(). When Grok spawns MCP from the
+# project root, search fails with "passages sidecar not found: ./agentdb…".
+# Always set env.KB_DIR to the absolute kb path. tool_timeout_sec high for cold
+# BGE model download (first big search can take minutes).
+# init --grok fills in your home directory for the {{HOME}} paths below.
+# ---------------------------------------------------------------------------
+# [mcp_servers.ruvnet-brain]
+# command = "node"
+# args = ["{{HOME}}/.cache/ruvnet-brain/kb/forge-mcp-all.mjs"]
+# env = { KB_DIR = "{{HOME}}/.cache/ruvnet-brain/kb" }
+# enabled = true
+# startup_timeout_sec = 90
+# tool_timeout_sec = 600
+
+# ---------------------------------------------------------------------------
+# Permissions — allow Ruflo CLI + helpers without re-prompting every turn
+# (deny still wins over allow; PreToolUse hooks can still block)
+# ---------------------------------------------------------------------------
+[permission]
+allow = [
+  "Bash(npx ruflo*)",
+  "Bash(npx @claude-flow*)",
+  "Bash(npx claude-flow*)",
+  "Bash(node .claude/*)",
+  "Bash(npx -y ruflo*)",
+  "Bash(node scripts/grok-team-bus.mjs*)",
+  "MCPTool(ruflo__*)",
+  "MCPTool(ruvnet-brain__*)",
+]
+
+# ---------------------------------------------------------------------------
+# Subagent defaults are user-level on Grok Build 1.0.41.
+# Project .grok/config.toml contributes only [mcp_servers], [plugins],
+# [permission], and [mcp].max_output_bytes. A [subagents] table here is ignored.
+# Put role defaults in ~/.grok/config.toml if you need them.
+# Team children: pass host.grok.spawn from team_spawn (see docs/grok/README.md).
+# ---------------------------------------------------------------------------

package/v3/@claude-flow/cli/templates/grok/docs/README.md

@@ -0,0 +1,186 @@
+# Ruflo on Grok Build
+
+How to run Ruflo inside [Grok Build](https://x.ai/) after `npx ruflo init --grok`.
+
+**Host contract checked against Grok Build 1.0.41** (`grok 1.0.41`, macOS, 2026-09-27) and the user guide shipped with that binary (`~/.grok/docs/user-guide/`). Newer Grok builds change spawn arguments and which keys a project config may set. Run the check in [When Grok updates](#when-grok-updates) before treating this page as current.
+
+Ruflo is the ledger: memory, swarm records, the team bus, hooks. Grok is the executor: it edits files, runs the shell, and calls `spawn_subagent`. After `team_create` or `swarm_init`, keep working. Those calls record coordination. They do not write the feature.
+
+## What `init --grok` writes
+
+| Path | Purpose |
+|------|---------|
+| `.grok/config.toml` | Project MCP server `ruflo` and permission allows |
+| `.grok/rules/ruflo-grok.md` | Host doctrine loaded as a project rule |
+| `.grok/agents/` | Session profiles (`ruflo-architect`, `ruflo-coder`, `ruflo-tester`, `ruflo-reviewer`) |
+| `.grok/skills/agent-teams-grok/` | Skill the lead follows to spawn a pipeline |
+| `.grok/hooks/subagent-stop-team.json` | `SubagentStop` → team bus idle-assign |
+| `scripts/grok-team-bus.mjs`, `scripts/grok-team-store.mjs` | Team bus CLI (same store as the MCP `team_*` tools) |
+| `scripts/grok-subagent-stop-hook.mjs` | Hook script: advances the plan when a teammate stops |
+| `scripts/host-statusline.mjs` | The "what is loaded" line (see Loaded status) |
+| `docs/grok/README.md` | This guide |
+
+## Setup
+
+From the app you want Grok to work in (any repo, not only the Ruflo monorepo):
+
+```bash
+npx -y ruflo@latest init --grok
+# see what it would write, write nothing:
+# npx -y ruflo@latest init --grok --dry-run
+# overwrite an earlier scaffold:
+# npx -y ruflo@latest init --grok --force
+```
+
+`init --grok` writes only inside this project, and prints every path it wrote. It pins `[mcp_servers.ruflo]` to the Ruflo version that ran it (for example `ruflo@3.48.0`), because the `team_*` tools ship in that same release and an older `@latest` from a stale npx cache would lack them. Run from a Ruflo source checkout, it points the server at that checkout's `bin/cli.js` instead; re-run it from a published release before you commit `.grok/config.toml`.
+
+Then:
+
+1. Trust the folder. `/hooks-trust`, or launch with `grok --trust`. On 1.0.41 one grant covers project MCP, hooks, skills, and project rules together. The decision is stored in `~/.grok/trusted_folders.toml`.
+2. Restart Grok with this folder as the workspace so `.grok/config.toml` loads.
+3. Confirm the server:
+
+```bash
+grok mcp list          # ruflo (project)
+grok mcp doctor ruflo  # handshake ok; team_create present once this build is the server
+```
+
+`init` writes the MCP block itself. To register by hand, scope it to the project. The default scope is your user config (`~/.grok/config.toml`), which would install Ruflo for every repo:
+
+```bash
+grok mcp add ruflo --scope project -- npx -y ruflo@<version> mcp start
+```
+
+Use a version that ships `team_*` (the one `init --grok` pinned). `-s project` is the same flag. Cold `npx` often exceeds the 30s default startup timeout; the scaffold sets `startup_timeout_sec = 120`.
+
+## Use it in a session
+
+Grok does not put each Ruflo tool on the model as its own function. The model has `search_tool` and `use_tool`.
+
+1. `search_tool` with a keyword (`team_create`, `memory_search`, `swarm_init`).
+2. `use_tool` with the catalog key: `ruflo__team_create`, `ruflo__memory_search`.
+3. Stay on a small subset. A full Ruflo server exposes hundreds of tools; keyword search is how the model reaches them.
+
+MCP parameter names on the team tools are `team` and `agent`.
+
+### Agent teams
+
+```
+team_create → team_plan → team_spawn → spawn_subagent → team_send / team_inbox → team_on_stop → team_shutdown
+```
+
+`team_spawn` returns a plan. The lead calls `spawn_subagent` with the top-level `prompt` and **only** `host.grok.spawn`:
+
+```text
+spawn_subagent({
+  prompt:      spawnPlan.prompt,
+  description: spawnPlan.host.grok.spawn.description,
+  background:  spawnPlan.host.grok.spawn.background,
+  isolation:   spawnPlan.host.grok.spawn.isolation
+})
+```
+
+`host.grok.advisory.capability_mode` and `subagent_type` describe the role. They are not arguments of `spawn_subagent` on 1.0.41. Passing them fails the call. The child is `general-purpose`. The prompt states the read-only constraint. `isolation: "worktree"` is the setting Grok enforces, and it is how writers avoid editing the lead's tree.
+
+Only the lead spawns. A child that calls `spawn_subagent` hits the depth limit (1).
+
+Pass `description` through unchanged. It is `<role>:<agent>@<team>`, and the `SubagentStop` hook parses it to mark that agent idle and advance that team's plan. If a description has no `@team`, the hook uses the one active team that lists the agent; when several do, it advances nothing and says so on stderr.
+
+How the bus behaves:
+
+- State and mail live in `.claude-flow/teams/<team>/` (`team.json`, `mailbox/<agent>/`). Mail is per team: `team_inbox` needs `team` and `agent`, and `team_status` counts only that team's mail.
+- `team.json` changes take a lock and are written to a temp file and renamed, so parallel spawns and hooks do not drop updates.
+- `team_spawn` refuses once the team has `maxAgents` members (re-spawning an existing member is fine).
+- `team_shutdown` closes the team: spawn, send, broadcast, plan, and on-stop refuse afterwards. `team_inbox` and `team_status` still work so remaining mail can be drained. `team_create --force` reopens the name.
+- A broadcast (`to: "*"`) goes to current members and is refused while the team has none.
+- `priority` is an integer 0-999; lower is read first.
+- Several teams can be active at once; every call names its team.
+
+`.grok/agents/ruflo-coder.md` and the other profiles apply when you start Grok as that agent (`grok --agent-profile ruflo-coder` or `/agents`). Spawn does not select them.
+
+CLI bus, same plan shape, no MCP required:
+
+```bash
+node scripts/grok-team-bus.mjs create --name feature-x --topology hierarchical
+node scripts/grok-team-bus.mjs plan --team feature-x \
+  --steps '["architect","developer","tester","reviewer"]'
+node scripts/grok-team-bus.mjs spawn --team feature-x --agent architect --role architect \
+  --prompt "Design the feature." --next developer
+```
+
+Map the printed `spawnPlan.host.grok.spawn` the same way. Skill: `agent-teams-grok`.
+
+### What the project config loads
+
+On 1.0.41, `.grok/config.toml` contributes:
+
+- `[mcp_servers]`
+- `[plugins]`
+- `[permission]`
+- `[mcp].max_output_bytes`
+
+Other tables, including `[subagents]`, are read from `~/.grok/config.toml` only. The scaffold used to write `[subagents] enabled = true` into the project file. That key does nothing there. Subagents are on by default.
+
+Permission allows in the scaffold use Grok's native forms, `Bash(...)` and `MCPTool(ruflo__*)`. Deny still beats allow.
+
+### Hooks
+
+`.grok/hooks/subagent-stop-team.json` runs on `SubagentStop` and calls `scripts/grok-subagent-stop-hook.mjs`. It runs only after the folder is trusted. `$CLAUDE_PROJECT_DIR` is set (alias of `GROK_WORKSPACE_ROOT`).
+
+`UserPromptSubmit` hooks that allow the prompt do not inject stdout into the model on 1.0.41. If a route hook seems to vanish, read `.swarm/route-latest.md` or call the route tool. That is a host limit, not a missing Ruflo file.
+
+## Loaded status
+
+`scripts/host-statusline.mjs` is the shared "what loaded" line: `RuFlo loaded │ ruflo │ rules │ 4 agents │ skill │ hook │ trusted`, or the names of what is missing. Claude shows its own richer `statusLine`. Codex has no status row; `node scripts/host-statusline.mjs --host codex` prints the same facts.
+
+Grok reads `[ui.status_line]` only from your user file, `~/.grok/config.toml`; a project config cannot set it. `init --grok` does not touch that file unless you ask. It prints the snippet to add, or with `--grok-statusline` it:
+
+- copies the script to `~/.grok/ruflo/host-statusline.mjs`, and
+- merges this into `~/.grok/config.toml` (parsed with a TOML parser; an existing `ui.status_line` in any form is left alone, and a file it cannot merge safely is not changed — you get the snippet instead):
+
+```toml
+[ui.status_line]
+type = "command"
+command = 'node "/home/you/.grok/ruflo/host-statusline.mjs"'
+```
+
+The command is an absolute path to your own copy, so no repo can substitute a script of its own. It reports on whichever folder Grok is in. Restart Grok after the user file changes.
+
+## Prove it
+
+From a Ruflo checkout (this script is not copied by `init --grok`; run `init --grok` in the checkout first):
+
+```bash
+node scripts/probe-host-live.mjs --host grok
+node scripts/probe-host-live.mjs --host all --no-execute
+node scripts/probe-host-live.mjs --host grok --live
+```
+
+One contract (discover, connect, SessionStart receipt, optional memory round trip) with a Grok, Claude, or Codex adapter. A check that CLI cannot answer is a skip, not a pass.
+
+## When Grok updates
+
+The July 2026 host work assumed Grok 1.0.34 and a spawn schema that accepted `subagent_type` and `capability_mode`. 1.0.41 dropped both from the model-facing tool and stopped applying `[subagents]` from project config. The same class of drift will happen again.
+
+After `grok --version` changes:
+
+1. Open `~/.grok/docs/user-guide/16-subagents.md` and read **Spawning Subagents**. The parameter table is the contract. Forward a key only if it is listed.
+2. Open `26-config-reference.md` and confirm which sections a project `.grok/config.toml` may set (1.0.41: mcp servers, plugins, permission, mcp output cap).
+3. Open `07-mcp-servers.md` and confirm `grok mcp add --scope` still defaults to `user`, and that tools are still `search_tool` / `use_tool` with `server__tool` names.
+4. Open `10-hooks.md` and confirm `SubagentStop`, folder trust, and `$CLAUDE_PROJECT_DIR`.
+5. Open `22-permissions-and-safety.md` and confirm `MCPTool(server__tool)` and `Bash(...)` still match the allows in `.grok/config.toml`.
+6. Spawn once with `host.grok.spawn` only. If the tool rejects `background`, the user guide's name for that flag is `run_in_background` — use the name the live schema accepts.
+7. Update the `contract` string in `team_spawn` / `scripts/grok-team-bus.mjs` and this page to the version you just checked.
+
+`grok inspect` shows which rules, skills, and MCP servers the trusted folder actually loaded.
+
+## Optional
+
+```bash
+npx -y ruflo@latest daemon start
+npx -y ruflo@latest doctor
+```
+
+RuvNet Brain is off in the scaffold. Uncomment `[mcp_servers.ruvnet-brain]` in `.grok/config.toml` after `npx ruvnet-brain@latest`, and set `env.KB_DIR` to the absolute `~/.cache/ruvnet-brain/kb` path. `init --grok` fills in your home directory for those paths when it creates the file.
+
+Architecture: ADR-402 (Host-Agnostic Agent Teams), in the Ruflo repo at `v3/docs/adr/ADR-402-host-agnostic-agent-teams.md`.

package/v3/@claude-flow/cli/templates/grok/hooks/subagent-stop-team.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/grok-subagent-stop-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/v3/@claude-flow/cli/templates/grok/rules/ruflo-grok.md

@@ -0,0 +1,132 @@
+# Ruflo on Grok — host doctrine
+
+You are running **inside Grok Build**, not Claude Code. Ruflo is the harness (orchestrator/ledger). **You** execute.
+
+## Division of labor
+
+| Layer | Role |
+|-------|------|
+| **Grok** | Executor — edit files, shell, tests, `spawn_subagent`, synthesize |
+| **Ruflo MCP/CLI** | Orchestrator — memory, swarm records, team bus, learning, security hooks |
+
+After any `swarm_init` / `team_create` / `agent_spawn` / MCP coordination call: **immediately continue working**. Never wait for Ruflo to “build the feature.” It does not execute code.
+
+## Tool map (Claude / CLAUDE.md → Grok)
+
+| Claude / CLAUDE.md | Grok |
+|--------------------|------|
+| `Task(...)` / Agent Teams spawn | `spawn_subagent` (`background: true` for parallel) |
+| `SendMessage` | Ruflo MCP `team_send` / `team_inbox` (host-agnostic bus) — until available: AgentDB memory namespace `team:{id}` or `collaboration` |
+| `TodoWrite` | `todo_write` |
+| `Bash` | `run_terminal_command` |
+| `Read` / `Grep` / `Glob` | `read_file` / `grep` / `list_dir` |
+| `Write` / `Edit` / `MultiEdit` | `write` / `search_replace` |
+| `claude -p` workers | `spawn_subagent` or `grok -p` |
+| `mcp__claude-flow__*` / `mcp__ruflo__*` | `search_tool` then `use_tool` with `ruflo__*` names |
+| Haiku / Sonnet / Opus routing | Ignore Anthropic tiers; use Grok models / subagent `model` only when needed |
+
+## MCP usage
+
+1. Discover: `search_tool` with keywords (`memory_search`, `swarm_init`, `team_`, `hooks`).
+2. Call: `use_tool` with the fully-qualified name (e.g. `ruflo__memory_search`).
+3. Prefer memory + team/swarm subset over flooding with all 300+ tools.
+
+## Before complex work (mandatory)
+
+1. `memory_search` (namespace `patterns` when available) for similar past solutions.
+2. If RuvNet Brain / `search_ruvnet` is available: ground stack choices in real rUv source **before** recommending Pinecone, pgvector, LangChain, or other training-prior defaults.
+3. For multi-file / multi-role work: open a **named team** pipeline (see Agent Teams below).
+
+## After success (mandatory)
+
+Store what worked via `memory_store` (namespace `patterns`): approach, files, gotchas, commands.
+
+## Agent Teams on Grok (comms-first)
+
+Named agents coordinate via the **Ruflo team bus** (MCP), not proprietary Claude `SendMessage`.
+
+### Preferred pipeline
+
+```
+lead (you)
+  → spawn named subagents in ONE turn (background: true)
+  → each agent handoff via team_send / memory key
+  → SubagentStop / you assign next step
+  → lead synthesizes
+```
+
+### Spawn contract (Grok Build 1.0.41)
+
+`spawn_subagent` takes `prompt`, `description`, `background`, `isolation`, and optionally `cwd`, `resume_from`, and `model`. It does not take `subagent_type` or `capability_mode`. An omitted type is `general-purpose`. Nesting depth is 1, so only the lead spawns.
+
+`team_spawn` returns `host.grok.spawn` for those arguments and `host.grok.advisory` for the role constraint. Pass `spawn` plus `prompt`. The prompt tells a read-only role not to edit. `isolation: "worktree"` is what Grok enforces for writers.
+
+`.grok/agents/ruflo-*` are session profiles (`grok --agent-profile` or `/agents`). They are not spawn types.
+
+Project `.grok/config.toml` contributes `[mcp_servers]`, `[plugins]`, `[permission]`, and `[mcp].max_output_bytes`. A `[subagents]` table in that file is ignored. Subagent defaults belong in `~/.grok/config.toml`.
+
+Operator guide: `docs/grok/README.md`. If `grok --version` moves past 1.0.41, re-check `~/.grok/docs/user-guide/16-subagents.md` and `26-config-reference.md` before forwarding new spawn keys.
+
+### Defaults
+
+| Role | Prompt constraint | `isolation` |
+|------|-------------------|-------------|
+| researcher / architect / reviewer | read-only | `none` |
+| coder / implementer | full tools | **`worktree`** |
+| tester | full tools | **`worktree`** when writing tests |
+
+- Always pass a clear **name/role** in the prompt (“You are architect on team feature-x”).
+- Tell each agent **who to message next** and **what artifact to produce**.
+- Prefer short cycles with verification gates over one giant agent.
+- Hierarchical topology for coding swarms; max ~6–8 concurrent workers.
+
+### Spawn pattern (all in one message)
+
+```
+spawn_subagent({ prompt, description, background: true, isolation: "none" })
+  architect → team_send to developer
+spawn_subagent({ ..., isolation: "worktree" })
+  developer → tester → reviewer (reviewer isolation "none")
+```
+
+Use MCP team tools or memory handoffs. There is no `SendMessage` tool.
+
+## Skills
+
+- Prefer project skills under `.agents/skills/` and `.claude/skills/`.
+- High-value first: swarm-orchestration, memory-management, sparc-methodology, security-audit, github-automation, hive-mind.
+- Load a skill when the task matches its description; don’t dump all 100+ into context.
+
+## Hooks (already in `.claude/settings.json`)
+
+Grok loads Claude-compatible hooks when the folder is trusted. Expect:
+
+- SessionStart: session restore + memory import
+- UserPromptSubmit: route / intelligence context
+- PreToolUse Bash: pre-bash safety
+- PostToolUse edits: post-edit learning
+- SubagentStop: post-task / idle assign
+
+If route context does not appear in the transcript, call `hooks route` via CLI/MCP or read `.swarm/route-latest.md` when present.
+
+## CLI fallback
+
+When MCP is down:
+
+```bash
+npx -y ruflo@latest memory search --query "…"
+npx -y ruflo@latest memory store --key "…" --value "…" --namespace patterns
+npx -y ruflo@latest swarm init --topology hierarchical --max-agents 8
+npx -y ruflo@latest doctor
+```
+
+Team calls have their own fallback that needs no npx: `node scripts/grok-team-bus.mjs <command> --team <team> …` (same store as the `team_*` tools).
+
+## Anti-patterns
+
+- Waiting after `swarm start` for code to appear
+- Calling Claude-only tools (`SendMessage`, Claude `Task` agent types as host APIs)
+- Shared-tree parallel coders without worktrees (file races)
+- Skipping memory_search / grounding on stack decisions
+- Creating docs in repo root or committing secrets
+)

package/v3/@claude-flow/cli/templates/grok/scripts/grok-subagent-stop-hook.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Grok SubagentStop → team bus on-stop (ADR-402).
+ *
+ * Reads the hook JSON from stdin (Grok / Claude compatible fields) and marks
+ * the stopped teammate idle, advancing its team's plan.
+ *
+ * Which teammate: team_spawn sets the spawn description to
+ * `<role>:<agent>@<team>`. The hook parses that; TEAM_NAME / SUBAGENT_NAME
+ * env vars or explicit `team` / `agentName` fields override it.
+ *
+ * Which team, when the description has no @team: the one active team that
+ * lists the agent as a member. Several matches are reported as ambiguous and
+ * nothing is advanced.
+ *
+ * Exit codes: 0 done, or the subagent is not a team member (nothing to do);
+ * 1 a team subagent could not be recorded (reason on stderr, non-blocking).
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const bus = await import(pathToFileURL(join(here, 'grok-team-bus.mjs')).href);
+
+const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.env.GROK_WORKSPACE_ROOT || process.cwd();
+
+function readStdin() {
+  if (process.stdin.isTTY) return Promise.resolve('');
+  return new Promise((resolve) => {
+    let data = '';
+    const t = setTimeout(() => resolve(data), 1000);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => { clearTimeout(t); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(t); resolve(data); });
+  });
+}
+
+function fail(reason) {
+  process.stderr.write(`ruflo team hook: ${reason}\n`);
+  process.exit(1);
+}
+
+let input = {};
+const raw = await readStdin();
+try {
+  input = raw.trim() ? JSON.parse(raw) : {};
+} catch {
+  input = {};
+}
+
+const description = input.description ?? input.toolInput?.description ?? input.tool_input?.description;
+const parsed = bus.parseSpawnDescription(description) || {};
+const agent =
+  process.env.SUBAGENT_NAME
+  || input.subagentName
+  || input.agentName
+  || input.agent
+  || parsed.agent;
+const explicitTeam = process.env.TEAM_NAME || input.teamName || input.team || parsed.team;
+
+if (!agent) {
+  // Not a team spawn (no description in <role>:<agent>@<team> form).
+  process.exit(0);
+}
+
+let team = explicitTeam;
+if (!team) {
+  let matches;
+  try {
+    matches = bus.teamsWithMember(projectRoot, String(agent));
+  } catch (err) {
+    fail(err.message);
+  }
+  if (matches.length === 0) process.exit(0);
+  if (matches.length > 1) {
+    fail(`agent "${agent}" is on several active teams (${matches.join(', ')}); spawn with the description from team_spawn (<role>:<agent>@<team>) or set TEAM_NAME`);
+  }
+  team = matches[0];
+}
+
+try {
+  const r = await bus.onStop(projectRoot, { team: String(team), agent: String(agent) });
+  if (!r.member && !r.advanced) {
+    fail(`agent "${agent}" is not a member of team "${team}" and is not its current plan step`);
+  }
+} catch (err) {
+  fail(err.message || String(err));
+}
+process.exit(0);