lingyu9495-source/agent-responsiveness-delegation

Main Agent Only Orchestrates · Heavy Tasks All Delegated to Sub-Agents · Always Responsive

Problem: You assign a heavy task to an AI assistant, and then it doesn't reply to your messages, you can only queue to interrupt, and you wait over ten minutes for a single response. Root cause: The model isn't slow—the main agent runs the heavy task in the foreground, locking up the entire turn—your messages just queue behind it. Solution: Turn "delegate heavy tasks + always respond" into a hard rule written into the Agent's instructions, and use scripts to idempotently apply it to your machine.

Platform-independent: The rules block itself is platform-agnostic and works with any AI Agent that supports instruction files / system prompts / sub-agents (Claude Code / Codex / Cursor / WorkBuddy / Hermes / other similar platforms). The provisioner only writes directly to two tested locations; for other platforms, it generates a paste-ready rules block—no guessing config paths or fabricating fields.

---

When to Use

• Users complain "waiting too long / interruption freezes / no one answers / I need to chat with you often";
• You want to institutionalize "delegate heavy tasks to sub-agents, main agent always responsive" on one or more local Agent instances;
• You want to install this mechanism on an instance (via scripts/provision_agent_responsiveness.py) and verify it's truly active (via scripts/audit_agent_responsiveness.py).

---

Root Cause

The main agent runs heavy tasks (batch scraping, multi-file processing, long scripts) in the foreground → the entire reply turn is locked up:

• During a foreground long command, user messages can only queue;
• On some platforms, when sub-agents are running, user interruptions are downgraded to "queued" and only read after the full turn ends;
• So the user experiences "this assistant ignores me"—when it's actually just busy working.

Conclusion: To let people reach the assistant anytime, the assistant must not do heavy work itself, and when it is busy, retain an immediate interruption channel. These two things must be done together.

---

Three Things to Do Together (All Essential)

1. Write the Rules Block into the Agent's Instruction Layer (Pinned)

Full rules block in templates/agent-ops-rules.md (used by the script). Core six rules:

