1package tools
2
3import (
4 "context"
5 "encoding/json"
6 "fmt"
7 "strings"
8 "time"
9
10 "github.com/bnema/zut/packages/agent/subagents"
11 "github.com/bnema/zut/packages/core"
12 "github.com/bnema/zut/packages/provider"
13)
14
15// SubagentSpawnTool lets the main agent fork a background sub-agent
16// against the host's cwd via subagents.Supervisor.SpawnReq. The sub-agent runs
17// in parallel: the tool returns the agent id immediately and the main
18// turn continues uninterrupted. The user can monitor / chat with the
19// spawned agent via /subagents.
20//
21// Gated by the auto_subagents_enabled config flag at call time so a user
22// can flip it off mid-session and the next call refuses cleanly
23// without re-registering the tool.
24type SubagentSpawnTool struct {
25 // Supervisor is the supervisor used to spawn agents. Nil means
26 // "auto-subagents not available in this mode" and the tool always
27 // errors.
28 Supervisor *subagents.Supervisor
29
30 // Enabled reads the live config flag. Lets users toggle from
31 // /settings without rebuilding the agent. When nil, the tool
32 // is treated as disabled.
33 Enabled func() bool
34
35 // DefaultModel and DefaultProvider return the host agent's resolved
36 // model and provider. They are used when the tool call omits both
37 // fields and does not select a named profile, so auto-subagents follows
38 // the same auth route as the user sees in the parent session.
39 DefaultModel func() string
40 DefaultProvider func() string
41 DefaultReasoning func() string
42
43 // ResolveSubagent validates and resolves a named markdown profile.
44 // The child receives only the name and loads the profile itself.
45 ResolveSubagent func(name string) (*subagents.Profile, error)
46
47 // OnSpawned, if set, is called after every successful spawn with
48 // the new agent + the task it was started with. Used by the
49 // interactive host to track agents and surface a summary back
50 // in chat when all sub-agents finish.
51 OnSpawned func(agent *subagents.Agent, task string)
52}
53
54type subagentSpawnArgs struct {
55 Task string `json:"task"`
56 Agent string `json:"agent,omitempty"`
57 Model string `json:"model,omitempty"`
58 Provider string `json:"provider,omitempty"`
59 Reasoning string `json:"reasoning,omitempty"`
60 Thinking string `json:"thinking,omitempty"`
61 Isolation string `json:"isolation,omitempty"`
62 Timeout string `json:"timeout,omitempty"`
63 MaxTurns *int `json:"max_turns,omitempty"`
64}
65
66const subagentSpawnSchemaTemplate = `{
67 "type": "object",
68 "properties": {
69 "task": {
70 "type": "string",
71 "description": "The full task description for the sub-agent. Be specific: the child normally has the main agent's built-in tools, including lsp when enabled, but a selected profile can restrict its tools; it shares this working directory and starts with NO context from this conversation."
72 },
73 "agent": {
74 "type": "string",
75 "description": "Optional named markdown profile from [subagents_list]. The child applies that profile's system prompt, model, thinking level, tool limits, and fast-mode preference. Omit for a generic child."
76 },
77 "model": {
78 "type": "string",
79 "description": "Optional model id to pin the sub-agent to. Normally omit both model and provider so the sub-agent inherits the host session's resolved provider/model/auth route, or omit them when using an agent profile. Do not infer provider from model name. If you override this, also provide provider."
80 },
81 "provider": {
82 "type": "string",
83 "description": "Optional provider id. Normally omit both model and provider so the sub-agent inherits the host session. If you override this, also provide model. Note: openai means public OpenAI API-key auth; openai-codex means ChatGPT/Codex subscription auth."
84 },
85 "reasoning": {
86 "type": "string",
87 "enum": ["off", "minimum", "low", "medium", "high", "xhigh", "max"],
88 "description": "Optional reasoning/thinking level for the child. Overrides the selected profile's thinking level when provided."
89 },
90 "thinking": {
91 "type": "string",
92 "enum": ["off", "minimum", "low", "medium", "high", "xhigh", "max"],
93 "description": "Alias for reasoning, accepted for compatibility with common agent profile terminology. Prefer reasoning when both are available."
94 },
95 "isolation": {
96 "type": "string",
97 "enum": ["shared", "worktree"],
98 "description": "Workspace mode. Shared preserves existing behavior; worktree captures a patch without merging it."
99 },
100 "timeout": {
101 "type": "string",
102 "description": "Optional Go duration such as 20m."
103 },
104 "max_turns": {
105 "type": "integer",
106 "minimum": 1,
107 "maximum": %d,
108 "description": "Optional maximum prompt-level turns for this worker. Omit to use the supervisor default; the effective policy allows 1 through %d."
109 }
110 },
111 "required": ["task"]
112}`
113
114func (t *SubagentSpawnTool) Name() string { return "subagent_spawn" }
115func (t *SubagentSpawnTool) Description() string {
116 return "Spawn a background sub-agent to work on a parallel sub-task. Optionally select a named markdown profile, model/provider/reasoning, timeout, turn limit, and shared/worktree isolation, and fast-mode preference. Returns the sub-agent id immediately; completion arrives through the result/event path."
117
118}
119func (t *SubagentSpawnTool) Schema() json.RawMessage {
120 maxTurns := 3
121 if t.Supervisor != nil {
122 if limit := t.Supervisor.MaxTurns(); limit > 0 {
123 maxTurns = limit
124 }
125 }
126 return json.RawMessage(fmt.Sprintf(subagentSpawnSchemaTemplate, maxTurns, maxTurns))
127}
128
129func (t *SubagentSpawnTool) Execute(ctx context.Context, raw json.RawMessage, progress func(string)) (core.ToolResult, error) {
130 prefix := t.Name()
131 if t.Supervisor == nil {
132 return protocolToolError(prefix + ": subagent supervisor not available in this mode")
133 }
134 if t.Enabled == nil || !t.Enabled() {
135 return protocolToolError(prefix + ": auto-subagents is disabled. Ask the user to enable it from /settings before delegating sub-tasks.")
136 }
137 var a subagentSpawnArgs
138 if err := json.Unmarshal(raw, &a); err != nil {
139 return core.ToolResult{}, fmt.Errorf("invalid args: %w", err)
140 }
141 task := strings.TrimSpace(a.Task)
142 if task == "" {
143 return protocolToolError(prefix + ": task is required")
144 }
145
146 workspaceMode := subagents.WorkspaceShared
147 if value := strings.TrimSpace(a.Isolation); value != "" {
148 workspaceMode = subagents.WorkspaceMode(value)
149 if workspaceMode != subagents.WorkspaceShared && workspaceMode != subagents.WorkspaceWorktree {
150 return protocolToolError(prefix + ": isolation must be shared or worktree")
151 }
152 }
153 var timeout time.Duration
154 if value := strings.TrimSpace(a.Timeout); value != "" {
155 parsed, parseErr := time.ParseDuration(value)
156 if parseErr != nil || parsed <= 0 {
157 return protocolToolError(prefix + ": timeout must be a positive duration")
158 }
159 timeout = parsed
160 }
161 if a.MaxTurns != nil {
162 if *a.MaxTurns < 1 {
163 return protocolToolError(prefix + ": max_turns must be positive")
164 }
165 if limit := t.Supervisor.MaxTurns(); limit > 0 && *a.MaxTurns > limit {
166 return protocolToolError(fmt.Sprintf("%s: max_turns must be 1 through %d; omit it to use the supervisor default", prefix, limit))
167 }
168 }
169
170 agentName := strings.TrimSpace(a.Agent)
171 var profile *subagents.Profile
172 var fastModeOverride *bool
173 if agentName != "" {
174 if t.ResolveSubagent == nil {
175 return protocolToolError(prefix + ": named subagent profiles are unavailable")
176 }
177 var err error
178 profile, err = t.ResolveSubagent(agentName)
179 if err != nil {
180 return protocolToolError(prefix + ": " + err.Error())
181 }
182 if profile == nil {
183 return protocolToolError(prefix + ": unknown subagent profile " + agentName)
184 }
185 agentName = profile.Name
186 fastModeOverride = profile.FastMode
187 }
188
189 model := strings.TrimSpace(a.Model)
190 providerID := strings.TrimSpace(a.Provider)
191 var profileTools []string
192 if profile != nil {
193 profileTools = append([]string(nil), profile.Tools...)
194 }
195 if (model == "") != (providerID == "") {
196 return protocolToolError(prefix + ": omit both model/provider to inherit the host or profile, or provide both explicitly")
197 }
198 if profile != nil {
199 // A profile may specify a qualified model, a bare model, a provider,
200 // or neither. Fill only missing pieces so explicit spawn options win;
201 // the parent session supplies whatever the profile leaves unspecified.
202 profileProvider, profileModel := profile.ModelSelection()
203 if model == "" {
204 model = profileModel
205 }
206 if providerID == "" {
207 providerID = profileProvider
208 }
209 }
210 if model == "" && t.DefaultModel != nil {
211 model = strings.TrimSpace(t.DefaultModel())
212 }
213 if providerID == "" && t.DefaultProvider != nil {
214 providerID = strings.TrimSpace(t.DefaultProvider())
215 }
216
217 reasoning, err := reasoningOverride(a.Reasoning, a.Thinking)
218 if err != nil {
219 return protocolToolError(prefix + ": " + err.Error())
220 }
221 if reasoning == "" && profile != nil && strings.TrimSpace(profile.Thinking) != "" {
222 reasoning, err = reasoningOverride(profile.Thinking, "")
223 if err != nil {
224 return protocolToolError(prefix + ": profile " + profile.Name + ": " + err.Error())
225 }
226 }
227 if reasoning == "" && t.DefaultReasoning != nil {
228 reasoning, err = reasoningOverride(t.DefaultReasoning(), "")
229 if err != nil {
230 return protocolToolError(prefix + ": host " + err.Error())
231 }
232 }
233
234 maxTurns := 0
235 if a.MaxTurns != nil {
236 maxTurns = *a.MaxTurns
237 }
238 agent, err := t.Supervisor.SpawnReq(ctx, subagents.SpawnRequest{
239 Task: task,
240 Model: model,
241 Provider: providerID,
242 Reasoning: reasoning,
243 FastMode: fastModeOverride,
244 Subagent: agentName,
245 Timeout: timeout,
246 MaxTurns: maxTurns,
247 WorkspaceMode: workspaceMode,
248 Tools: profileTools,
249 })
250 if err != nil {
251 return core.ToolResult{}, fmt.Errorf("%s: %w", prefix, err)
252 }
253 if t.OnSpawned != nil {
254 t.OnSpawned(agent, task)
255 }
256
257 var sb strings.Builder
258 fmt.Fprintf(&sb, "spawned sub-agent %s\n", agent.ID)
259 fmt.Fprintf(&sb, "state: %s/%s\n", agent.ProcessState(), agent.TurnState())
260 fmt.Fprintf(&sb, "workspace: %s\n", agent.WorkspaceMode)
261 fmt.Fprintf(&sb, "task: %s\n", truncateTask(task, 200))
262 if agentName != "" {
263 fmt.Fprintf(&sb, "agent: %s\n", agentName)
264 }
265 if model != "" {
266 fmt.Fprintf(&sb, "model: %s\n", model)
267 }
268 if providerID != "" {
269 fmt.Fprintf(&sb, "provider: %s\n", providerID)
270 }
271 if reasoning != "" {
272 fmt.Fprintf(&sb, "reasoning: %s\n", reasoning)
273 }
274 if agent.FastMode {
275 sb.WriteString("fast mode: enabled\n")
276 }
277 if fastModeOverride != nil && *fastModeOverride && agent.FastModeOverridesHost() {
278 sb.WriteString("warning: subagent profile has fast mode enabled, overriding global fast mode off\n")
279 }
280 sb.WriteString("\nThe sub-agent is running in the background. Use /subagents in the TUI to monitor it. ")
281 sb.WriteString("This conversation continues immediately; do not wait for the sub-agent to finish before working on the next thing.")
282 return core.ToolResult{
283 Content: []provider.Content{provider.TextBlock{Text: sb.String()}},
284 Details: map[string]any{
285 "agent_id": agent.ID,
286 "task": task,
287 "agent": agentName,
288 "model": model,
289 "provider": providerID,
290 "reasoning": reasoning,
291 "fast_mode": agent.FastMode,
292 "isolation": string(workspaceMode),
293 "timeout": agent.Timeout.String(),
294 "max_turns": agent.MaxTurns,
295 "state": agent.Status(),
296 "process_state": string(agent.ProcessState()),
297 "turn_state": string(agent.TurnState()),
298 "result_ref": subagents.ResultRef(agent.ID),
299 },
300 }, nil
301}
302
303func reasoningOverride(reasoning, thinking string) (string, error) {
304 reasoning = strings.TrimSpace(reasoning)
305 thinking = strings.TrimSpace(thinking)
306 if reasoning != "" && thinking != "" && provider.NormalizeReasoning(reasoning) != provider.NormalizeReasoning(thinking) {
307 return "", fmt.Errorf("reasoning and thinking disagree; provide only one")
308 }
309 value := reasoning
310 if value == "" {
311 value = thinking
312 }
313 if value == "" {
314 return "", nil
315 }
316 normalized := provider.NormalizeReasoning(value)
317 switch normalized {
318 case "":
319 return "off", nil
320 case "minimum", "low", "medium", "high", "xhigh", "max":
321 return normalized, nil
322 default:
323 return "", fmt.Errorf("reasoning must be off|minimum|low|medium|high|xhigh|max")
324 }
325}
326
327// protocolToolError keeps model-visible validation failures in the
328// ToolResult channel rather than treating them as host execution errors.
329func protocolToolError(msg string) (core.ToolResult, error) {
330 //nolint:nilerr // ToolResult.IsError is the established tool protocol.
331 return toolErr(msg), nil
332}
333
334func toolErr(msg string) core.ToolResult {
335 return core.ToolResult{
336 Content: []provider.Content{provider.TextBlock{Text: msg}},
337 IsError: true,
338 }
339}
340
341func truncateTask(s string, n int) string {
342 if len(s) <= n {
343 return s
344 }
345 return s[:n-3] + "..."
346}