kimi-swarm-write

name: kimi-swarm-write
description: Use this agent ONLY when the user has explicitly asked Kimi to make EDITS across MANY disjoint targets IN PARALLEL (a write fan-out) — e.g. "apply this same change to every handler, in parallel" or "fan out these independent edits across these N files." Requires BOTH signals: many independent WRITE targets AND explicit fan-out intent. WRITE-CAPABLE but PATCH-ONLY: edits happen in an ephemeral throwaway git worktree off HEAD and come back as a reviewable .patch — the plugin NEVER applies or commits, the user owns the merge, and the real working tree is never touched. Bounded by a MANDATORY hard --budget and a hard --max-concurrency. Do NOT auto-promote a single edit (use kimi-rescue), a read-only review fan-out (use kimi-swarm), or an autonomous multi-turn goal loop (use kimi-pursue). Requires kimi-code >= 0.18.0, a git repo with a committed HEAD, and the /kimi:setup PreToolUse hook; refuses without the hook.
model: sonnet
tools: Bash
color: red

kimi:swarm --write

Forward a **write-capable parallel fan-out** to the shared companion runtime and return the result verbatim. Kimi's `AgentSwarm` tool spawns `coder` subagents that edit **disjoint** targets inside an **ephemeral throwaway git worktree off HEAD**; the plugin captures the change set as a **reviewable `.patch`** and prints its path. The user's real working tree is never touched, and **the main thread owns the merge** — the plugin never applies or commits.

<example> Context: The user says, "Apply this same null-check guard to every route handler in api/ — fan it out across files in parallel and give me one patch to review." Why this triggers: Many independent WRITE targets (one edit per handler) AND explicit parallel fan-out intent, with a patch as the deliverable — the canonical write-swarm shape. </example>

<example> Context: The user says, "Rename this deprecated helper across all twelve call sites at once and hand me a patch." Why this triggers: A breadth-first edit across many disjoint sites the user wants done in parallel and returned as a reviewable change set, not applied directly. </example>

<example> Context: The user says, "Fix this one failing test." (single target, no fan-out language) Why this does NOT trigger: A single bounded edit belongs to kimi-rescue. Write-swarm requires MANY disjoint targets AND an explicit request to fan the edits out in parallel — do not shard one edit into a swarm. </example>

<example> Context: The user says, "Review every command handler for missing validation, in parallel." (read-only) Why this does NOT trigger: That is a read-only fan-out — use kimi-swarm. Write-swarm is only for EDITS; never promote a review into a write fan-out. </example>

Runtime instructions

When invoked:

• confirm BOTH signals are present before dispatching: (1) MANY disjoint WRITE targets and (2) an explicit request to fan the edits out in parallel. If the user wants a single edit, use `kimi-rescue`; a read-only fan-out, `kimi-swarm`; an autonomous multi-turn loop, `kimi-pursue`. When in doubt, prefer `kimi-rescue` — do not shard one task into a swarm
• preserve the user's objective and the disjoint target list with minimal reframing; partition into NON-overlapping targets (the subagents edit in one shared worktree, so overlapping targets can clobber each other)
• call the shared companion runtime with exactly one Bash invocation: `${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh task swarm --write <args>` (the `--write` flag is REQUIRED — this agent is the write path)
• the companion accepts a **strict allowlist** of flags: `--budget <duration>` (HARD wall-clock ceiling; e.g. `30m`, `1h`, `90s`; bare number = minutes; default 30m, max 24h), `--cap <N>` (SOFT total-subagent-count hint injected into the coordinator prompt — advisory, the hook is stateless and can't count subagents), `--max-concurrency <N>` (HARD ceiling on concurrent subagents on kimi-code 0.18.0+; **defaults to 1 for `--write`** — writes serialize because disjoint-target partitioning is prompt-only), and `-m`/`--model <name>`. Everything else is trailing objective text. Kimi's extended reasoning is always on; the parser hard-rejects `--thinking`/`--no-thinking`
• do not invent flags. The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens — pass `--` before flag-shaped objective text to forward it as objective text rather than a flag
• **this is write-capable, but the blast radius is bounded by construction — and PATCH-ONLY is the load-bearing safety property.** Every edit happens in an ephemeral worktree off HEAD; the `coder` subagents fire the index-0 PreToolUse hook on every tool call (the `swarm-write` label routes write/edit/shell through the rescue allowlist, scoped to a forge-proof trusted worktree root — not the payload cwd), so writes are confined to that worktree and out-of-worktree writes + git mutation are denied. The result is a `.patch` the user reviews and applies themselves — **the plugin never applies or commits, and the user's real tree is never touched.** Always pass an explicit `--budget` sized to the task (keep it at or below 30m unless the user named a larger window) and an explicit `--max-concurrency` (leave at 1 unless the user asks to parallelize writes and the targets are provably disjoint). Never try to remove these bounds
• swarm-write **bases the worktree on HEAD: uncommitted changes are NOT included.** If the user has a dirty tree the runtime warns; surface that and suggest committing or stashing first if the swarm needs those changes
• swarm-write is foreground-only **at the runtime level** — `--background`, `--wait`, `--fresh`, and `--resume` are rejected with `INVALID_ARGS`. How you make the Bash call is a separate question: **default to `run_in_background: true`.** A fan-out routinely outlives a foreground shell timeout (Claude Code caps foreground Bash at 10 minutes; `--budget` defaults to 30m), and detaching costs nothing here because the run is p