Responsive Agent Skill v1.8.0 — Two-Layer Async Architecture#

Origin: Based on session-coordinator v3, merged with async-command patterns.

---

Quick Reference#

Spawn Decision (binary — exec OR spawn, nothing else)#

text

Is it fast (<1s) AND local AND same topic AND no network I/O AND read-only?
  → YES: exec directly in main process, respond
  → NO:  spawn subagent immediately

yieldMs vs timeout (for subagent exec calls)#

Command durationyieldMsexec timeout< 5s, need sync resultnone (exec directly)105–30s500060> 30s, async ok10000300Unknown duration30000600

• yieldMs = wait-before-background threshold. If command exceeds yieldMs, it gets backgrounded automatically.
• timeout = hard kill after N seconds. Must be > yieldMs.
• To run sync: set timeout large, yieldMs = timeout (or omit yieldMs).
• To run async: set yieldMs small, timeout = estimated + buffer.

Subagent Error Strategy#

On exec failure: log → write workspace/tasks/{task-id}/error.md → reply to parent. No retry. Fail-fast.

---

Two-Layer Architecture#

text

┌─────────────────────────────────────────────────────────┐
│  Layer 1: MAIN PROCESS (never blocks)                   │
│  dialog + dispatch only — spawn everything else         │
└─────────────────────────────────────────────────────────┘
                         │
                    spawn ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 2: SUBAGENT (executes tasks)                     │
│  exec + yieldMs for long local commands                 │
└─────────────────────────────────────────────────────────┘

Rule: Main process never blocks. Subagent never hangs.

---

Core Principle#

Main process = dialog + dispatch. Never block.

The main goal is responsiveness — the main process must never be blocked, stalled, or made unresponsive. This is not "never execute." It is "never block."

A blocked main process shows as: typing indicator disappears, user cannot get a response, session appears frozen.

---

Resource Limits#

Max concurrent subagents per main process: 5

Tracking and Queueing#

• When user fires rapid requests: spawn a new subagent for each
• Track concurrent count internally
• If count > 5: reply "任务已加入队列，等前一个完成后自动开始" and queue the task

Nested Spawn — Subagent Spawning Subagent#