• Four-level triage (assess level before acting): L0 Q&A → answer directly, no delegation｜L1 single-step quick task (≤1 tool and ≤20 seconds) → do directly｜L2 multi-step/long task/batch/network → always delegate｜L3 requires user approval → first reply "This needs your decision on X".
• After delegation, immediately reply and end the turn (no waiting; waiting = didn't delegate).
• Commands exceeding 60 seconds go to background (foreground long commands lock the entire turn).
• Sub-agents only return conclusions + artifact paths; integration analysis is done by the main agent.
• User interruption as highest priority: acknowledge immediately, answer if possible, never leave the user waiting.
• Tasks needing questions/approval stay with the main agent (sub-agents can't ask people).

The rules block is wrapped with <!-- agent-ops-rules:v1 --> … <!-- /agent-ops-rules -->. The provisioner uses these markers for idempotent operation: repeated runs only replace the marked block, leaving your other content untouched.

2. Retain an Immediate Interruption Channel (Platform-Dependent)

Different platforms have different semantics for "user interrupts busy AI", with vastly different results:

Interruption Semantics	Actual Experience	Satisfies "Always Responsive"?
Read only after full turn ends	User waits idly	❌
Attached to "last tool result", delivered only after current batch of tools finishes	When main agent runs foreground long command, stuck until command exits	❌ (Fails for long-command scenarios)
Immediately interrupts current generation/request, injects user message as new input, and completed work is preserved	Interruption almost instant	✅

Criterion (one sentence): To enable "interrupt anytime", you must choose the semantics of "immediately interrupt + preserve completed work"; and combine it with the "long commands go to background" rule—both together make it work. (Hermes key names and test details in references/hermes-implementation.md; for other platforms, find equivalent semantics in your platform's settings.)

3. Sufficient Sub-Agent Concurrency (Otherwise "Delegate All" Gets Stuck by Slot Limits)

"Always delegate heavy tasks" requires being able to send out several simultaneously. If concurrency is too low, delegation becomes queuing—the user still waits.

• Set concurrency ceiling to an acceptable level (common 3–6); consequences of exceeding ceiling vary by platform (some reject entire batch, some truncate), so batch delegation is safer than hitting the ceiling.
• Concurrency directly affects cost: each sub-agent is billed independently; set as needed, don't blindly max out.

4. After Changes, Force Agent to Reload Instructions

Instruction files / system prompts are typically read once at process startup. Not restarting after writing = not effective:

• Restart the corresponding Agent process / gateway / session (per your platform);
• Verify after restart: ask the Agent to recite the rule—if it can, the instructions were actually loaded (not "I think it read them").

---

One-Click Provisioning / Audit

# ① Dry-run (default behavior, no files written): preview which files will be affected
python3 scripts/provision_agent_responsiveness.py

# ② Apply changes (auto-backup + idempotent; exports paste-ready block if platform not detected)
python3 scripts/provision_agent_responsiveness.py --apply

# ③ Force export paste-ready rules block (for Codex / Cursor / WorkBuddy / unknown platforms)
python3 scripts/provision_agent_responsiveness.py --apply --export --out ./agent-ops-rules.md

# ④ Audit: check if rules block exists / is pinned / matches current template
python3 scripts/audit_agent_responsiveness.py

Provisioner Behavior Conventions (hardcoded, verifiable):

Convention	Description
Default dry-run	No --apply, never writes to disk
Auto-backup	Generates <filename>.bak-agent-ops-<timestamp> before writing
Idempotent	If markers exist, compare content: match → skip; mismatch → replace only marked block
No overwriting user content	Insert only at file top (skip YAML frontmatter), never delete your original text
No guessing paths	Write only to two tested locations (Hermes SOUL.md, Claude Code ~/.claude/CLAUDE.md); for other platforms, export paste block
Pure standard library	Uses only argparse / pathlib / json etc., Windows / macOS / Linux compatible

Audit Script Behavior Conventions: Checks facts verifiable at the file level (exists / marked / pinned / content up-to-date); when no supported platform is detected, outputs "No supported platforms detected" truthfully and returns exit code 2—never falsely reports success.

---

Platform Adaptation Layer (Tool Name Mapping Table)

Abstract Action	Hermes (Tested)	Claude Code	Cursor / Codex / WorkBuddy	Other Similar Platforms
Rules block location	<HERMES_HOME>/SOUL.md (and <HERMES_HOME>/profiles/<p>/SOUL.md)	~/.claude/CLAUDE.md	Per your platform's global instructions / system prompt location	Export agent-ops-rules.md, then paste into system prompt
Delegate sub-agent	delegate_task	Task / sub-agent tool (map per your platform)	Per your platform's sub-agent / task tool mapping	Per your platform's sub-agent / task tool mapping
Long command to background	Background execution + completion notification	Background task / async mode of command tool	Per your platform's background execution method	System background process + log to disk

Honest boundary: Hermes column keys and semantics from local tests; Claude Code ~/.claude/CLAUDE.md is a tested path. Cursor / Codex / WorkBuddy tool names may change per version; this skill does not fabricate commands or field names—please map per the table above. For a more complete cross-platform delegation discipline, see the same author's subagent-first skill.

---

Pitfalls (Cross-Platform)

1. Instruction files are read only at process startup: Changing without restarting (or restarting the wrong instance) = no effect. Don't use "it's written in the file" as evidence of effectiveness.
2. Wrong interruption semantics: Choosing semantics like "delivered after this batch of tools finishes", combined with "main agent runs foreground long commands", results in the user feeling ignored. Must choose "immediately interrupt + preserve completed work".
3. Environment variables may override config files: Many platforms prioritize env over config. After changes, confirm actual active source, don't just look at config files.
4. Fake restart: Only terminating the wrapper process / scheduled task instance, while the real child processes still run old config. Verify by checking process start time, not process count.
5. Concurrency ceiling not verified: Assuming "all can be delegated", while exceeding ceiling causes whole batch rejection or truncation → delegate in batches, and verify the current effective ceiling value.
6. Only installed in one place: Multi-instance / multi-profile instruction files and skill directories are independent; write to each separately (provisioner traverses Hermes profiles; for other platforms, install per instance).
7. Don't disable the main agent's heavy tools to force delegation: On most platforms, sub-agents' toolset is a subset of the main agent (can't have tools the main agent lacks); disabling them cripples yourself.
8. False success: Audit script checking only "does the file contain these words" can easily report success when content is outdated or overwritten by later changes. Verify content matches current template; if not detected, truthfully say "No supported platforms detected".

---

Acceptance Checklist (Answer "Is it really working?" with this)

A. File Level (Script-Auditable)

• Rules block target file exists and agent-ops-rules:v1 marker is grep-able;
• Rules block is pinned (in top 1/3 of file);
• Rules block content matches current template (not an old residual);
• Repeated runs of provisioner: produce no second copy, don't overwrite existing content;
• audit_agent_responsiveness.py all green (exit code 0); exit code 2 + clear message when platform not detected.

B. Runtime (Manual Verification)

• After restart, ask the Agent to recite this rule → if it can, instructions were actually loaded;
• Give the Agent a heavy task → it immediately replies "Delegated (who is doing what)", not working silently for minutes;
• User interrupts during heavy task → immediately receives acknowledgment, and reply is not broken;
• After heavy task completes: output can be re-read and verified by main agent (not just "self-reported complete").

C. Boundaries

• During user interruption, running sub-agents are not cascadingly canceled (or any canceled ones are explicitly accounted for);
• Tasks needing user approval are not delegated to sub-agents.

---

License

MIT License. Free for personal and commercial use with author attribution.

---

🙋 About the Author

九品锦锂e | Encapsulates hard-won lessons into "ready-to-run" skills, not textbooks. This skill is the version I use daily.

WeChat: ly5419495 (Add with note "SkillHub" for priority approval) Public Account: 初五Agent (Search on WeChat; reviews and methods are written there, readable without adding me)

My other ready-to-run tools are on this shelf page (copy to browser): https://skillpay.alipay.com/public/jiupinjinlie

If you get stuck or have other scenarios you want me to package into a skill, reach me via any of the above.

This Skill is the complete version with no features removed.