netwatch

name	netwatch
description	Use when the user says "netwatch" or asks to measure network stats (ping latency, packet loss, interface throughput) in the background. Launches a background subagent via the `task` tool that runs ~20s of measurements, then returns control immediately so the user can keep talking. Demonstrates background subagent invocation in opencode.

Netwatch (demo) — background subagent invocation

Demonstrates invoking a subagent in the background with opencode's task tool: hand a long-running measurement to a separate agent context that runs for ~20 seconds, while the main agent stays responsive so the user can keep chatting. When the subagent finishes, its result arrives as a notification and you relay the summary.

This is different from skills that compose other skills in the same conversation. Here the main agent spawns a subagent — its own context and tool loop — and does not block on it.

What to do

1. Launch a background subagent with the task tool. Call it in a single message, on its own, so the harness can start it and return control to you immediately. Use:

   • description: "measure network stats"
   • subagent_type: "general"
   • prompt: the task block below (verbatim).

   Do not chain any other tool call after it in the same message that depends on its result — you must let the turn end so control returns to the user.

   Task prompt to hand the subagent:

   Measure local network stats for about 20 seconds, then report a concise summary. Use only safe, read-only commands. Steps:

   1. Find the primary interface with ip route get 1.1.1.1 (or ip -o link). Take a baseline of its RX/TX byte counters with ip -s link show <iface> and note the current time.
   2. Run ping -c 20 -i 1 -W 2 1.1.1.1 to measure latency and packet loss (this takes ~20s). If 1.1.1.1 is unreachable, retry once with 8.8.8.8.
   3. Run ip -s link show <iface> again; compute RX/TX bytes-per-second over the elapsed interval.
   4. Report a short table: interface, min/avg/max RTT (ms), packet loss %, and RX/TX throughput (KB/s). Note if there was no connectivity.

   Return only the final summary in your reply — not the raw ping/counter output.

2. Immediately tell the user, in one or two lines, that the network measurement is now running in the background (~20s) and they can keep talking meanwhile. Then end your turn — do not block waiting for the subagent.

3. When the subagent completes, you will be notified with its result. Relay the network summary to the user (a short table or a few lines).

Why this is a background subagent

Three things make this a background subagent, not a blocking call:

1. Separate context. The subagent has its own conversation/tool loop; the 20s of ping output and ip -s link counter parsing never enter the main transcript — only the final summary comes back.
2. Non-blocking. The main agent launches it and ends its turn instead of waiting, so the user keeps control.
3. Async result. When the subagent completes, opencode notifies the main agent, which then relays the summary. You do not poll.

The teaching point: a long/heavy task lives in a separate agent context, the main conversation stays free, and the result comes back asynchronously — fire-and-continue, not fire-and-wait.