PR #72128: feat: implemented configurable label templates for spawned agent sess…

• Repository: openclaw/openclaw
• Author: geethsowri
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/72128

Description (problem / solution / changelog)

Summary

• Problem: sessions_spawn accepted a plain label param with no convention or auto-prefix mechanism; in multi-agent pipelines (Manager / Extractor / Scorer / Reporter), the sessions list shows raw
  user-supplied labels with no way to filter or identify which agent spawned a session.
• Why it matters: Operators running multi-agent workflows must manually prefix every sessions_spawn call — fragile, discipline-dependent, and breaks when callers omit it.
• What changed: Added a labelTemplate config field (string with {agentId} and {taskPreview} tokens) to both agents.defaults.subagents and per-agent agents.list[].subagents. When sessions_spawn is called
  without an explicit label, the template fires as fallback. Per-agent config overrides defaults. Explicit label always wins.
• What did NOT change: No change to spawn behavior, session lifecycle, registry, ACP path, or any existing config keys. Fully additive and backwards-compatible.

Change Type

• Feature

Linked Issue/PR

• Closes #72074
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A — feature addition, not a bug.

• Root cause: N/A
• Missing detection / guardrail: N/A
• Contributing context: N/A

Regression Test Plan (if applicable)

N/A — no existing behavior changed.

• Coverage level that should have caught this: N/A
• Target test or file: N/A
• If no new test is added, why not: Pure additive config + fallback path. No existing code path altered; template only fires when label is absent and labelTemplate is configured.

User-visible / Behavior Changes

New optional config field labelTemplate in agents.defaults.subagents and agents.list[].subagents. No change when field is absent (default behavior unchanged).

Example config:

{                                                         
  "agents": {
    "defaults": {
      "subagents": { "labelTemplate": "{agentId}-{taskPreview}" }                                                                                                                                            
    }                                                            
  }                                                                                                                                                                                                          
}

Tokens: {agentId} = target agent id, {taskPreview} = first 40 chars of task (newlines stripped).

Diagram

Before:
sessions_spawn(task, label?) -> label || "" (no template)

After:

sessions_spawn(task, label?) -> explicitLabel                                                                                                                                                                
                              ?? perAgentTemplate(agentId, task)
                              ?? defaultsTemplate(agentId, task)                                                                                                                                              
                              ?? ""

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 25.0.0
• Runtime: Node 22+
• Relevant config: agents.defaults.subagents.labelTemplate: "{agentId}-{taskPreview}"

Steps

1. Set agents.defaults.subagents.labelTemplate to "{agentId}-{taskPreview}" in config.
2. Invoke sessions_spawn with agentId: "scorer", task: "Score all candidates", no label.
3. Check sessions list.

Expected

• Session label: scorer-Score all candidates

Actual

• Before fix: label is empty string.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Code-reviewed manually; no runtime environment available for live verification (Node 18 on dev machine, repo requires Node 22+).

Human Verification

• Verified scenarios: config type additions, zod schema additions (both defaults + per-agent), template substitution logic, explicit label precedence, per-agent-over-defaults precedence.
• Edge cases checked: no labelTemplate configured (returns ""), no agentId provided (token replaced with ""), task longer than 40 chars (truncated), task with newlines (stripped).
• What I did not verify: live runtime spawn with actual session list inspection.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? Yes — new optional fields added, no existing fields changed
• Migration needed? No

Risks and Mitigations

• Risk: Template with no tokens (e.g. "fixed-label") stamps every session with the same label.
  • Mitigation: Acceptable — user-configured, documented behavior. Could add a lint warning later.
• Risk: opts?.config is snapshotted at tool-construction time, not call time.
  • Mitigation: Consistent with all other opts?.config usage in the same function; not a regression.

Changed files

• src/agents/tools/sessions-spawn-tool.ts (modified, +15/-1)
• src/config/types.agent-defaults.ts (modified, +2/-0)
• src/config/types.agents.ts (modified, +2/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +1/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +1/-0)