• The 5 concurrent subagent limit applies to top-level subagents only (direct children of the main process)
• Nested subagents (subagent's children) do not count toward the 5-slot limit
• Rationale: recursive task decomposition forms a DAG, not a tree — counting all levels would artificially limit deep task decomposition
• Warning: nested spawn should still be used sparingly — too many levels makes debugging hard

Queue Processing#

• Queue is FIFO (first in, first out)
• When a running subagent completes, start the next queued task
• Main process manages the queue — no user action needed

Queue Priority#

Detailed priority queue implementation:

• Main process maintains a queue dict with fields:
  • {label, task, priority: "high"|"normal", timestamp}
• On new spawn request:
  • If priority=high AND queue has no existing high-priority: insert at position 0, shift others back
  • If queue already has 1 high-priority: add after it (slot taken)
  • If priority=normal: add to end (FIFO)
• On subagent completion: start next in queue (high-priority first, then oldest normal)
• Reply to user: "已加入高优先级队列" or "已加入队列（第 N 位）"

Concurrent high-priority conflict: When two high-priority tasks arrive simultaneously:

1. Both are marked high-priority
2. They are ordered by arrival timestamp (first-come, first-served within priority)
3. The earlier one gets slot 1, the later one waits
4. Reply to second user: "已有1个高优先级任务在排队，已加入队列（第2位）"

• Queue insertion is atomic per arrival — no race condition
• If same timestamp (very rare): use lexicographic label order as tiebreaker

High-priority flag: If user says "紧急" or "priority":

• Mark task as high-priority
• Reply: "已加入高优先级队列"
• High-priority queue slot is limited: max 1 high-priority task ahead of normal queue at a time

Memory/CPU#

• Subagent inherits main process limits — no extra quotas needed for OpenClaw context
• OS-level resource management handles overall system load

---

When Is a Command "Long"? — Practical Thresholds#

Use this to decide whether to exec directly or spawn:

DurationTypeAction< 3s, known fastlocal read, simple computationexec directly in main process3–10slocal with uncertain loadexec with yieldMs=3000, timeout=15> 10s or unknownany remote, any build, any unknownspawn subagent

Rule: "When in doubt, spawn."

Specifically:

• Any remote operation (SSH, API call, HTTP) = long → spawn
• Any operation with uncertain duration = long → spawn
• Any state-modifying operation (write, commit, deploy) = long → spawn

Quick decision tree:

text

Is it < 3s AND local AND known-fast AND read-only?
  → YES: exec directly
  → NO:  spawn subagent

---

Decision Framework#

Layer 1 — Main Process Spawn Decision Tree (mechanical)#

When a request arrives at the main process, answer these questions in order:

text

Q1: Is it a FAST local read (<1s)?
    - No read I/O, no network, same topic, read-only?
    → YES: exec directly in main process, respond now
    → NO:  proceed to Q2

Q2: Is it ANY of the following?
    - Remote / network / SSH / HTTP
    - git push / pull / clone
    - Unknown duration
    - Different topic from current conversation
    - State-modifying (write, commit, deploy, publish)
    → YES: spawn subagent immediately
    → NO:  still spawn (conservative — when in doubt, spawn)

Binary rule: if you hesitated on any Q, spawn.

Context Passing ("Continue from Above")#

When user says "接着上面的" or "continue from above":

Implementation method:

1. Main process uses exec to read the previous task.md: text

   exec(command="cat workspace/tasks/{task-id}/task.md", timeout=5)
   
   

2. Alternative for quick lookup: memory_search on the task-id

3. Main process copies the relevant context into the new spawn task description

4. New subagent receives a complete task description including the prior context

Result: New subagent can continue from where it left off.

• The task.md file at workspace/tasks/{task-id}/task.md is the continuity mechanism
• Main process is responsible for maintaining context, not the subagent

Always spawn (never exec in main process):

• Remote operations (SSH, remote API calls, HTTP)
• git push/pull/clone
• Any network I/O
• Unknown duration
• Different topic from current conversation
• State-modifying operations (file write, git commit, package publish, deploy)
• Anything requiring waiting for external result

Main process never executes long commands. It only spawns.

Layer 2 — Subagent Execution Pattern#

Inside a subagent, use exec + yieldMs for commands that may take time:

json

// Short local command (<1s): exec directly, no yield needed
exec(command="ls /tmp")

// Long local command (5-30s): exec + yieldMs
exec(command="some-long-operation.sh", yieldMs=5000, timeout=60)

// Long command (>30s, async ok): exec + yieldMs
exec(command="moderate-build.sh", yieldMs=10000, timeout=300)

// Unknown duration: exec + yieldMs + large timeout
exec(command="unknown-task.sh", yieldMs=30000, timeout=600)

// Very long command: exec + background + poll
exec(command="very-long-build.sh", background=true, yieldMs=60000, timeout=3600)

yieldMs = how long to wait before backgrounding. If the command finishes within yieldMs, result is returned directly. If not, it is backgrounded and result arrives via push.

⚠️ yieldMs WARNING — Result Loss Risk#

If you need the result, yieldMs must be LARGER than estimated command duration.

ScenarioProblemCorrectyieldMs=5000, command takes 8sCommand bg'd BEFORE completing, result may be lostSet yieldMs >= 8000yieldMs=10000, command takes 45sCommand completes normally, result returned✅ correctyieldMs=5000, command takes 4sCommand completes normally, result returned✅ correct

Rule:

• Need the result? → yieldMs >= estimated_duration
• Fire-and-forget (don't need result)? → yieldMs can be small (5000–10000ms)

---

background=true vs yieldMs — What's the Difference?#

These are two different mechanisms for handling long commands. They are not the same.

yieldMs``background=trueWhat it doesWaits N ms before backgrounding, but process is still attached — result will eventually come back via pushTruly detaches the process — runs independently, no result returned unless you pollResult delivery✅ Result arrives via push when done❌ No automatic result — detachedUse whenYou need the result eventuallyYou explicitly need NO result (pure fire-and-forget)

If BOTH are set#

If you set both background=true AND yieldMs:

1. yieldMs takes precedence initially — the command waits up to yieldMs milliseconds before being backgrounded
2. After yieldMs elapses, background=true kicks in — the process is truly detached
3. Result will not come back via push (background=true overrides the attached behavior)

Decision Rule#

ScenarioUseNeed the resultyieldMs (set >= estimated duration)Explicitly need NO result (pure fire-and-forget)background=trueMost casesyieldMs (not background=true)json

// ✅ Need result — use yieldMs
// Inside subagent:
exec(command="analysis-script.sh", yieldMs=30000, timeout=120)

// ✅ Explicitly need NO result — use background=true
// Inside subagent:
exec(command="ping -c 100 remote-host", background=true)
// Result: none, process runs independently

Rule of thumb: Default to yieldMs. Use background=true only when you explicitly need the process to be truly detached with no result expected.

---

yieldMs and exec timeout — Complete Reference#

The relationship#

• yieldMs: wait time before backgrounding. If command takes longer than yieldMs, it goes to background automatically.
• timeout: hard kill after N seconds. Command is killed if it exceeds this.
• Rule: yieldMs < timeout always. yieldMs is the backgrounding threshold; timeout is the hard limit.

When to use each#

Command durationyieldMstimeoutStrategy< 5s, sync result needednone (exec directly)10No yieldMs needed — exec direct5–30s500060yieldMs = wait-before-bg, timeout = hard limit> 30s, async ok10000300yieldMs small → bg quickly, timeout allows completionUnknown duration30000600Conservative — bg after 30s, kill at 10minVery long (>10min)100003600yieldMs=10s for responsiveness, long timeout for completion

Sync vs async decisions#

Want result synchronously (wait in subagent until done)?

• Set yieldMs = timeout (or omit yieldMs, use timeout only)
• Example: exec("short-task.sh", timeout=30) — waits up to 30s, returns result

Async is fine (background immediately)?

• Set yieldMs small (e.g., 5000–10000ms)
• Example: exec("long-task.sh", yieldMs=5000, timeout=300) — bg after 5s, result via push

---

Subagent Error Strategy#

When an exec call fails inside a subagent:

1. Log the error — capture stdout, stderr, exit code
2. Create directory — mkdir -p workspace/tasks/{task-id} (subagent's responsibility)
3. Write error file — workspace/tasks/{task-id}/error.md
4. Reply to parent — always report back to main process, even on failure

Error file format ( workspace/tasks/{task-id}/error.md):

markdown

# Subagent Error Report

- Task: [task description]
- Timestamp: [ISO timestamp]
- Exit code: [N or "signal"]
- Command: [what was run]

## stdout
[output]

## stderr
[error output]

## Analysis
[brief root cause if known]

Key principles:

• No automatic retry (fail-fast per ClawFlow principle)
• Subagent never silently dies — always replies to parent
• Main process decides whether to respawn or report failure to user

error.md cleanup strategy:

• error.md files are persistent audit trail — do NOT auto-delete
• They serve as historical record of what went wrong
• Trigger: during weekly memory maintenance (HEARTBEAT.md check)
• Who: main process runs the scan during HEARTBEAT
• Script:
  1. Scan workspace/tasks/*/error.md
  2. If file age > 30 days AND task is resolved: move to workspace/tasks/archive/{year}/{task-id}/error.md
  3. If total tasks/ directory > 1GB: report to user "tasks/ 目录超过 1GB，建议手动清理"
• This is NOT automatic deletion — archive only, never delete

Directory creation: Before writing any files (error.md or temp results), the subagent must create the directory:

bash

mkdir -p workspace/tasks/{task-id}   # for error files
mkdir -p workspace/temp/{task-id}    # for large results

This is the subagent's responsibility, not the main process's.

---

Subagent Reply to Parent#

When a subagent completes (success or failure), it must reply to its parent session — it does not use sessions_yield. The subagent session key is known at spawn time; use it to send the final result directly.

Result format: brief summary of what was done, file paths if any (not raw large data).

json

// Subagent sends result back to parent via message tool (channel send)
message(action="send", target="{parent_session_key}", message="Task complete. Files written: workspace/temp/{task-id}/result.txt")
// Subagent then terminates normally — no sessions_yield needed

When to reply:

• Always — success, failure, or error. Parent must hear back.
• Keep the message brief. If large data was produced, reply with the file path, not the raw content.

Key point: Subagent does NOT use sessions_yield — it terminates normally after sending the result via sessions_send.

Spawn Failure Fallback#

If spawning a subagent fails (system error):

1. Reply to user: "系统繁忙，请稍后再试"
2. Log the failure: create dir mkdir -p workspace/mailbox/errors/ then write to workspace/mailbox/errors/{timestamp}-spawn-fail.md
3. Do NOT retry within the same session (fail-fast to prevent loop)

Error log format:

markdown

# Spawn Failure Report
- Timestamp: [ISO timestamp]
- Task: [task description]
- Reason: [system error message if known]

---

Spawn Mode v3 — Default: session thread#

Default spawn mode is mode="session" with thread=true.

thread=true vs thread=false vs mode="run"#

ModethreadBehaviorUse Whenmode="session"``thread=truePersistent conversation — context is preserved across messages, multi-turn dialog possibleMulti-step tasks, tasks where user may ask follow-up questions, uncertain scopemode="session"``thread=falseNew session each time — context is NOT preserved, each spawn starts fresh. Subagent sends ONE final result push when done, then the session is closed. Cannot receive additional messages in the same thread.Fire-and-forget tasks with bounded scope, no follow-up expectedmode="run"N/ADetached, no session — truly fire-and-forget, no result pushRare; avoid unless you explicitly need detached executionmode="one-shot"N/ADoes not exist in OpenClaw. Was considered but removed.Use mode="session" + thread=false for bounded fire-and-forget.

Both thread=true and thread=false receive the result via push mechanism. The difference is whether the session stays open afterward:

• thread=false: session created but closed after final result push — one-shot, no follow-up
• thread=true: session stays alive, can receive multiple messages across turns

Decision Guide#

"Is this a multi-step task or does the user expect follow-up?"

• YES → mode="session" + thread=true
• NO, just do this one thing → mode="session" + thread=false (fire-and-forget)
• NO, but I explicitly need detached → mode="run"

json

// ✅ Multi-step task — context preserved, user may ask follow-up
sessions_spawn(task="debug service issue, may need to run multiple commands",
               runtime="medium", label="service-debug")

// ✅ Fire-and-forget — bounded scope, no follow-up expected
sessions_spawn(task="restart the backup service on remote node",
               runtime="fast", label="backup-restart")

// ⚠️ Run mode — only when you explicitly need detached, no result push
sessions_spawn(task="background health check", runtime="fast", label="health-bg", mode="run")

Note: thread=false still creates a session (unlike mode="run"), so you get result push — but the subagent starts with a fresh context, no history from previous related spawns.

• Use mode="session", thread=true for most tasks (interactive, multi-step, or uncertain duration)
• Use mode="session", thread=false for fire-and-forget tasks with bounded scope
• Avoid mode="run" unless you explicitly need detached/no-result (it provides no result push)

json

// ✅ Default: session thread (most tasks)
sessions_spawn(task="task-description", runtime="medium", label="task-label")

// ✅ Fire-and-forget: bounded scope, fresh context each time
sessions_spawn(task="task-description", runtime="fast", label="task-label")

// ⚠️ Avoid: run mode provides no result push — use only when detached is explicitly needed
sessions_spawn(task="task-description", runtime="fast", label="task-label", mode="run")

---

Timeout Guidelines#

runtime vs exec timeout — Clarification#

• runtime (fast/medium/long) and exec timeout are independent
• runtime = spawn-level timeout — how long the entire subagent session is allowed to run
• exec timeout = command-level timeout — how long a specific exec call waits
• If runtime=medium (15min) but exec timeout=3600s:
  • The exec will be killed if it runs longer than 3600s
  • The subagent itself will be killed if ALL its work exceeds 15min
  • They don't conflict — runtime is the outer limit, exec timeout is inner protection
• Rule: exec timeout should always be <= runtime, otherwise exec will be killed by runtime first
• runtime=fast (5min) + large exec timeout (3600s): exec will be killed when the subagent's runtime timeout fires at 5 minutes, regardless of exec timeout. The outer runtime limit always wins. To avoid confusion: set exec timeout significantly smaller than runtime (e.g., runtime=fast, exec timeout=60–300)

runtime Tiers#

Use these as a guide to set runtime when spawning:

TierDurationExamplesfast~5 minfile ops, single API call, config check, quick testmedium~15 mingit operations, moderate build, moderate data processinglong60 min+large clones, heavy builds, multi-step deployments, data migrationjson

// Fast task — 5 min timeout
sessions_spawn(task="check service status", runtime="fast", label="service-status-check")

// Medium task — 15 min timeout
sessions_spawn(task="clone repository and run tests", runtime="medium", label="repo-test")

// Long task — 60 min timeout
sessions_spawn(task="full deployment pipeline", runtime="long", label="deploy-pipeline")

---

Spawn Label Convention#

When spawning a subagent, always include a descriptive label parameter:

• Use dashes, not spaces (e.g., project-config-sync not project config sync)
• Use generic, descriptive names only — never specific project names, IPs, hostnames, or user names
• Label should reflect the actual task category or action
• Rule: Does this label reveal anything about the user's private data? If yes, change it.

Label Examples#

GOOD labels (functional, generic):

python

label="config-sync"           # what it does, not which project
label="log-review"             # functional category
label="deploy-check"           # what it checks, not which environment
label="service-health"         # generic health check
label="backup-status"         # generic backup check
label="build-verify"           # what it verifies

BAD labels (specific identifiers, reveal private data):

python

label="192.168.1.1"             # ❌ specific IP — privacy leak
label="ken-task"               # ❌ specific user name — privacy leak
label="fix-123"                # ❌ specific bug number — reveals internal tracking
label="proj-zeta"              # ❌ specific project codename
label="john-doe-deploy"        # ❌ specific person + action
label="acme-corp-sync"         # ❌ specific company name

Generic placeholder rewrites:

• 192.168.x.x → remote-host or node-alpha
• user@host → admin-user or service-account
• project-name → repo-name or project-alpha
• bug-123 → bugfix-verify or issue-check

json

// ✅ Good: generic, dashes, descriptive
sessions_spawn(task="sync config to remote node", label="config-sync")
sessions_spawn(task="run test suite for module", label="test-suite")
sessions_spawn(task="deploy service to environment", label="service-deploy")

// ❌ Bad: spaces, specific names, cryptic
sessions_spawn(task="...", label="proj1")           // too short, no dashes
sessions_spawn(task="...", label="192-168-1-1")     // specific IP — not allowed
sessions_spawn(task="...", label="johns-task")      // specific user name — not allowed
sessions_spawn(task="...", label="foo-bar-v2")      // specific project codename — not allowed

When the user says "stop that thing", look at subagents list and match the label to find the right subagent to stop.

---

Parallel Subagent Pattern#

When a task requires multiple independent subagents running simultaneously:

1. Main process spawns all subagents at once (they run in parallel)
2. Each subagent runs independently, sends result to parent via sessions_send
3. Main process collects results as they arrive (push-based)
4. When all results are in, main process synthesizes and replies to user

Data sharing: each subagent writes its result to its own subdirectory workspace/tasks/{parent-task-id}/{subagent-label}/result.txt

Result gathering: results are collected after ALL subagents complete (not streaming). Main process reads all result files and synthesizes.

This is fan-out pattern, not DAG dependency pattern — all subagents are independent and start at the same time.

Parallel Completion Detection (Join/Barrier Mechanism)#

Main process needs a way to know when ALL parallel subagents are done:

Mechanism: counter-based tracking

• Main process maintains a counter: remaining = N (number of parallel subagents)
• Each subagent result arrival via push decrements counter
• When remaining == 0: all done, synthesize and report to user

Implementation:

• Main process tracks results in a dict keyed by subagent label
• Each push event: check if all results received, if yes → synthesize

Example:

text

parallel subtasks: [agent-a, agent-b, agent-c]
remaining = 3
→ agent-a pushes result: remaining = 2
→ agent-c pushes result: remaining = 1
→ agent-b pushes result: remaining = 0 → all done, synthesize

Concurrent Write Warning#

⚠️ Warning: multiple subagents writing to the same parent directory is safe IF they write to DIFFERENT subdirectories (each subagent has its own {subagent-id}/).

Rule: each subagent writes ONLY to its own workspace/tasks/{parent-task-id}/{subagent-label}/

• Subdirectory is created per subagent, no shared files
• If two subagents try to write the same file: this is an error — use unique subdirectory names

Parallel Subagent Labels#

Use a common prefix for parallel subagent labels so they can be cancelled together:

json

// Good: prefix-based naming for parallel tasks
sessions_spawn(task="check weather for location", runtime="fast", label="parallel-check-1")
sessions_spawn(task="check email inbox for urgent messages", runtime="fast", label="parallel-check-2")
sessions_spawn(task="check calendar for upcoming events", runtime="fast", label="parallel-check-3")

json

// Example: user asks "check weather + email + calendar"
// Main process spawns 3 subagents in parallel:
sessions_spawn(task="check weather for location", runtime="fast", label="parallel-check-1")
sessions_spawn(task="check email inbox for urgent messages", runtime="fast", label="parallel-check-2")
sessions_spawn(task="check calendar for upcoming events", runtime="fast", label="parallel-check-3")

// Each subagent writes its result to:
// workspace/temp/{task-id}/parallel-check-1.txt
// workspace/temp/{task-id}/parallel-check-2.txt
// workspace/temp/{task-id}/parallel-check-3.txt

// Main process waits for all 3 results, then synthesizes and replies

Parallel Subagent Failure Handling#

Rule: partial results are better than no results — never waste succeeded work.

If one or more parallel subagents fail:

1. Mark as failed — the failed subagent writes its error to workspace/tasks/{task-id}/error.md and replies to parent
2. Continue waiting — do NOT cancel remaining subagents when one fails; wait for all to complete
3. Synthesize partial results — after all done, main process reads available result files and synthesizes
4. Report to user — "[X] failed, [Y] succeeded. Partial results: ..." with whatever succeeded
5. If ALL failed — report total failure with error summary from all failed subagents

Example:

text

User: check weather + email + calendar
→ 3 subagents spawned (parallel-check-1, parallel-check-2, parallel-check-3)
→ parallel-check-1 (weather): succeeded → weather-check.txt
→ parallel-check-2 (email): failed → error.md written, reply sent
→ parallel-check-3 (calendar): succeeded → calendar-check.txt

Main process synthesizes: 1 failed, 2 succeeded.
Reply: "2/3 succeeded. Weather: sunny, 22°C. Calendar: meeting at 3pm. Email check failed — see error log."

---

Large Results#

If subagent produces > 1MB of data, write to file instead of returning raw:

1. Write result to: workspace/temp/{task-id}/result.txt
2. Reply to parent: pass the file path (not the raw content)
3. Main process: reads the file path and reports to user

Example:

json

// Large output scenario
exec(command="git diff --name-only", yieldMs=10000, timeout=60)
// Result: 50MB of file names → write to file instead

// Correct approach:
// 1. subagent writes to workspace/temp/{task-id}/result.txt
// 2. subagent replies with file path
// 3. main process reads path, reports to user

Cleanup: temp files are ephemeral — OS handles cleanup on reboot. No manual cleanup needed.

---

Subagent Lifecycle#

Normal duration: seconds to minutes depending on task complexity.

Duration Guidelines#

Task TypeExpected DurationActionFast local reads< 1sexec direct in mainSimple operationssecondssubagentMulti-step tasksminutessubagentBuild/clone/deployminutes to hourssubagent with appropriate timeout

Long-Running Subagent Monitoring#

• Subagent running > 10 minutes without update: check status via subagents list
• No automatic kill — let it finish unless user cancels
• If subagent appears stalled after > 10min without result, report to user

Subagent Completion#

• Subagent completion: auto-replies to parent when done (via push mechanism)
• Parent receives result and reports to user
• No polling needed — completion is push-based

Long Task Progress Reporting#

• For very long tasks (>5 min), subagent can optionally send interim progress to parent
• Progress format: brief message like "Step 2/5 complete, moving to step 3"
• Subagent sends progress via sessions_send to parent (same as final result, just multiple pushes)
• Main process relays progress to user if user asks "how's it going?"
• Rule: do NOT proactively push progress to user — only send to parent, relay on demand
• This adds complexity, only implement if the task explicitly supports it

---

Lifecycle Management#

Auto-Timeout#

• Subagents run with a defined runtime timeout (fast/medium/long)
• If the subagent exceeds its timeout without a result, it is considered stalled
• Do NOT manually extend timeouts unless user explicitly asks

Done Signals#

A subagent can be safely let timeout (or can terminate early) when:

1. user says "done" — user has indicated the task is complete or no longer needed
2. Context switches — user has moved to a different topic or task; the previous subagent is no longer relevant
3. Explicit cancel — user says "stop", "cancel", "forget it"

What to do when done signal fires:#

• Do NOT try to salvage a timed-out subagent
• Do NOT restart the same task unless user explicitly asks
• Acknowledge the signal and move on

---

Memory Updates#

After subagent completes: if the task resulted in a decision, config change, or state change, update MEMORY.md.

When to Update MEMORY.md#

Result TypeUpdate MEMORY.md?ExampleTrivial/ephemeral❌ No"checked service status", "file exists"Decision made✅ Yes"decided to use strategy X over Y because..."Config changed✅ Yes"updated timeout from 30s to 60s"State change✅ Yes"moved from manual to automated backup"Lesson learned✅ Yes"found that approach A fails in scenario X"Important output✅ Yes"discovered key info about..."

Update Format#

markdown

## [Date] Task Result
- Task: [brief description]
- Outcome: [what happened]
- Key decision/learning: [why this matters]

Main process handles MEMORY.md writes — subagent reports the result, main process decides whether to write it down.

---

Result Writing#

Daily logs → memory/YYYY-MM-DD.md#

Routine subagent work should be logged in the daily memory file:

bash

# Create/update daily log
memory/2026-04-06.md

Include: task label, what was done, key result. Keep it concise.

---

Spawn Is Transparent#

Do not announce to user when you are spawning a subagent.

• Do NOT say "I'm spawning a subagent to handle this..."
• Do NOT say "Let me dispatch this to a background agent..."
• Just spawn it and continue the dialog naturally

User does not need to know the execution architecture. The subagent handles the work; you handle the conversation.

---

Role Definition#

ResponsibilityMain ProcessSubagentUser dialog✅❌Task dispatch✅❌Result production❌✅Result delivery to user✅❌Decision making✅❌Status coordination✅❌Fast local operations (<1s)✅❌Blocking / remote / long operations❌✅exec + yieldMs for long local commands❌✅

---

Execution Model#

Blocked = Wrong#

If the main process blocks, the pattern has failed — regardless of whether the task eventually completes.

Two-Layer Flow#

json

// Layer 1: Main process — always spawn for non-trivial work
// ❌ Wrong — blocks main process, typing disappears
exec(command="ssh remote-host ...")

// ✅ Correct — non-blocking, typing stays active
sessions_spawn(task="remote operation description", runtime="medium", label="remote-task")

// Inside the spawned subagent (Layer 2):
// ✅ exec + yieldMs for long local command
exec(command="some-long-local-script.sh", yieldMs=10000, timeout=300)

// ✅ exec + background for very long commands
exec(command="very-long-build.sh", background=true, yieldMs=60000, timeout=3600)

After spawning: continue dialog with user. Do NOT wait. Results arrive via push event.

Fire-and-Forget#

• Spawn with full task description and runtime estimate
• Do NOT estimate how long it takes
• Do NOT poll for status
• Continue dialog
• Report result when delivered

---

Multi-Node Coordination#

Each node runs its own subagents. Nodes do not delegate to each other's subagents. Coordination between nodes goes through whatever inter-node protocol is configured for that setup.

---

User Cancellation Protocol#

When the user says "停" / "stop" / "取消":

1. Check subagents list — find all active subagents

2. Match label — if parallel subagents share a common prefix (e.g., parallel-check-1, parallel-check-2, parallel-check-3), match by prefix to catch ALL of them

3. Send SIGTERM — graceful termination to all matched subagents (max 5 seconds)

4. Wait up to 5 seconds — if still running, send SIGKILL (hard kill)

5. Reply to user — "已停止全部 {n} 个并行子任务" (for parallel) or "已停止 {label}" (for single)

6. Log cancellation — write to workspace: markdown

   # Subagent Cancellation Log
   

• Label: {label}
• Cancelled by: user
• Timestamp: {ISO timestamp}
• Result: SIGTERM → SIGKILL (or SIGTERM only if clean exit)

**Example flow (single subagent):**

text

User: 停！ Agent: (subagents list) → finds label="config-sync" (kill config-sync subagent) "已停止 config-sync"

**Example flow (parallel subagents):**

text

User: 停！ Agent: (subagents list) → finds parallel-check-1, parallel-check-2, parallel-check-3 (kill all 3 subagents with prefix "parallel-check") "已停止全部 3 个并行子任务"

**Do NOT return partial results when user cancels** — assume clean stop is wanted.

**Rule:** Always reply confirming which subagent was stopped. Never silently ignore a cancellation request.

### Done Signals (Graceful Termination)

SignalMeaningBehavior**SIGTERM**Graceful terminationFinish current step, then exit (max 5 seconds)**SIGKILL**Forced terminationExit immediately, no cleanup

**When to use SIGKILL:** Only when user explicitly says "强制停止" or "kill" (kill, not stop/cancel).

* * *

## Real-World Templates

### Template: ClawHub Rate-Limit Wait

When ClawHub returns 429 Too Many Requests:

json

```json
sessions_spawn(
  task="Install or publish skill to ClawHub, handling rate limits. If 429 received, wait Retry-After seconds then retry. Max 3 attempts.",
  label="clawhub-ops"
)

Inside the subagent:

1. First attempt: run clawhub command
2. If 429: extract Retry-After header (e.g., 60 seconds)
3. exec(command="sleep {Retry-After}", yieldMs={Retry-After * 1000 + 1000}, timeout={Retry-After + 10})
4. Second attempt: retry the clawhub command
5. If still 429 after 3 attempts: write error.md, reply to parent with failure

Template: GitHub Rate-Limit Wait#

When GitHub API returns 403 with "rate limit exceeded":

json

sessions_spawn(
  task="GitHub API operation, handle rate limits. If 403 received, wait suggested reset time then retry. Max 3 attempts.",
  label="github-ops"
)

Inside the subagent:

1. Check for X-RateLimit-Reset header
2. Calculate wait time: (reset_timestamp - now) + 5 seconds buffer
3. exec(command="sleep {wait_seconds}", yieldMs={wait_seconds * 1000 + 1000}, timeout={wait_seconds + 30})
4. Retry with Authorization header using token from TOOLS.md

---

Anti-Patterns#

Anti-PatternWhy WrongCorrectexec long command in main processBlocks typingMain process spawns; subagent uses exec+yieldMs"Let me check..." + exec in mainBlocks typingSpawn subagentWaiting for subagent result before respondingBlocks dialogContinue, report laterDirect remote operations in main processBlocksSpawn subagentSpawning to avoid doing work (not to avoid blocking)Misuse of patternFast ops = direct in main processAll work spawn, nothing directOver-interpretationFast local ops = direct exec in mainAnnouncing the spawn to userNoise, breaks flowSpawn silently, continueSubagent uses blocking exec without yieldMsSubagent hangsSubagent uses exec+yieldMsUsing specific IPs/hostnames in labelsPrivacy leakUse generic namesyieldMs >= timeoutBackground threshold >= hard kill — illogicalyieldMs must always be < timeoutSubagent silently failing without reportingParent never knowsAlways reply to parent, write error.mdUsing thread=false when multi-step neededLoses context mid-task, user follow-up failsUse thread=true for multi-step or uncertain scopeUsing thread=true for fire-and-forgetWastes context window on single-use taskUse thread=false for bounded fire-and-forget tasksmode="one-shot" (deprecated)Not a valid mode — anti-pattern residueUse mode="run" for detached or mode="session" with thread=false for fire-and-forgetUser says "stop" but nothing happensSubagent keeps runningImplement cancellation protocol: list → match label → SIGTERM → SIGKILL → replySubagent cancelled but no reply to userUser doesn't know it stoppedAlways reply confirming which subagent was stopped

---

Workflow Summary#

text

User request arrives
        │
        ▼
┌───────────────────────────────────┐
│ LAYER 1: MAIN PROCESS             │
│ Q1: fast + local + same topic?    │
│   YES → exec direct, respond      │
│ Q2: any spawn condition met?      │
│   YES → spawn subagent, continue  │
└───────────────────────────────────┘
        │
   spawn ↓
┌───────────────────────────────────┐
│ LAYER 2: SUBAGENT                 │
│ exec + yieldMs for long commands  │
│ background for very long          │
│ On error: log + error.md + reply  │
│ Return result via push            │
└───────────────────────────────────┘
        │
        ▼
Result arrives at main process
Report to user
If significant → write to MEMORY.md

---

Key Insight#

"Never block" is the rule. "Never execute" is a misreading of the rule — fast operations should be direct in the main process because they do not block.

The two-layer architecture makes this clean:

• Main process: dispatches everything, blocks nothing
• Subagent: executes with exec+yieldMs, never hangs without yield

The typing indicator is the visible signal: if it disappears, something is blocking.

---

Privacy Notes#

All examples in this skill use generic placeholders only. No specific project names, IPs, hostnames, user names, service names, or AI names appear in any example. This protects both operational security and privacy.