feat(delegation): add per-task toolsets, persona, and timeout fields

Three new per-task fields on delegate_task batch items:

- **toolsets** (string[]): restrict which tools a subagent loads.
  Previously hardcoded to None (inherit parent), now the model can
  narrow toolsets per task. Intersection with parent toolsets and
  blocked-tool stripping are handled by the existing validation chain.

- **persona** (string): injected into the child's system prompt as a
  YOUR ROLE block to specialize behavior (e.g. 'web researcher',
  'senior engineer') without cramming instructions into context.

- **timeout** (number): per-task wall-clock cap in seconds. Overrides
  the global delegation.child_timeout_seconds for that subagent.
  None = inherit the global default (no timeout by default).

All three are backward-compatible: single-task mode is unchanged,
and batch tasks without the new fields default to None with
existing inheritance behaviour preserved.

Author: prismatic7

tools/delegate_tool.py

@@ -667,6 +667,7 @@ def _build_child_system_prompt(
     role: str = "leaf",
     max_spawn_depth: int = 2,
     child_depth: int = 1,
+    persona: Optional[str] = None,
 ) -> str:
     """Build a focused system prompt for a child agent.
 
@@ -675,12 +676,18 @@ def _build_child_system_prompt(
     inspiration/openclaw/src/agents/subagent-system-prompt.ts:63-95).
     The depth note is literal truth (grounded in the passed config) so
     the LLM doesn't confabulate nesting capabilities that don't exist.
+
+    When ``persona`` is provided, it is injected as a "YOUR ROLE" block
+    that specializes the subagent's behavior (e.g. "web researcher",
+    "senior engineer", "code reviewer").
     """
     parts = [
         "You are a focused subagent working on a specific delegated task.",
         "",
         f"YOUR TASK:\n{goal}",
     ]
+    if persona and persona.strip():
+        parts.append(f"\nYOUR ROLE:\n{persona.strip()}")
     if context and context.strip():
         parts.append(f"\nCONTEXT:\n{context}")
     if workspace_path and str(workspace_path).strip():
