---
description: "Queue an instruction for a task that is already running. It is applied at the next phase boundary, not mid-phase. Use when a run is going the wrong way and killing it would throw away good work."
description-tr: "Zaten koşmakta olan bir göreve talimat bırakır. Talimat faz ortasında değil, bir sonraki faz sınırında uygulanır. Koşu yanlış yöne gidiyorsa ve kill etmek iyi işi de çöpe atacaksa kullanılır."
argument-hint: "#id \"<instruction>\"  -  e.g. #3 \"the field is called web, not frontend\". With no instruction, you are asked for it."
---

# multi-agent steer  -  correct a run without stopping it

**Input**: $ARGUMENTS

Leave one instruction for a running task. The next phase reads it before it
starts work, applies it, and marks it consumed.

This exists because the alternative was losing the run. `kill` stops a task and
deletes its worktree; `resume` picks a stopped one back up. Neither helps while
a phase is in flight, so a correction that arrived mid-run - "that field is
called `web`, not `frontend`", "keep the analysis, drop the rest" - had nowhere
to go, and the run carried on in the wrong direction until it finished.

**Not a second prompt.** One instruction is queued at a time. Steering a task
that already has an unconsumed instruction replaces it, after showing you what
is being replaced.

## Steps

1. **Find the task**  -  parse `#N` or `{JIRA-KEY}-XXXXX` from the argument,
   the same way `kill` and `resume` do. Locate its `agent-state.json`:

   ```bash
   find {repo}/.worktrees/ -name "agent-state.json" -maxdepth 2
   find $HOME/.claude/logs/multi-agent -maxdepth 4 -name agent-state.json -path '*/artifacts/*'
   ```

   Not found → `ERR: no task #N. '/multi-agent:status' lists what is running.`

2. **Check it can still be steered**  -  read `status` and `currentPhase`:

   | State | What to do |
   |---|---|
   | `in_progress` | Queue it. This is the case the command is for. |
   | `paused` / `failed` | Say the task is not running, and that `/multi-agent:resume #N` will re-enter with the instruction applied at that phase's entry. Queue it. |
   | `complete` | Refuse. Nothing will read it. Point at `/multi-agent` for a follow-up run. |

   `currentPhase` is 7 and status is `in_progress` → warn that Phase 7 is the
   last one, so an instruction queued now may never be consumed.

3. **Read the instruction**  -  from the argument, or ask for it when the
   argument carries only an id. Verbatim, up to 4000 characters. Do not
   summarize or rewrite it: the phase that consumes it needs the user's own
   words, and a paraphrase is where the meaning goes.

4. **Show what will be queued, and ask**:

   ```
   Steer #3 ({JIRA-KEY}-12345, Phase 3 Dev, in_progress)

     "the field is called web, not frontend"

   Applied at the entry to Phase 4. The current phase finishes as it is.
   ```

   Already carrying an unconsumed `pendingSteer` → print the old text above the
   new one and ask whether to replace it.

5. **Write it**  -  through the state writer, never by editing the file, because
   the running task is writing to it too. `$STATE_FILE` is the path from step 1
   and `$INSTRUCTION` the text from step 3:

   ```bash
   printf '{"pendingSteer":{"text":%s,"at":"%s","appliedAt":null,"appliedPhase":null}}' \
     "$(node -e 'process.stdout.write(JSON.stringify(process.argv[1]))' "$INSTRUCTION")" \
     "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
   ```

   The instruction is JSON-encoded by `node -e`, not by hand: it is arbitrary
   user text, and a quote or newline in it would otherwise produce invalid JSON
   or, worse, a payload that merges into fields nobody meant to touch.

   Exit 2 (lock timeout) → the task is mid-write. Retry once, then report it
   rather than forcing the write.

6. **Confirm**: `🧭 Steer queued for #N  -  applies at the entry to Phase {N+1}`

## What the phase does with it

Phase entry, before any work: read a `pendingSteer` that has no `appliedAt`.
When present, apply it to that phase's context, set `appliedAt` and
`appliedPhase` - which is what stops it being read a second time - and write a
`Steer applied` line into `agent-log.md`. The record itself stays, so the run
keeps the trace of what was asked and when. The contract lives in
`$HOME/.claude/multi-agent-refs/phases.md` under "Phase entry  -  pending
steer" (the file has a second, unrelated "Phase entry" line inside the tracker
block).

Applied at entry rather than the moment it arrives, on purpose: a phase that
changes target halfway through throws away the work it already did, which is
the outcome this command exists to avoid.

An instruction that contradicts the plan is not silently obeyed. The phase says
what it is changing, and a contradiction that would invalidate an approved plan
halts for the user instead of quietly rewriting it.

**One limit worth knowing.** The reader is the phase contract, so a task started
by an install that predates it will not consume the field: the instruction is
written and nothing picks it up. There is no version stamp on a state file to
detect this from, so the honest advice is that steer applies to runs started
after the install carrying it. A run already in flight from an older install is
still a `kill` or a wait.