notifying-main-agent git:20260922.bede94fA

Immutable. This exact content never changes and is served at /api/v1/blob/b225503d30738640.

---
name: notifying-main-agent
description: Use when a dispatched agent routes a question, progress, or status to its main agent.
---

## Overview

Discuss work details and authorization directly with the user; the main agent accepts those decisions.
Ask it only for integrated context or a coordinator-owned action result.
Address every operation by your instruction path.

Live bodies carry one delta in at most two sentences.
Put detailed context or evidence in repeatable `--ref`; transport adds identity, intent, and correlation.

## Ask the main agent

From `awaiting-user-input` or `awaiting-authorization`, report `awaiting-main-agent`
with the coordinator action or fact you need before sending a question. The transport
enforces this order; progress notes alone preserve the user-owned checkpoint.

```bash
uv run --script "${CLAUDE_PLUGIN_ROOT}/scripts/send-dispatch-message.py" \
  --instruction-path <your exact instruction path> \
  --to main --intent question \
  --message "<one integration question; include expected reply shape>" \
  --ref "<source or artifact when needed>"
```

Continue independent work.
If the coordinator's answer becomes blocking, report `awaiting-main-agent`; a user-owned question remains `awaiting-user-input`.
`awaiting-main-agent` means a coordinator action or fact is required. Waiting on your own subagent, review, or CI is progress, recorded as a wait under [Report status](#report-status).

## Report status

At every checkpoint and terminal outcome, make exactly one call:

```bash
uv run --script "${CLAUDE_PLUGIN_ROOT}/scripts/report-task-status.py" \
  --instruction-path <your exact instruction path> \
  --status <done|failed|awaiting-authorization|awaiting-user-input|awaiting-main-agent> \
  --note "<outcome or exact unblock>" --ref "<proof when needed>"
```

The command persists status before notifying the recorded main-agent Herdr endpoint.
Delivery failure is surfaced and leaves durable state for watcher recovery.
A reply to an `awaiting-main-agent` checkpoint leaves `status` unchanged and only marks that checkpoint resolved; before stopping, report a fresh status here or record a wait, since the resolved one no longer counts.
To end a turn while your own CI watch, subagent, review, or scheduled wake will resume you, run `report-progress.py` with `--note "<current state>" --waiting-on "<what resumes you>"`; each wait note covers one stop.

## Report a feature-branch push

```bash
uv run --script "${CLAUDE_PLUGIN_ROOT}/scripts/send-dispatch-message.py" \
  --instruction-path <your exact instruction path> \
  --to main --intent inform \
  --message "Pushed <branch>; continuing." --ref "<MR/PR>"
```

If no live endpoint exists, record the same detail with `report-progress.py`.
Continue immediately.

**Complete when:** the intended message was delivered, or terminal status was persisted and its Herdr notification succeeded or visibly failed.