@@ -1065,6 +1072,13 @@ def _build_child_agent(
     # 'leaf' (default) cannot; 'orchestrator' retains the delegation
     # toolset subject to depth/kill-switch bounds applied below.
     role: str = "leaf",
+    # Per-task persona — injected into the child's system prompt as
+    # a "YOUR ROLE" block to specialize behavior.
+    persona: Optional[str] = None,
+    # Per-task wall-clock timeout in seconds. Overrides the global
+    # delegation.child_timeout_seconds for this child. None = inherit
+    # the global config default (which itself defaults to no timeout).
+    timeout: Optional[float] = None,
 ):
     """
     Build a child AIAgent on the main thread (thread-safe construction).
@@ -1152,6 +1166,7 @@ def _build_child_agent(
         role=effective_role,
         max_spawn_depth=max_spawn,
         child_depth=child_depth,
+        persona=persona,
     )
     # Extract parent's API key so subagents inherit auth (e.g. Nous Portal).
     parent_api_key = getattr(parent_agent, "api_key", None)
@@ -1373,6 +1388,8 @@ def _child_thinking(text: str) -> None:
     child._parent_subagent_id = parent_subagent_id
     child._subagent_goal = goal
     child._parent_turn_id = getattr(parent_agent, "_current_turn_id", "") or ""
+    # Per-task timeout override (None = inherit global config default)
+    child._delegate_timeout = timeout
     # Stable sidebar marker: delegate subagent sessions must stay out of
     # session pickers even when a parent delete orphans them (parent_session_id
     # → NULL). Mirrors /branch's ``_branched_from`` pattern — see
@@ -1927,7 +1944,9 @@ def _heartbeat_loop():
         # Run child with an optional hard timeout (off by default —
         # result(timeout=None) blocks until the child finishes). Stuck-child
         # protection comes from the heartbeat staleness monitor instead.
-        child_timeout = _get_child_timeout()
+        # Per-task timeout (child._delegate_timeout) beats the global config.
+        _per_task_timeout = getattr(child, "_delegate_timeout", None)
+        child_timeout = _per_task_timeout if _per_task_timeout is not None else _get_child_timeout()
         # Daemon worker (tools.daemon_pool): a timed-out child is abandoned
         # below; a stdlib non-daemon worker would then block interpreter
         # exit at atexit-join time if the child never unwinds.
@@ -2527,13 +2546,16 @@ def delegate_task(
             # Per-task role beats top-level; normalise again so unknown
             # per-task values warn and degrade to leaf uniformly.
             effective_role = _normalize_role(t.get("role") or top_role)
+            # Per-task toolsets: when provided, the model can narrow which
+            # tools a subagent gets. Intersection with parent + blocked-tool
+            # stripping is handled inside _build_child_agent. None = inherit
+            # the parent's full toolset (existing behaviour).
+            per_task_toolsets = t.get("toolsets")
             child = _build_child_agent(
                 task_index=i,
                 goal=t["goal"],
                 context=t.get("context"),
-                # Subagents always inherit the parent's toolsets; the model
-                # cannot choose or narrow them (no model-facing toolsets arg).
-                toolsets=None,
+                toolsets=per_task_toolsets,
                 model=creds["model"],
                 max_iterations=effective_max_iter,
                 task_count=n_tasks,
@@ -2547,6 +2569,8 @@ def delegate_task(
                 override_acp_command=creds.get("command"),
                 override_acp_args=creds.get("args"),
                 role=effective_role,
+                persona=t.get("persona"),
+                timeout=t.get("timeout"),
             )
             # Override with correct parent tool names (before child construction mutated global)
             child._delegate_saved_tool_names = _parent_tool_names
@@ -3324,6 +3348,7 @@ def _build_top_level_description() -> str:
         "delegation.orchestrator_enabled=false.\n"
         "- Subagent model is NOT selectable per call: children inherit the parent model (plus its fallback chain) unless you pin all subagents to a model via delegation.provider / delegation.model in config.yaml.\n"
         "- Each subagent gets its own terminal session (separate working directory and state).\n"
+        "- Per-task fields on batch items: 'toolsets' (restrict which tools the subagent loads), 'persona' (specialize its behavior via a role description), 'timeout' (per-task wall-clock cap in seconds).\n"
         "- Results are always returned as an array, one entry per task."
     )
 
@@ -3338,7 +3363,10 @@ def _build_tasks_param_description() -> str:
         f"Batch mode: tasks to run in parallel (up to {max_children} for this "
         f"user, set via delegation.max_concurrent_children). Each gets "
         "its own subagent with isolated context and terminal session. "
-        "When provided, top-level goal/context/role are ignored."
+        "Per-task fields: 'goal' (required), 'context', 'role', 'toolsets' "
+        "(restrict which tools the subagent loads), 'persona' (specialize "
+        "its behavior), 'timeout' (per-task wall-clock cap in seconds). "
+        "When provided, top-level goal/context/toolsets are ignored."
     )
 
 
@@ -3451,6 +3479,19 @@ def _build_dynamic_schema_overrides() -> dict:
                             "enum": ["leaf", "orchestrator"],
                             "description": "Per-task role override. See top-level 'role' for semantics.",
                         },
+                        "toolsets": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional toolset names to restrict this subagent to (e.g. [\"web\", \"terminal\", \"file\"]). When set, only tools from these toolsets are loaded, significantly reducing input token overhead. When omitted, the subagent inherits the parent's full toolset. Infer from the task — e.g. use [\"web\"] for research, [\"terminal\", \"file\"] for coding, [\"web\", \"terminal\", \"file\", \"delegation\"] for orchestrator tasks.",
+                        },
+                        "persona": {
+                            "type": "string",
+                            "description": "Optional role/persona description injected into the subagent's system prompt (e.g. 'web researcher — focus on finding authoritative sources, cite URLs', 'senior engineer — prioritize correctness, add error handling'). Helps specialize subagent behavior without cramming instructions into context.",
+                        },
+                        "timeout": {
+                            "type": "number",
+                            "description": "Optional per-task wall-clock timeout in seconds. Overrides the global delegation.child_timeout_seconds for this subagent. Use a short timeout for quick lookups (e.g. 30) and a longer one for deep analysis (e.g. 300). Omit to inherit the global default (no timeout by default).",
+                        },
                     },
                     "required": ["goal"],
                 },