docs: document background jobs across prompts, config example, and README

- Extend the injected Background Jobs prompt guidance: system_notifications
  push on completion, collect-only-when-idle wait protocol, and the graph
  LLM-node collect-before-final-turn rule
- Mention the system_notifications push in the agent spawning guidance and
  in the sisyphus/architect wait-protocol text (agent completions push
  notifications too)
- config.example.yaml: max_concurrent_jobs (default 5, 0 = disabled)
- README: features-list entry pointing at the Background-Jobs wiki page
This commit is contained in:
2026-08-25 18:24:44 -06:00
parent 24ed674952
commit 6256b5fcfa
5 changed files with 16 additions and 9 deletions
+12 -7
View File
@@ -112,9 +112,10 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
### CRITICAL: Never end your turn with pending agents
Spawned agents do NOT report back on their own. They run in the background until you
actively reclaim them with `agent__collect` (to get their output) or `agent__cancel`
(to discard them). If you spawn agents and then emit a final message without reclaiming
Spawned agents do NOT deliver their results on their own. When one finishes, a
`system_notifications` entry appears on your next tool result naming the exact collect
command — but the output is only retrieved when you actively reclaim it with `agent__collect`
(or discard it with `agent__cancel`). If you spawn agents and then emit a final message without reclaiming
them, the system will detect the unreclaimed agents and reject the turn-end, injecting
a reminder forcing you to handle them. After several such reminders, the system will
auto-cancel them and warn you that work was lost.
@@ -194,10 +195,14 @@ pub(in crate::config) const DEFAULT_JOB_INSTRUCTIONS: &str = indoc! {"
## Background Jobs
For long-running tool calls (builds, test suites, slow commands), call `job__start` and keep
working instead of blocking. Check progress with `job__check` (sparingly), block on the result
with `job__collect`, cancel with `job__cancel`, and list jobs with `job__list`. Collect or
cancel every job you started before ending your turn. Jobs run against a snapshot of the
current config/environment and do not survive coyote exiting.
working instead of blocking — completion arrives as a `system_notifications` entry on your
next tool result. Check progress with `job__check` (sparingly), block on the result with
`job__collect` (only when you have nothing else to do), cancel with `job__cancel`, and list
jobs with `job__list`. Collect or cancel every job you started before ending your turn. In
graph LLM nodes, collect or cancel your jobs before ending your final node turn — an
uncollected job at node turn-end burns node iterations via the guardrail and can fail the
node. Jobs run against a snapshot of the current config/environment and do not survive
coyote exiting.
"
};