From f75dba1a6573661e06d4f4e68ee33c0649ff70eb Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 13 Apr 2026 23:10:55 +0800
Subject: [PATCH] feat(kernel): add WHEN TO USE guidance to task tool and
 promote spawn-background to core (#1348)

- Enrich task tool description with WHEN TO USE / WHEN NOT TO USE
  sections following the Hermes delegate_task pattern, so the LLM
  knows when delegation is appropriate
- Promote spawn-background from deferred to core tier so it is
  always visible in the tool list
- Remove redundant delegation guidance from context_contract (now
  authoritative in tool description)

Closes #1348
---
 crates/kernel/src/agent/mod.rs             |  8 --------
 crates/kernel/src/tool/spawn_background.rs |  2 +-
 crates/kernel/src/tool/task/mod.rs         | 10 +++++++++-
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/crates/kernel/src/agent/mod.rs b/crates/kernel/src/agent/mod.rs
index ee0c3aed..b762c42a 100644
--- a/crates/kernel/src/agent/mod.rs
+++ b/crates/kernel/src/agent/mod.rs
@@ -852,14 +852,6 @@ Excessively long context may cause model call failures. In this case, you MAY us
 `tape-info` to check token usage and you SHOULD use `tape-anchor` to shorten the \
 retrieved history.
 
-**Task delegation**: Use the `task` tool to delegate focused subtasks to a background \
-agent. Pick a task_type: `explore` for codebase research (read-only, fast), `bash` for \
-shell operations, `general-purpose` for complex multi-step work with full tool access. \
-Provide a complete prompt with all necessary context — the child agent does not see your \
-conversation. Use `explore` when your task requires more than 3 search queries or spans \
-multiple files. You can launch multiple tasks concurrently to investigate independent \
-questions in parallel.
-
 **On-demand tool activation**: Call `discover-tools` BEFORE using any tool from \
 the discoverable list below. These are search keywords, NOT callable tools. \
 Example: `discover-tools({{"query":"marketplace"}})`. \
diff --git a/crates/kernel/src/tool/spawn_background.rs b/crates/kernel/src/tool/spawn_background.rs
index f2771150..4f47fddf 100644
--- a/crates/kernel/src/tool/spawn_background.rs
+++ b/crates/kernel/src/tool/spawn_background.rs
@@ -36,7 +36,7 @@ use crate::{
                    instruction), `description` (short status label), and `system_prompt` (agent \
                    behavior). Optional: `name`, `tools`, `model`, `max_iterations`. The agent \
                    runs independently and results are delivered when complete.",
-    tier = "deferred"
+    tier = "core"
 )]
 pub struct SpawnBackgroundTool {
     handle:      KernelHandle,
diff --git a/crates/kernel/src/tool/task/mod.rs b/crates/kernel/src/tool/task/mod.rs
index 9dc4a24e..91227691 100644
--- a/crates/kernel/src/tool/task/mod.rs
+++ b/crates/kernel/src/tool/task/mod.rs
@@ -40,7 +40,15 @@ use crate::{
     description = "Launch a background task using a predefined agent type. Pick a task_type: \
                    'explore' for codebase analysis and research, 'bash' for shell/CLI operations, \
                    'general-purpose' for complex multi-step tasks with full tool access. The \
-                   agent runs independently and results are delivered when complete."
+                   agent runs independently and results are delivered when complete. Only the \
+                   final result enters your context — intermediate tool calls stay in the \
+                   child.\n\nWHEN TO USE:\n- Research spanning 3+ queries or multiple files\n- \
+                   Tasks whose intermediate output would flood your context\n- Independent \
+                   workstreams that can run in parallel\n- Reasoning-heavy subtasks (debugging, \
+                   code review, analysis)\n\nWHEN NOT TO USE:\n- Single tool call — just call the \
+                   tool directly\n- Tasks needing user interaction — child agents cannot ask the \
+                   user\n\nIMPORTANT: The child agent has NO memory of your conversation. Pass \
+                   ALL relevant context (file paths, error messages, constraints) in the prompt."
 )]
 pub struct TaskTool {
     handle:      KernelHandle,