From 4025b8dacd8b9fe4b54163585f39b7a6536185d8 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Tue, 25 Aug 2026 16:56:10 -0600
Subject: [PATCH] feat: inject background-jobs prompt guidance when jobs are
 enabled

Agents whose function pool includes job__* declarations get a Background
Jobs section teaching start/check/collect/cancel discipline and the
snapshot/no-persistence semantics. Presence of the declarations doubles
as the jobs_enabled predicate, so a context with function calling off or
max_concurrent_jobs 0 sees no job prompt text.
---
 src/config/agent.rs   | 21 ++++++++++++++++++---
 src/config/prompts.rs | 10 ++++++++++
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/src/config/agent.rs b/src/config/agent.rs
index c139b71..1bafbe3 100644
--- a/src/config/agent.rs
+++ b/src/config/agent.rs
@@ -3,15 +3,19 @@ use super::*;
 use crate::{
     client::Model,
     config::memory,
-    function::{Functions, jobs::DEFAULT_MAX_CONCURRENT_JOBS, run_llm_function},
+    function::{
+        Functions,
+        jobs::{DEFAULT_MAX_CONCURRENT_JOBS, JOB_FUNCTION_PREFIX},
+        run_llm_function,
+    },
     graph, rag,
 };
 
 use super::rag_cache::RagKey;
 use crate::config::paths;
 use crate::config::prompts::{
-    DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS, DEFAULT_TODO_INSTRUCTIONS,
-    DEFAULT_USER_INTERACTION_INSTRUCTIONS,
+    DEFAULT_JOB_INSTRUCTIONS, DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS,
+    DEFAULT_TODO_INSTRUCTIONS, DEFAULT_USER_INTERACTION_INSTRUCTIONS,
 };
 use crate::graph::types::RagNode;
 use crate::graph::{Graph, GraphParser, NodeType};
@@ -450,6 +454,17 @@ impl Agent {
             output.push_str(DEFAULT_SPAWN_INSTRUCTIONS);
         }
 
+        // Job declarations are appended at init iff jobs are enabled for this
+        // agent, so their presence doubles as the jobs_enabled predicate.
+        if self
+            .functions
+            .declarations()
+            .iter()
+            .any(|f| f.name.starts_with(JOB_FUNCTION_PREFIX))
+        {
+            output.push_str(DEFAULT_JOB_INSTRUCTIONS);
+        }
+
         output.push_str(DEFAULT_TEAMMATE_INSTRUCTIONS);
         output.push_str(DEFAULT_USER_INTERACTION_INSTRUCTIONS);
 
diff --git a/src/config/prompts.rs b/src/config/prompts.rs
index cb2e163..e08afec 100644
--- a/src/config/prompts.rs
+++ b/src/config/prompts.rs
@@ -190,6 +190,16 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
     4. **Respond promptly**; the child agent is blocked and waiting (5-minute timeout).
 "};
 
+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."
+};
+
 pub(in crate::config) const DEFAULT_TEAMMATE_INSTRUCTIONS: &str = indoc! {"
     ## Teammate Messaging