johannSoCodeyPublic

subagent: run child agents alongside the session

A subagent is a whole agent — its own conversation, context window, model and
goroutine — and the parent sees only the report it ends with. That is the point:
work that would have filled the parent's window with file listings fills the
child's instead and comes back a paragraph long.

The supervisor owns them. Four run at once and the rest queue; pause, resume
and kill act at the boundaries the loop offers; a child's approvals go through
the session's policy tagged with its id. Presets say what kind of job it is and
nothing about what to spend on it — the agent doing the spawning picks the
model and the effort, because those are judgements about the task, and a pinned
id is a guess about someone else's endpoint.

A report reaches the parent exactly once. Both paths — agent_wait returning it
as a tool result, and the front end putting it into the conversation — claim it
first, and only one claim wins. Deciding that from a copy taken earlier is how
the same report was handed over twice.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Browse Files

Jjonicommitted 4 weeks ago1 parent 68a1174commit3869bc2

Showing 6 changed files with 2205 additions and 0 deletions.

+483−0internal/subagent/control_test.goaddedView File

++ package subagent
++ import (
++ 	"context"
++ 	"strings"
++ 	"sync"
++ 	"testing"
++ 	"time"
++ 	"harness/internal/agent"
++ 	"harness/internal/approval"
++ 	"harness/internal/metrics"
++ 	"harness/internal/tools"
++ )
++ // Parallel agents are parallel spend, so only so many run at once and the rest
++ // wait their turn.
++ func TestTheConcurrencyCapQueuesTheRest(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f, func(o *Options) { o.MaxRunning = 1 })
++ 	first, _ := s.Spawn(Spec{Preset: "explore", Task: "one"})
++ 	second, _ := s.Spawn(Spec{Preset: "explore", Task: "two"})
++ 	third, _ := s.Spawn(Spec{Preset: "explore", Task: "three"})
++ 	waitFor(t, "the first agent to start", func() bool { return statusOf(t, s, first) == Running })
++ 	time.Sleep(settle)
++ 	if got := statusOf(t, s, second); got != Queued {
++ 		t.Errorf("second agent is %s, want queued behind the cap", got)
++ 	}
++ 	if got := statusOf(t, s, third); got != Queued {
++ 		t.Errorf("third agent is %s, want queued behind the cap", got)
++ 	}
++ 	if n := f.count(); n != 1 {
++ 		t.Errorf("%d agents were talking to the API at once, want 1", n)
++ 	}
++ 	f.release()
++ 	waitFor(t, "every agent to finish", func() bool {
++ 		return statusOf(t, s, first) == Done && statusOf(t, s, second) == Done && statusOf(t, s, third) == Done
++ 	})
++ }
++ func TestKillStopsARunningAgent(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to start", func() bool { return statusOf(t, s, id) == Running })
++ 	if err := s.Kill(id); err != nil {
++ 		t.Fatalf("Kill: %v", err)
++ 	}
++ 	waitFor(t, "the agent to stop", func() bool { return statusOf(t, s, id) == Killed })
++ 	f.release()
++ 	info, _ := s.Info(id)
++ 	if info.Err != "" {
++ 		t.Errorf("a killed agent recorded an error (%q); being stopped is not a failure", info.Err)
++ 	}
++ 	if !strings.Contains(info.Notification(), "stopped by the user") {
++ 		t.Errorf("the parent would be told: %q", info.Notification())
++ 	}
++ }
++ // Killing something that has not started must not leave it queued, waiting to
++ // start after it was stopped.
++ func TestKillingAQueuedAgentNeverRunsIt(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f, func(o *Options) { o.MaxRunning = 1 })
++ 	first, _ := s.Spawn(Spec{Preset: "explore", Task: "one"})
++ 	queued, _ := s.Spawn(Spec{Preset: "explore", Task: "two"})
++ 	waitFor(t, "the first agent to start", func() bool { return statusOf(t, s, first) == Running })
++ 	if err := s.Kill(queued); err != nil {
++ 		t.Fatalf("Kill: %v", err)
++ 	}
++ 	if got := statusOf(t, s, queued); got != Killed {
++ 		t.Fatalf("queued agent is %s after being killed", got)
++ 	}
++ 	f.release()
++ 	waitFor(t, "the first agent to finish", func() bool { return statusOf(t, s, first) == Done })
++ 	time.Sleep(settle)
++ 	if n := f.count(); n != 1 {
++ 		t.Errorf("the API saw %d requests, want 1 — the killed agent still ran", n)
++ 	}
++ }
++ // Pausing holds the agent at the next turn boundary and spends nothing until
++ // it is resumed.
++ func TestPauseHoldsAnAgentAndResumeContinuesIt(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.twoTurns = true
++ 	var sup *Supervisor
++ 	// Pausing from inside the first turn's tool call is the only way to be
++ 	// sure the request for the second turn has not gone out yet.
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Observe = func(ev Event) {
++ 			if ev.Agent.Kind == agent.EventToolResult {
++ 				sup.Pause(ev.ID)
++ 			}
++ 		}
++ 	})
++ 	sup = s
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to be held", func() bool { return statusOf(t, s, id) == Paused })
++ 	time.Sleep(settle)
++ 	if n := f.count(); n != 1 {
++ 		t.Fatalf("a paused agent made %d requests, want 1", n)
++ 	}
++ 	if err := s.Resume(id); err != nil {
++ 		t.Fatalf("Resume: %v", err)
++ 	}
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	if n := f.count(); n != 2 {
++ 		t.Errorf("made %d requests overall, want 2", n)
++ 	}
++ }
++ // Pausing something that never started would be a lie in the sidebar: there is
++ // nothing to hold. Say so, and point at the thing that does work.
++ func TestPausingAQueuedAgentSaysItHasNotStarted(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f, func(o *Options) { o.MaxRunning = 1 })
++ 	first, _ := s.Spawn(Spec{Preset: "explore", Task: "one"})
++ 	queued, _ := s.Spawn(Spec{Preset: "explore", Task: "two"})
++ 	waitFor(t, "the first agent to start", func() bool { return statusOf(t, s, first) == Running })
++ 	err := s.Pause(queued)
++ 	if err == nil {
++ 		t.Fatal("pausing a queued agent succeeded")
++ 	}
++ 	if !strings.Contains(err.Error(), "not started") {
++ 		t.Errorf("error = %q, want it to say the agent has not started", err)
++ 	}
++ 	if got := statusOf(t, s, queued); got != Queued {
++ 		t.Errorf("a failed pause changed the status to %s", got)
++ 	}
++ 	f.release()
++ }
++ func TestPauseAndResumeOnAFinishedAgentAreRefused(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	for _, err := range []error{s.Pause(id), s.Resume(id), s.Kill(id)} {
++ 		if err == nil {
++ 			t.Error("controlling a finished agent succeeded")
++ 		} else if !strings.Contains(err.Error(), "already finished") {
++ 			t.Errorf("error = %q, want it to say the agent has finished", err)
++ 		}
++ 	}
++ }
++ func TestWaitReturnsHowTheAgentEnded(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	info, err := s.Wait(context.Background(), id)
++ 	if err != nil {
++ 		t.Fatalf("Wait: %v", err)
++ 	}
++ 	if info.Status != Done || info.Report != "handled: find it" {
++ 		t.Errorf("Wait returned %+v", info)
++ 	}
++ }
++ // Interrupting the turn that is waiting must not kill the agent it waited for:
++ // the wait is the parent's, the work is the child's.
++ func TestWaitIsInterruptibleWithoutKillingTheAgent(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	ctx, cancel := context.WithCancel(context.Background())
++ 	cancel()
++ 	if _, err := s.Wait(ctx, id); err == nil {
++ 		t.Fatal("a cancelled Wait returned no error")
++ 	}
++ 	if got := statusOf(t, s, id); !got.Live() {
++ 		t.Errorf("the agent is %s after its waiter gave up", got)
++ 	}
++ 	f.release()
++ 	waitFor(t, "the agent to finish on its own", func() bool { return statusOf(t, s, id) == Done })
++ }
++ func TestWaitingOnAnUnknownAgentSaysSo(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	if _, err := s.Wait(context.Background(), "a9"); err == nil {
++ 		t.Fatal("waiting on an agent that does not exist succeeded")
++ 	}
++ }
++ // Reports are handed to the parent exactly once: twice would repeat the work
++ // in its context, never would lose it.
++ func TestReportsAreHandedOverOnce(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	first := s.TakeReports()
++ 	if len(first) != 1 || first[0].ID != id {
++ 		t.Fatalf("TakeReports = %+v, want the finished agent", first)
++ 	}
++ 	if again := s.TakeReports(); len(again) != 0 {
++ 		t.Errorf("TakeReports handed the same report over twice: %+v", again)
++ 	}
++ }
++ // The front end redraws on a callback rather than by polling, so a status
++ // change that fires nothing would leave a finished agent showing as running.
++ func TestChangedFiresOnStatusChanges(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	var changes int
++ 	var mu = make(chan struct{}, 1)
++ 	mu <- struct{}{}
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Changed = func() {
++ 			<-mu
++ 			changes++
++ 			mu <- struct{}{}
++ 		}
++ 	})
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	waitFor(t, "the change callback", func() bool {
++ 		<-mu
++ 		defer func() { mu <- struct{}{} }()
++ 		return changes >= 2
++ 	})
++ }
++ // Leaving the harness must not leave agents editing a tree nobody is watching.
++ func TestShutdownStopsEverything(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f, func(o *Options) { o.MaxRunning = 1 })
++ 	running, _ := s.Spawn(Spec{Preset: "general", Task: "one"})
++ 	queued, _ := s.Spawn(Spec{Preset: "general", Task: "two"})
++ 	waitFor(t, "the first agent to start", func() bool { return statusOf(t, s, running) == Running })
++ 	done := make(chan struct{})
++ 	go func() { s.Shutdown(); close(done) }()
++ 	f.release()
++ 	select {
++ 	case <-done:
++ 	case <-time.After(3 * time.Second):
++ 		t.Fatal("Shutdown never returned")
++ 	}
++ 	for _, id := range []string{running, queued} {
++ 		if got := statusOf(t, s, id); got.Live() {
++ 			t.Errorf("agent %s is %s after shutdown", id, got)
++ 		}
++ 	}
++ }
++ // A subagent's tool calls go through the same policy the session's own do, and
++ // the request has to say which agent is asking — you cannot decide on a shell
++ // command without knowing who wants to run it. While it waits, the sidebar has
++ // to show that it is stopped on you rather than working.
++ func TestASubagentsApprovalIsTaggedAndShowsAsWaiting(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.callTool = "noop"
++ 	asked := make(chan approval.Request, 4)
++ 	release := make(chan approval.Decision)
++ 	policy := approval.New(func(ctx context.Context, req approval.Request) (approval.Decision, error) {
++ 		asked <- req
++ 		select {
++ 		case d := <-release:
++ 			return d, nil
++ 		case <-ctx.Done():
++ 			return approval.Deny, ctx.Err()
++ 		}
++ 	})
++ 	s := newSupervisor(t, f, func(o *Options) { o.Policy = policy })
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	var req approval.Request
++ 	select {
++ 	case req = <-asked:
++ 	case <-time.After(3 * time.Second):
++ 		t.Fatal("the subagent's tool call never reached the approval policy")
++ 	}
++ 	if req.Agent != id {
++ 		t.Errorf("the prompt says agent %q, want %q", req.Agent, id)
++ 	}
++ 	waitFor(t, "the agent to show as waiting", func() bool { return statusOf(t, s, id) == Waiting })
++ 	release <- approval.Once
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ }
++ // newBlockedSupervisor holds every child inside its tool-set construction, so
++ // a test can act on an agent in the window between being given a slot and
++ // having anything to cancel. release lets them through.
++ func newBlockedSupervisor(t *testing.T, f *fakeAPI) (*Supervisor, func()) {
++ 	t.Helper()
++ 	gate := make(chan struct{})
++ 	root := t.TempDir()
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Tools = func(state *agent.State, log *metrics.Logger) *tools.Registry {
++ 			<-gate
++ 			return tools.NewRegistry(log).Register(tools.NewRead(root, state))
++ 		}
++ 	})
++ 	var once sync.Once
++ 	return s, func() { once.Do(func() { close(gate) }) }
++ }
++ // Killing an agent that has a slot but has not reached its first request must
++ // stop it. Losing the kill there means watching an agent you stopped carry on
++ // editing files.
++ func TestKillingAnAgentThatIsStillStartingStopsIt(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s, release := newBlockedSupervisor(t, f)
++ 	defer release()
++ 	// Spawn blocks in the gate: a child is built on the goroutine that asked
++ 	// for it, and the gate is inside that construction.
++ 	go s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to take a slot", func() bool {
++ 		rows := s.Snapshot()
++ 		return len(rows) == 1 && rows[0].Status == Running
++ 	})
++ 	id := s.Snapshot()[0].ID
++ 	if err := s.Kill(id); err != nil {
++ 		t.Fatalf("Kill: %v", err)
++ 	}
++ 	release()
++ 	waitFor(t, "the agent to stop", func() bool { return statusOf(t, s, id) == Killed })
++ 	time.Sleep(settle)
++ 	if n := f.count(); n != 0 {
++ 		t.Errorf("a killed agent still made %d requests", n)
++ 	}
++ }
++ // Shutting down in that same window must not find a half-built child it
++ // accounts for twice — once as never-started and once when it ends.
++ func TestShutdownDuringStartupDoesNotPanic(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s, release := newBlockedSupervisor(t, f)
++ 	go s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to take a slot", func() bool {
++ 		rows := s.Snapshot()
++ 		return len(rows) == 1 && rows[0].Status == Running
++ 	})
++ 	id := s.Snapshot()[0].ID
++ 	done := make(chan struct{})
++ 	go func() { s.Shutdown(); close(done) }()
++ 	time.Sleep(settle)
++ 	release()
++ 	select {
++ 	case <-done:
++ 	case <-time.After(3 * time.Second):
++ 		t.Fatal("Shutdown never returned")
++ 	}
++ 	if got := statusOf(t, s, id); got.Live() {
++ 		t.Errorf("agent is %s after shutdown", got)
++ 	}
++ 	// The half-built child is let go last. If shutting down accounted for it
++ 	// once and its own ending accounts for it again, this is where the process
++ 	// dies — so the test waits for that ending rather than leaving it to land
++ 	// after the run, as a crash somebody sees once a month.
++ 	waitFor(t, "the released agent to end", func() bool { return statusOf(t, s, id) == Killed })
++ 	time.Sleep(settle)
++ 	if n := f.count(); n != 0 {
++ 		t.Errorf("an agent shut down before it started still made %d requests", n)
++ 	}
++ }
++ // The sequence that used to send every report twice: the agent finishes, the
++ // front end drains it into its pending queue, and only then does the parent's
++ // agent_wait land. Whoever hands the report to the model has to claim it, or
++ // the other one hands it over again — which is what the whole feature exists
++ // to avoid.
++ func TestAReportDrainedBeforeTheWaitIsNotSentTwice(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	// The front end drains first — it holds the report, it has not given it
++ 	// to the model yet.
++ 	if reports := s.TakeReports(); len(reports) != 1 {
++ 		t.Fatalf("TakeReports = %+v", reports)
++ 	}
++ 	// Now the parent asks for it, and gets it as the tool's result.
++ 	info, err := s.Wait(context.Background(), id)
++ 	if err != nil {
++ 		t.Fatalf("Wait: %v", err)
++ 	}
++ 	if !s.ClaimReport(info.ID) {
++ 		t.Fatal("agent_wait could not claim a report nobody had delivered")
++ 	}
++ 	// The front end, coming to inject the copy it drained, must be refused.
++ 	if s.ClaimReport(id) {
++ 		t.Error("the front end would put the same report into the conversation a second time")
++ 	}
++ }
++ // Claiming is the handover, so exactly one caller can win it however many ask.
++ func TestOnlyOneClaimOnAReportEverWins(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	var won int
++ 	for i := 0; i < 4; i++ {
++ 		if s.ClaimReport(id) {
++ 			won++
++ 		}
++ 	}
++ 	if won != 1 {
++ 		t.Errorf("%d callers were told to deliver the same report", won)
++ 	}
++ 	if s.ClaimReport("a99") {
++ 		t.Error("an agent that does not exist had a report to claim")
++ 	}
++ }
++ // An agent still working has nothing to hand over yet.
++ func TestARunningAgentsReportCannotBeClaimed(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to start", func() bool { return statusOf(t, s, id) == Running })
++ 	if s.ClaimReport(id) {
++ 		t.Error("claimed a report from an agent that has not finished")
++ 	}
++ 	f.release()
++ }
++ // A wait the user interrupted delivered nothing, so the report must still be
++ // there for the front end to hand over.
++ func TestAnInterruptedWaitLeavesTheReportToBeDelivered(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	ctx, cancel := context.WithCancel(context.Background())
++ 	cancel()
++ 	if _, err := s.Wait(ctx, id); err == nil {
++ 		t.Fatal("a cancelled Wait returned no error")
++ 	}
++ 	f.release()
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	if !s.ClaimReport(id) {
++ 		t.Error("the report was claimed by a wait that was interrupted before it delivered anything")
++ 	}
++ }

+102−0internal/subagent/presets.goaddedView File

++ package subagent
++ import (
++ 	"fmt"
++ 	"strings"
++ )
++ // Preset is one kind of subagent: a brief and a turn budget. They are compiled
++ // in rather than configurable, because a preset the model can invent is a
++ // blast radius the model can invent.
++ //
++ // A preset deliberately pins no model and no effort level. Which model suits a
++ // job is a judgement about that job — a search across forty files and a design
++ // question are not the same errand — and the agent doing the spawning is the
++ // one holding the task. Pinning them here also meant pinning ids that a
++ // gateway may not serve at all.
++ type Preset struct {
++ 	Name string
++ 	// Description is one line, shown in the spawn tool's description and in
++ 	// the sidebar. It is what the model chooses between.
++ 	Description string
++ 	// MaxTurns overrides the session's cap when set: what differs between
++ 	// these jobs is how long they are worth running, not what they run on.
++ 	MaxTurns int
++ 	// System is the brief. It replaces the session's system prompt outright:
++ 	// a subagent is not a smaller copy of the main agent, it is a different
++ 	// job with a different definition of done.
++ 	System string
++ }
++ // sharedRules are what every subagent has to know about being one. They report
++ // back through a final message and nothing else: nobody is reading their
++ // transcript turn by turn.
++ const sharedRules = `
++ You are a subagent: another agent delegated this task to you and is waiting on
++ your answer. You cannot ask it questions and you cannot spawn agents of your
++ own. Work with what you were given.
++ Your final message is the entire report — it is all the agent that spawned you
++ will see. Lead with the answer, then the specifics it needs: file paths with
++ line numbers, what you changed, what you could not settle and why. Do not
++ describe your process, and do not pad it.`
++ var presets = []Preset{
++ 	{
++ 		Name:        "explore",
++ 		Description: "search the repository and report what is where — for questions of fact, where a small fast model earns its keep",
++ 		MaxTurns:    20,
++ 		System: `You are a code exploration agent. You find things in a repository and report
++ precisely where they are.
++ Search before you read: glob and grep cost less than reading files that turn
++ out to be the wrong ones. Read only the regions you need. Answer with paths and
++ line numbers, not with paraphrase — the agent reading your report will go to
++ those lines.` + sharedRules,
++ 	},
++ 	{
++ 		Name:        "plan",
++ 		Description: "work out how a change should be made and report the approach, without making it — worth a strong model",
++ 		MaxTurns:    30,
++ 		System: `You are a software design agent. You work out how a change should be made in
++ this repository and report the plan.
++ Read the code that the change would touch before proposing anything: a plan
++ that does not match the code as it is costs more than no plan. Follow the
++ conventions already there rather than the ones you would have chosen. Report
++ the approach, the files it touches, the order of the steps, and the risks worth
++ knowing about.` + sharedRules,
++ 	},
++ 	{
++ 		Name:        "general",
++ 		Description: "carry out a self-contained piece of work end to end, including edits and tests",
++ 		MaxTurns:    40,
++ 		System: `You are a coding agent working on a self-contained task delegated to you.
++ Never guess at file paths — find them with glob or grep. When you change
++ something, verify it by running the project's own tests rather than asserting
++ that it works. Stay inside the task you were given: work you were not asked for
++ is work nobody will review.` + sharedRules,
++ 	},
++ }
++ // Presets are the kinds of subagent that can be spawned, in the order they are
++ // offered.
++ func Presets() []Preset { return append([]Preset(nil), presets...) }
++ // Lookup finds a preset by name. The error lists the real ones, because the
++ // caller is usually a model that guessed.
++ func Lookup(name string) (Preset, error) {
++ 	for _, p := range presets {
++ 		if p.Name == name {
++ 			return p, nil
++ 		}
++ 	}
++ 	var names []string
++ 	for _, p := range presets {
++ 		names = append(names, p.Name)
++ 	}
++ 	return Preset{}, fmt.Errorf("no such agent preset %q. The ones that exist are: %s",
++ 		name, strings.Join(names, ", "))
++ }

+721−0internal/subagent/supervisor.goaddedView File

++ // Package subagent runs child agents alongside the session's own.
++ //
++ // A subagent is a whole agent: its own conversation, its own context window,
++ // its own model, its own goroutine. The agent that spawned one never sees its
++ // turns — only the report it ends with — which is the point. Work that would
++ // have filled the parent's window is spent somewhere else and comes back a
++ // paragraph long.
++ //
++ // Like the agent package, this one knows nothing about a terminal. It reports
++ // through callbacks and a snapshot, so the TUI and the eval runner can both
++ // drive it.
++ package subagent
++ import (
++ 	"context"
++ 	"encoding/json"
++ 	"errors"
++ 	"fmt"
++ 	"strings"
++ 	"sync"
++ 	"time"
++ 	"harness/internal/agent"
++ 	"harness/internal/approval"
++ 	"harness/internal/llm"
++ 	"harness/internal/metrics"
++ 	"harness/internal/tools"
++ )
++ // Status is where one subagent is in its life.
++ type Status string
++ const (
++ 	// Queued is spawned but waiting for a slot: only so many agents run at
++ 	// once, because parallel agents are parallel spend.
++ 	Queued Status = "queued"
++ 	// Waiting is blocked on an approval prompt — stopped by you, not by
++ 	// itself.
++ 	Waiting Status = "waiting"
++ 	Running Status = "running"
++ 	Paused  Status = "paused"
++ 	Done    Status = "done"
++ 	Failed  Status = "failed"
++ 	Killed  Status = "killed"
++ )
++ // Live reports whether the agent is still going to do something. A live agent
++ // holds one of the concurrency slots; a finished one does not.
++ func (s Status) Live() bool {
++ 	switch s {
++ 	case Queued, Running, Waiting, Paused:
++ 		return true
++ 	}
++ 	return false
++ }
++ // DefaultMaxRunning caps how many subagents run at once. Four is enough to
++ // parallelise a search and few enough that a runaway spawn loop is visible
++ // before it is expensive.
++ const DefaultMaxRunning = 4
++ // Info is one subagent as the outside world sees it: everything the sidebar
++ // draws and everything the parent is told.
++ type Info struct {
++ 	ID     string
++ 	Preset string
++ 	Model  string
++ 	// Effort is the level this agent runs at, empty when it runs at the
++ 	// session's — or when the model it is on takes no effort level at all.
++ 	Effort string
++ 	Task   string
++ 	Status Status
++ 	Turns  int
++ 	Usage  llm.Usage
++ 	// Started is when it got a slot, not when it was spawned; a queued agent
++ 	// has not started.
++ 	Started time.Time
++ 	Ended   time.Time
++ 	// Report is the agent's final message: the whole of what it hands back.
++ 	Report string
++ 	// Err is why it failed, empty otherwise.
++ 	Err string
++ }
++ // Cost prices the agent's usage at its own model, which is the only honest way
++ // to bill a haiku agent spawned from an opus session.
++ func (i Info) Cost() (float64, bool) { return i.Usage.Cost(i.Model) }
++ // Elapsed is how long it has been running, or how long it ran.
++ func (i Info) Elapsed() time.Duration {
++ 	if i.Started.IsZero() {
++ 		return 0
++ 	}
++ 	if i.Ended.IsZero() {
++ 		return time.Since(i.Started)
++ 	}
++ 	return i.Ended.Sub(i.Started)
++ }
++ // Notification is what the parent agent is told when this agent finishes. It
++ // goes into the conversation as a user message, so it names the agent and
++ // repeats the task: by the time it lands, several turns may have passed and
++ // the parent has to be able to place it.
++ func (i Info) Notification() string {
++ 	var b strings.Builder
++ 	switch i.Status {
++ 	case Done:
++ 		fmt.Fprintf(&b, "[subagent %s (%s) finished after %s]\n", i.ID, i.Preset, plural(i.Turns, "turn"))
++ 		fmt.Fprintf(&b, "Its task was: %s\n\nIts report:\n%s", i.Task, i.Report)
++ 	case Failed:
++ 		fmt.Fprintf(&b, "[subagent %s (%s) failed]\nIts task was: %s\nIt stopped because: %s\n\n", i.ID, i.Preset, i.Task, i.Err)
++ 		b.WriteString("Nothing it may have done was rolled back. Decide whether to do this work yourself, spawn another agent, or leave it.")
++ 		if i.Report != "" {
++ 			fmt.Fprintf(&b, "\n\nWhat it had said before it stopped:\n%s", i.Report)
++ 		}
++ 	case Killed:
++ 		fmt.Fprintf(&b, "[subagent %s (%s) was stopped by the user]\nIts task was: %s\n\n", i.ID, i.Preset, i.Task)
++ 		b.WriteString("Do not spawn it again unless you are asked to: the user stopped it on purpose.")
++ 	default:
++ 		fmt.Fprintf(&b, "[subagent %s (%s) is %s]", i.ID, i.Preset, i.Status)
++ 	}
++ 	return b.String()
++ }
++ // AlreadyDelivered is what agent_wait answers when the report has already
++ // reached the parent another way. Repeating the text would charge it twice for
++ // something already in its context, which is the cost this whole feature
++ // exists to avoid.
++ func (i Info) AlreadyDelivered() string {
++ 	return fmt.Sprintf("[subagent %s (%s) %s after %s — its report has already been delivered to you "+
++ 		"as a message in this conversation. Read it there rather than waiting again.]",
++ 		i.ID, i.Preset, endedWord(i.Status), plural(i.Turns, "turn"))
++ }
++ // endedWord is how an agent's ending is described in a sentence.
++ func endedWord(s Status) string {
++ 	switch s {
++ 	case Failed:
++ 		return "failed"
++ 	case Killed:
++ 		return "was stopped"
++ 	}
++ 	return "finished"
++ }
++ func plural(n int, word string) string {
++ 	if n == 1 {
++ 		return fmt.Sprintf("%d %s", n, word)
++ 	}
++ 	return fmt.Sprintf("%d %ss", n, word)
++ }
++ // Event is one child's agent event, tagged with the child it came from. The
++ // front end keeps a transcript per agent and needs to know which.
++ type Event struct {
++ 	ID     string
++ 	Preset string
++ 	Model  string
++ 	Agent  agent.Event
++ }
++ // Options wires a Supervisor.
++ type Options struct {
++ 	// Client is the session's. Children are cloned off it so they
++ 	// authenticate identically and differ only in the model.
++ 	Client *llm.Client
++ 	Log    *metrics.Logger
++ 	// Policy gates children's tool calls. Nil means nothing is gated, which
++ 	// is only right where the blast radius is already contained.
++ 	Policy *approval.Policy
++ 	// Base carries the session's agent settings — streaming, caching, the
++ 	// context window, the identity prefix, the discovered skills. The preset
++ 	// supplies the system prompt, the effort and the turn cap over the top.
++ 	Base agent.Options
++ 	// Tools builds the tool set for one child. It is supplied by the caller
++ 	// because the tools need a root, and the supervisor has no business
++ 	// knowing one. Note what it does not include: the spawn tools, so a
++ 	// subagent cannot spawn subagents.
++ 	Tools func(*agent.State, *metrics.Logger) *tools.Registry
++ 	// MaxRunning caps concurrency. Zero means DefaultMaxRunning.
++ 	MaxRunning int
++ 	// Observe receives every child's events, tagged. It may be nil.
++ 	Observe func(Event)
++ 	// Changed is called when a status changes or a report is queued, so a
++ 	// front end knows to redraw without polling. It may be nil.
++ 	Changed func()
++ }
++ // child is one subagent and the handles needed to control it.
++ type child struct {
++ 	info   Info
++ 	ag     *agent.Agent
++ 	cancel context.CancelFunc
++ 	// killed records that the cancellation was deliberate, so the ordinary
++ 	// context error is reported as a kill rather than as a failure.
++ 	killed bool
++ 	// pauseWanted holds a pause asked for before the agent existed.
++ 	pauseWanted bool
++ 	// delivered records that this agent's report has been handed to the
++ 	// parent — as an agent_wait result or as a message the front end put into
++ 	// the conversation. Whoever hands it over claims it first, so the other
++ 	// one knows not to.
++ 	delivered bool
++ 	done      chan struct{}
++ }
++ // Supervisor owns every subagent of one session.
++ type Supervisor struct {
++ 	ctx  context.Context
++ 	opts Options
++ 	mu    sync.Mutex
++ 	byID  map[string]*child
++ 	order []*child
++ 	n     int
++ 	// reports are finished agents the parent has not been told about yet.
++ 	reports []Info
++ 	wg sync.WaitGroup
++ }
++ // New builds a supervisor. ctx is the parent of every child's context: it
++ // outlives any one turn, because a subagent must survive the interruption of
++ // the turn that spawned it.
++ func New(ctx context.Context, opts Options) *Supervisor {
++ 	if opts.MaxRunning <= 0 {
++ 		opts.MaxRunning = DefaultMaxRunning
++ 	}
++ 	return &Supervisor{ctx: ctx, opts: opts, byID: map[string]*child{}}
++ }
++ // Subscribe sets the callbacks a front end wants. It exists because the TUI
++ // cannot be built before the supervisor it watches: the program has to exist
++ // to be sent messages, and the supervisor has to exist to be handed to it.
++ func (s *Supervisor) Subscribe(observe func(Event), changed func()) {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	s.opts.Observe, s.opts.Changed = observe, changed
++ }
++ // observer and notifier read the callbacks under the lock, so Subscribe can be
++ // called while children are already running.
++ func (s *Supervisor) observer() func(Event) {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	return s.opts.Observe
++ }
++ func (s *Supervisor) changed() {
++ 	s.mu.Lock()
++ 	fn := s.opts.Changed
++ 	s.mu.Unlock()
++ 	if fn != nil {
++ 		fn()
++ 	}
++ }
++ // Spec is what one subagent is asked to be: which preset, what to do, and what
++ // to spend on it. Model and Effort are the caller's choice — the presets pin
++ // neither — and both may be empty, which inherits the session's.
++ type Spec struct {
++ 	Preset string
++ 	Task   string
++ 	Model  string
++ 	Effort string
++ }
++ // Spawn starts a subagent, or queues it when the concurrency cap is full. It
++ // returns the id immediately: the work happens on its own goroutine.
++ func (s *Supervisor) Spawn(spec Spec) (string, error) {
++ 	p, err := Lookup(spec.Preset)
++ 	if err != nil {
++ 		return "", err
++ 	}
++ 	if strings.TrimSpace(spec.Task) == "" {
++ 		return "", errors.New("a subagent needs a task: say what it should do and what to report back")
++ 	}
++ 	task := spec.Task
++ 	model := spec.Model
++ 	if model == "" {
++ 		// Nobody chose: the session's own model is the one answer that is
++ 		// certainly served by this endpoint.
++ 		model = s.opts.Client.Model()
++ 	}
++ 	effort := spec.Effort
++ 	if effort != "" && !llm.ValidEffort(effort) {
++ 		return "", fmt.Errorf("no such effort level %q. The ones that exist are: %s",
++ 			effort, strings.Join(llm.EffortLevels, ", "))
++ 	}
++ 	// A level this model does not take is not a reason to refuse the spawn —
++ 	// the job and the model may both be right — but it is not in force, and
++ 	// recording it as though it were would be a lie in the sidebar and in the
++ 	// answer the parent gets.
++ 	if !llm.SupportsEffort(model, effort) {
++ 		effort = ""
++ 	}
++ 	s.mu.Lock()
++ 	s.n++
++ 	id := fmt.Sprintf("a%d", s.n)
++ 	c := &child{
++ 		info: Info{ID: id, Preset: p.Name, Model: model, Effort: effort, Task: task, Status: Queued},
++ 		done: make(chan struct{}),
++ 	}
++ 	s.byID[id] = c
++ 	s.order = append(s.order, c)
++ 	s.mu.Unlock()
++ 	s.opts.Log.Log(metrics.Event{Type: "subagent_spawn", Extra: map[string]any{
++ 		"agent": id, "preset": p.Name, "model": model, "effort": effort,
++ 	}})
++ 	s.changed()
++ 	s.pump()
++ 	return id, nil
++ }
++ // pump starts queued children while there are slots. It is called whenever the
++ // set of running agents can have changed.
++ func (s *Supervisor) pump() {
++ 	for {
++ 		s.mu.Lock()
++ 		running := 0
++ 		for _, c := range s.order {
++ 			if c.info.Status.Live() && c.info.Status != Queued {
++ 				running++
++ 			}
++ 		}
++ 		var next *child
++ 		if running < s.opts.MaxRunning {
++ 			for _, c := range s.order {
++ 				if c.info.Status == Queued {
++ 					next = c
++ 					break
++ 				}
++ 			}
++ 		}
++ 		if next == nil {
++ 			s.mu.Unlock()
++ 			return
++ 		}
++ 		next.info.Status = Running
++ 		next.info.Started = time.Now()
++ 		// The context, its cancel, and the wait-group count are all taken here,
++ 		// in the same hold of the lock that marks the child running. Setting
++ 		// them up inside start instead would leave a window where the child
++ 		// is running with nothing to cancel and nothing to wait for: a kill
++ 		// landing in it would be lost, and a shutdown would account for the
++ 		// child twice.
++ 		ctx, cancel := context.WithCancel(s.ctx)
++ 		next.cancel = cancel
++ 		s.wg.Add(1)
++ 		s.mu.Unlock()
++ 		s.start(next, ctx, cancel)
++ 		s.changed()
++ 	}
++ }
++ // start builds the child's agent and runs it. The context is already live and
++ // already cancellable by the time it gets here.
++ func (s *Supervisor) start(c *child, ctx context.Context, cancel context.CancelFunc) {
++ 	p, _ := Lookup(c.info.Preset)
++ 	id, task := c.info.ID, c.info.Task
++ 	log := s.opts.Log.For(id)
++ 	state := agent.NewState()
++ 	reg := s.opts.Tools(state, log)
++ 	o := s.opts.Base
++ 	o.System = p.System
++ 	if c.info.Effort != "" {
++ 		o.Effort = c.info.Effort
++ 	}
++ 	if p.MaxTurns > 0 {
++ 		o.MaxTurns = p.MaxTurns
++ 	}
++ 	ag := agent.New(s.opts.Client.Clone(c.info.Model), reg, state, log, o)
++ 	ag.Observe = func(ev agent.Event) { s.onEvent(id, ev) }
++ 	if s.opts.Policy != nil {
++ 		ag.Approve = approver{sup: s, id: id}
++ 	}
++ 	s.mu.Lock()
++ 	c.ag = ag
++ 	pause := c.pauseWanted
++ 	s.mu.Unlock()
++ 	if pause {
++ 		ag.Pause()
++ 	}
++ 	go func() {
++ 		defer s.wg.Done()
++ 		defer cancel()
++ 		// A kill that landed while this child was being built has already
++ 		// cancelled ctx, so Run returns at once and finish records it as
++ 		// killed — without the agent having done anything.
++ 		report, err := ag.Run(ctx, task)
++ 		s.finish(c, report, err)
++ 	}()
++ }
++ // onEvent keeps the snapshot current and forwards the event.
++ func (s *Supervisor) onEvent(id string, ev agent.Event) {
++ 	var status bool
++ 	s.mu.Lock()
++ 	c := s.byID[id]
++ 	if c != nil {
++ 		switch ev.Kind {
++ 		case agent.EventTurnStart:
++ 			c.info.Turns = ev.Turn
++ 		case agent.EventUsage:
++ 			c.info.Usage = addUsage(c.info.Usage, ev.Usage)
++ 		case agent.EventPaused:
++ 			c.info.Status, status = Paused, true
++ 		case agent.EventResumed:
++ 			c.info.Status, status = Running, true
++ 		}
++ 	}
++ 	var preset, model string
++ 	if c != nil {
++ 		preset, model = c.info.Preset, c.info.Model
++ 	}
++ 	s.mu.Unlock()
++ 	if fn := s.observer(); fn != nil {
++ 		fn(Event{ID: id, Preset: preset, Model: model, Agent: ev})
++ 	}
++ 	if status {
++ 		s.changed()
++ 	}
++ }
++ // finish records how a child ended and queues its report for the parent.
++ func (s *Supervisor) finish(c *child, report string, err error) {
++ 	s.mu.Lock()
++ 	c.info.Ended = time.Now()
++ 	c.info.Report = strings.TrimSpace(report)
++ 	switch {
++ 	case c.killed:
++ 		c.info.Status = Killed
++ 	case err != nil:
++ 		c.info.Status = Failed
++ 		c.info.Err = err.Error()
++ 	default:
++ 		c.info.Status = Done
++ 	}
++ 	info := c.info
++ 	s.reports = append(s.reports, info)
++ 	close(c.done)
++ 	s.mu.Unlock()
++ 	cost, _ := info.Cost()
++ 	s.opts.Log.Log(metrics.Event{Type: "subagent_finish", Turn: info.Turns, Extra: map[string]any{
++ 		"agent": info.ID, "preset": info.Preset, "status": string(info.Status),
++ 		"seconds": info.Elapsed().Seconds(), "cost_usd": cost,
++ 	}})
++ 	s.changed()
++ 	s.pump()
++ }
++ // Snapshot is every subagent this session has spawned, in spawn order.
++ func (s *Supervisor) Snapshot() []Info {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	out := make([]Info, 0, len(s.order))
++ 	for _, c := range s.order {
++ 		out = append(out, c.info)
++ 	}
++ 	return out
++ }
++ // Info is one subagent by id.
++ func (s *Supervisor) Info(id string) (Info, bool) {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	c, ok := s.byID[id]
++ 	if !ok {
++ 		return Info{}, false
++ 	}
++ 	return c.info, true
++ }
++ // Live is how many subagents are still going, for the status line.
++ func (s *Supervisor) Live() int {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	var n int
++ 	for _, c := range s.order {
++ 		if c.info.Status.Live() {
++ 			n++
++ 		}
++ 	}
++ 	return n
++ }
++ // TakeReports hands over the finished agents the parent has not been told
++ // about, and forgets them. The caller is expected to deliver every one.
++ func (s *Supervisor) TakeReports() []Info {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	out := s.reports
++ 	s.reports = nil
++ 	return out
++ }
++ func (s *Supervisor) lookupLive(id, verb string) (*child, error) {
++ 	c, ok := s.byID[id]
++ 	if !ok {
++ 		return nil, fmt.Errorf("no subagent %q. Check the id you were given when you spawned it", id)
++ 	}
++ 	if !c.info.Status.Live() {
++ 		return nil, fmt.Errorf("subagent %s has already finished (%s), so it cannot be %s", id, c.info.Status, verb)
++ 	}
++ 	return c, nil
++ }
++ // Pause holds a subagent at its next turn boundary.
++ func (s *Supervisor) Pause(id string) error {
++ 	s.mu.Lock()
++ 	c, err := s.lookupLive(id, "paused")
++ 	if err != nil {
++ 		s.mu.Unlock()
++ 		return err
++ 	}
++ 	if c.info.Status == Paused {
++ 		s.mu.Unlock()
++ 		return nil
++ 	}
++ 	if c.info.Status == Queued {
++ 		// There is nothing to hold, and saying "paused" about an agent that
++ 		// was never running would be a lie in the sidebar.
++ 		s.mu.Unlock()
++ 		return fmt.Errorf("subagent %s has not started yet — it is queued behind the ones running. Stop it if you do not want it to run", id)
++ 	}
++ 	// Marked before the turn in flight has finished, so the sidebar says what
++ 	// was asked for rather than lagging a whole turn behind it. pauseWanted
++ 	// covers the moment between getting a slot and having an agent to hold.
++ 	c.pauseWanted = true
++ 	c.info.Status = Paused
++ 	ag := c.ag
++ 	s.mu.Unlock()
++ 	if ag != nil {
++ 		ag.Pause()
++ 	}
++ 	s.changed()
++ 	return nil
++ }
++ // Resume lets a paused subagent carry on.
++ func (s *Supervisor) Resume(id string) error {
++ 	s.mu.Lock()
++ 	c, err := s.lookupLive(id, "resumed")
++ 	if err != nil {
++ 		s.mu.Unlock()
++ 		return err
++ 	}
++ 	c.pauseWanted = false
++ 	if c.info.Status == Paused {
++ 		c.info.Status = Running
++ 	}
++ 	ag := c.ag
++ 	s.mu.Unlock()
++ 	if ag != nil {
++ 		ag.Resume()
++ 	}
++ 	s.changed()
++ 	return nil
++ }
++ // Kill stops a subagent now. Whatever it has already done to the working tree
++ // stays done — this ends the agent, it does not undo it.
++ func (s *Supervisor) Kill(id string) error {
++ 	s.mu.Lock()
++ 	c, err := s.lookupLive(id, "stopped")
++ 	if err != nil {
++ 		s.mu.Unlock()
++ 		return err
++ 	}
++ 	c.killed = true
++ 	cancel := c.cancel
++ 	neverStarted := c.info.Status == Queued
++ 	if neverStarted {
++ 		// Nothing is running to notice the cancellation, so this is where it
++ 		// ends: recorded, reported, and out of the queue.
++ 		c.info.Status = Killed
++ 		c.info.Ended = time.Now()
++ 		s.reports = append(s.reports, c.info)
++ 		close(c.done)
++ 	}
++ 	s.mu.Unlock()
++ 	if cancel != nil {
++ 		cancel()
++ 	}
++ 	s.opts.Log.Log(metrics.Event{Type: "subagent_killed", Extra: map[string]any{"agent": id}})
++ 	s.changed()
++ 	if neverStarted {
++ 		s.pump()
++ 	}
++ 	return nil
++ }
++ // Wait blocks until a subagent finishes and returns how it ended. The context
++ // is the caller's — interrupting the turn that is waiting does not kill the
++ // agent it was waiting for.
++ func (s *Supervisor) Wait(ctx context.Context, id string) (Info, error) {
++ 	s.mu.Lock()
++ 	c, ok := s.byID[id]
++ 	s.mu.Unlock()
++ 	if !ok {
++ 		return Info{}, fmt.Errorf("no subagent %q. Check the id you were given when you spawned it", id)
++ 	}
++ 	select {
++ 	case <-c.done:
++ 	case <-ctx.Done():
++ 		return Info{}, ctx.Err()
++ 	}
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	return c.info, nil
++ }
++ // ClaimReport asks for the right to give one finished agent's report to the
++ // parent, and reports whether the caller got it. Exactly one caller ever does.
++ //
++ // Two of them compete, and which one arrives first is a race nobody can
++ // arrange: agent_wait, which returns the report as its tool result, and the
++ // front end, which puts it into the conversation as a message. Claiming is the
++ // handover itself rather than a flag either side reads from a copy — a copy
++ // taken before the other side acted is exactly how the same report used to be
++ // handed over twice.
++ func (s *Supervisor) ClaimReport(id string) bool {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	c, ok := s.byID[id]
++ 	// An agent still working has nothing to hand over yet.
++ 	if !ok || c.info.Status.Live() || c.delivered {
++ 		return false
++ 	}
++ 	c.delivered = true
++ 	return true
++ }
++ // Shutdown kills every subagent and waits for them to unwind. It is what
++ // leaving the harness does: an agent outliving the session it belongs to would
++ // keep editing a tree nobody is watching.
++ func (s *Supervisor) Shutdown() {
++ 	s.mu.Lock()
++ 	var cancels []context.CancelFunc
++ 	for _, c := range s.order {
++ 		if !c.info.Status.Live() {
++ 			continue
++ 		}
++ 		c.killed = true
++ 		if c.cancel != nil {
++ 			cancels = append(cancels, c.cancel)
++ 			continue
++ 		}
++ 		// Queued and never started: nothing will report it, so record it here.
++ 		c.info.Status = Killed
++ 		c.info.Ended = time.Now()
++ 		close(c.done)
++ 	}
++ 	s.mu.Unlock()
++ 	for _, cancel := range cancels {
++ 		cancel()
++ 	}
++ 	s.wg.Wait()
++ }
++ // approver routes a child's approval requests through the session's policy,
++ // tagged with the agent asking, and marks the agent as waiting while a human
++ // decides. Several agents can be waiting at once; the UI queues them.
++ type approver struct {
++ 	sup *Supervisor
++ 	id  string
++ }
++ func (a approver) Approve(ctx context.Context, tool string, input json.RawMessage) error {
++ 	a.sup.setWaiting(a.id, true)
++ 	defer a.sup.setWaiting(a.id, false)
++ 	return a.sup.opts.Policy.ApproveAs(ctx, a.id, tool, input)
++ }
++ func (s *Supervisor) setWaiting(id string, waiting bool) {
++ 	s.mu.Lock()
++ 	c := s.byID[id]
++ 	if c == nil {
++ 		s.mu.Unlock()
++ 		return
++ 	}
++ 	switch {
++ 	case waiting && c.info.Status == Running:
++ 		c.info.Status = Waiting
++ 	case !waiting && c.info.Status == Waiting:
++ 		c.info.Status = Running
++ 	default:
++ 		// Paused, killed, or already finished: an approval coming or going
++ 		// does not get to overwrite that.
++ 		s.mu.Unlock()
++ 		return
++ 	}
++ 	s.mu.Unlock()
++ 	s.changed()
++ }
++ func addUsage(a, b llm.Usage) llm.Usage {
++ 	a.InputTokens += b.InputTokens
++ 	a.OutputTokens += b.OutputTokens
++ 	a.CacheReadInputTokens += b.CacheReadInputTokens
++ 	a.CacheCreationInputTokens += b.CacheCreationInputTokens
++ 	return a
++ }

+511−0internal/subagent/supervisor_test.goaddedView File

++ package subagent
++ import (
++ 	"bytes"
++ 	"context"
++ 	"encoding/json"
++ 	"io"
++ 	"net/http"
++ 	"net/http/httptest"
++ 	"sort"
++ 	"strings"
++ 	"sync"
++ 	"testing"
++ 	"time"
++ 	"harness/internal/agent"
++ 	"harness/internal/llm"
++ 	"harness/internal/metrics"
++ 	"harness/internal/tools"
++ )
++ // settle is how long a test waits before concluding nothing more is coming.
++ const settle = 150 * time.Millisecond
++ // fakeAPI answers every child's request. What it answers is derived from the
++ // task the child was given, so a test can tell two agents' traffic apart.
++ type fakeAPI struct {
++ 	mu       sync.Mutex
++ 	requests int
++ 	models   []string
++ 	// bodies is every request body, for asking what a child actually sent.
++ 	bodies [][]byte
++ 	// gate, when non-nil, holds every request until it is closed: the way a
++ 	// test keeps an agent running while it inspects the supervisor.
++ 	gate chan struct{}
++ 	// status, when non-zero, is returned instead of a response.
++ 	status int
++ 	// twoTurns makes the first answer a tool call, so the agent has a second
++ 	// turn — which is where a pause lands.
++ 	twoTurns bool
++ 	// callTool makes the first answer a call to a named tool, for asking what
++ 	// happens when a child reaches for one it does not have.
++ 	callTool string
++ 	srv      *httptest.Server
++ }
++ func newFakeAPI(t *testing.T) *fakeAPI {
++ 	t.Helper()
++ 	f := &fakeAPI{}
++ 	f.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		body, _ := io.ReadAll(r.Body)
++ 		var req llm.Request
++ 		json.Unmarshal(body, &req)
++ 		f.mu.Lock()
++ 		f.requests++
++ 		f.models = append(f.models, req.Model)
++ 		f.bodies = append(f.bodies, body)
++ 		gate, status := f.gate, f.status
++ 		f.mu.Unlock()
++ 		if gate != nil {
++ 			<-gate
++ 		}
++ 		if status != 0 {
++ 			w.WriteHeader(status)
++ 			io.WriteString(w, `{"type":"error","error":{"type":"overloaded_error","message":"nope"}}`)
++ 			return
++ 		}
++ 		f.mu.Lock()
++ 		two := f.twoTurns
++ 		f.mu.Unlock()
++ 		f.mu.Lock()
++ 		named := f.callTool
++ 		f.mu.Unlock()
++ 		if len(req.Messages) == 1 {
++ 			switch {
++ 			case named != "":
++ 				io.WriteString(w, toolUse("tu_1", named))
++ 				return
++ 			case two:
++ 				io.WriteString(w, toolUse("tu_1", "noop"))
++ 				return
++ 			}
++ 		}
++ 		io.WriteString(w, endTurn("handled: "+task(req)))
++ 	}))
++ 	t.Cleanup(f.srv.Close)
++ 	return f
++ }
++ func (f *fakeAPI) hold() { f.mu.Lock(); f.gate = make(chan struct{}); f.mu.Unlock() }
++ func (f *fakeAPI) release() {
++ 	f.mu.Lock()
++ 	gate := f.gate
++ 	f.gate = nil
++ 	f.mu.Unlock()
++ 	if gate != nil {
++ 		close(gate)
++ 	}
++ }
++ func (f *fakeAPI) fail(status int) { f.mu.Lock(); f.status = status; f.mu.Unlock() }
++ func (f *fakeAPI) count() int      { f.mu.Lock(); defer f.mu.Unlock(); return f.requests }
++ // requestsSeen decodes every request the fake was sent.
++ func (f *fakeAPI) requestsSeen(t *testing.T) []llm.Request {
++ 	t.Helper()
++ 	f.mu.Lock()
++ 	defer f.mu.Unlock()
++ 	out := make([]llm.Request, 0, len(f.bodies))
++ 	for _, b := range f.bodies {
++ 		var req llm.Request
++ 		if err := json.Unmarshal(b, &req); err != nil {
++ 			t.Fatalf("request body does not decode: %v", err)
++ 		}
++ 		out = append(out, req)
++ 	}
++ 	return out
++ }
++ // effortSent is the effort level the one request carried, or "" for none.
++ func (f *fakeAPI) effortSent(t *testing.T) string {
++ 	t.Helper()
++ 	reqs := f.requestsSeen(t)
++ 	if len(reqs) != 1 {
++ 		t.Fatalf("want exactly one request, got %d", len(reqs))
++ 	}
++ 	if reqs[0].OutputConfig == nil {
++ 		return ""
++ 	}
++ 	return reqs[0].OutputConfig.Effort
++ }
++ func (f *fakeAPI) modelsSeen() []string {
++ 	f.mu.Lock()
++ 	defer f.mu.Unlock()
++ 	return append([]string(nil), f.models...)
++ }
++ // task pulls the first user message out of a request: the brief the child was
++ // spawned on.
++ func task(req llm.Request) string {
++ 	for _, m := range req.Messages {
++ 		if m.Role == llm.RoleUser && len(m.Content) > 0 {
++ 			return m.Content[0].Text
++ 		}
++ 	}
++ 	return ""
++ }
++ func toolUse(id, name string) string {
++ 	return `{"id":"msg","type":"message","role":"assistant","model":"m","content":[` +
++ 		`{"type":"tool_use","id":"` + id + `","name":"` + name + `","input":{}}],` +
++ 		`"stop_reason":"tool_use","usage":{"input_tokens":100,"output_tokens":20}}`
++ }
++ func endTurn(text string) string {
++ 	b, _ := json.Marshal(text)
++ 	return `{"id":"msg","type":"message","role":"assistant","model":"m","content":[{"type":"text","text":` +
++ 		string(b) + `}],"stop_reason":"end_turn","usage":{"input_tokens":100,"output_tokens":20}}`
++ }
++ func newSupervisor(t *testing.T, f *fakeAPI, opts ...func(*Options)) *Supervisor {
++ 	t.Helper()
++ 	log := metrics.NewWriter(&bytes.Buffer{}, "test")
++ 	root := t.TempDir()
++ 	o := Options{
++ 		Client: llm.New(llm.WithBaseURL(f.srv.URL), llm.WithAPIKey("k"), llm.WithModel("claude-opus-5")),
++ 		Log:    log,
++ 		Tools: func(state *agent.State, log *metrics.Logger) *tools.Registry {
++ 			return tools.NewRegistry(log).Register(
++ 				tools.NewRead(root, state),
++ 				tools.New("noop", "does nothing", func(context.Context, struct{}) (string, error) {
++ 					return "ok", nil
++ 				}),
++ 			)
++ 		},
++ 	}
++ 	for _, fn := range opts {
++ 		fn(&o)
++ 	}
++ 	s := New(context.Background(), o)
++ 	t.Cleanup(s.Shutdown)
++ 	return s
++ }
++ // waitFor polls until cond holds, so tests do not race the goroutines they are
++ // watching. It fails rather than hanging.
++ func waitFor(t *testing.T, what string, cond func() bool) {
++ 	t.Helper()
++ 	deadline := time.Now().Add(3 * time.Second)
++ 	for time.Now().Before(deadline) {
++ 		if cond() {
++ 			return
++ 		}
++ 		time.Sleep(5 * time.Millisecond)
++ 	}
++ 	t.Fatalf("timed out waiting for %s", what)
++ }
++ func statusOf(t *testing.T, s *Supervisor, id string) Status {
++ 	t.Helper()
++ 	info, ok := s.Info(id)
++ 	if !ok {
++ 		t.Fatalf("no agent %q", id)
++ 	}
++ 	return info.Status
++ }
++ func TestSpawnRunsTheAgentAndKeepsItsReport(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, err := s.Spawn(Spec{Preset: "explore", Task: "find the approval policy"})
++ 	if err != nil {
++ 		t.Fatalf("Spawn: %v", err)
++ 	}
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	info, _ := s.Info(id)
++ 	if info.Report != "handled: find the approval policy" {
++ 		t.Errorf("report = %q, want the agent's final text", info.Report)
++ 	}
++ 	if info.Preset != "explore" || info.Task != "find the approval policy" {
++ 		t.Errorf("info = %+v, want the preset and task it was spawned with", info)
++ 	}
++ 	if info.Turns != 1 {
++ 		t.Errorf("turns = %d, want 1", info.Turns)
++ 	}
++ 	if info.Usage.OutputTokens != 20 {
++ 		t.Errorf("usage = %+v, want the child's token counts", info.Usage)
++ 	}
++ 	if info.Ended.IsZero() || info.Ended.Before(info.Started) {
++ 		t.Errorf("started %v, ended %v", info.Started, info.Ended)
++ 	}
++ }
++ // Ids are what the sidebar shows and what the model says back to you, so they
++ // are short and in spawn order rather than random.
++ func TestIDsAreShortAndInSpawnOrder(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	first, _ := s.Spawn(Spec{Preset: "explore", Task: "one"})
++ 	second, _ := s.Spawn(Spec{Preset: "plan", Task: "two"})
++ 	if first != "a1" || second != "a2" {
++ 		t.Errorf("ids = %q, %q; want a1, a2", first, second)
++ 	}
++ 	got := []string{}
++ 	for _, info := range s.Snapshot() {
++ 		got = append(got, info.ID)
++ 	}
++ 	if strings.Join(got, " ") != "a1 a2" {
++ 		t.Errorf("snapshot order = %v, want spawn order", got)
++ 	}
++ }
++ // A preset the model made up must come back as something it can act on, not as
++ // a silent no-op or a crash.
++ func TestUnknownPresetNamesTheOnesThatExist(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	_, err := s.Spawn(Spec{Preset: "researcher", Task: "go"})
++ 	if err == nil {
++ 		t.Fatal("spawning an unknown preset succeeded")
++ 	}
++ 	for _, p := range Presets() {
++ 		if !strings.Contains(err.Error(), p.Name) {
++ 			t.Errorf("error %q does not offer the %q preset", err, p.Name)
++ 		}
++ 	}
++ 	if len(s.Snapshot()) != 0 {
++ 		t.Error("a rejected spawn still created an agent")
++ 	}
++ }
++ // No preset pins a model: the agent doing the spawning picks one for the job,
++ // and a spawn that names none runs on the session's own model rather than on
++ // something the harness chose for it.
++ func TestTheSpawningAgentChoosesTheModel(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	unnamed, _ := s.Spawn(Spec{Preset: "explore", Task: "one"})
++ 	chosen, _ := s.Spawn(Spec{Preset: "explore", Task: "two", Model: "claude-haiku-4-5"})
++ 	waitFor(t, "both agents to finish", func() bool {
++ 		return statusOf(t, s, unnamed) == Done && statusOf(t, s, chosen) == Done
++ 	})
++ 	first, _ := s.Info(unnamed)
++ 	second, _ := s.Info(chosen)
++ 	if first.Model != "claude-opus-5" {
++ 		t.Errorf("a spawn naming no model ran on %q, want the session's", first.Model)
++ 	}
++ 	if second.Model != "claude-haiku-4-5" {
++ 		t.Errorf("the chosen model was %q", second.Model)
++ 	}
++ 	// Both agents run at once, so which request arrives first is not
++ 	// something to assert on — only that each asked for its own model.
++ 	models := f.modelsSeen()
++ 	sort.Strings(models)
++ 	want := []string{"claude-haiku-4-5", "claude-opus-5"}
++ 	if strings.Join(models, " ") != strings.Join(want, " ") {
++ 		t.Errorf("requests asked for %v, want %v", models, want)
++ 	}
++ }
++ // An agent whose model call fails is finished, not stuck: the status says so
++ // and the reason is kept for the parent to be told.
++ func TestAFailedAgentIsRecordedAsFailed(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.fail(http.StatusBadRequest)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to fail", func() bool { return statusOf(t, s, id) == Failed })
++ 	info, _ := s.Info(id)
++ 	if info.Err == "" {
++ 		t.Error("a failed agent kept no reason")
++ 	}
++ 	if info.Ended.IsZero() {
++ 		t.Error("a failed agent never ended")
++ 	}
++ }
++ // Every event a child produces reaches the front end tagged with the agent it
++ // came from, because they all land in one UI.
++ func TestEventsAreTaggedWithTheAgent(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	var mu sync.Mutex
++ 	var seen []Event
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Observe = func(ev Event) {
++ 			mu.Lock()
++ 			defer mu.Unlock()
++ 			seen = append(seen, ev)
++ 		}
++ 	})
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	mu.Lock()
++ 	defer mu.Unlock()
++ 	if len(seen) == 0 {
++ 		t.Fatal("no events were observed")
++ 	}
++ 	for _, ev := range seen {
++ 		if ev.ID != id {
++ 			t.Fatalf("event %+v is not tagged with %q", ev, id)
++ 		}
++ 		if ev.Preset != "explore" {
++ 			t.Fatalf("event %+v does not name the preset", ev)
++ 		}
++ 	}
++ }
++ // How hard a subagent thinks is the other half of what it costs, so the agent
++ // spawning it chooses that too.
++ func TestTheChosenEffortReachesTheChild(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f, func(o *Options) { o.Base.Effort = "high" })
++ 	id, err := s.Spawn(Spec{Preset: "explore", Task: "go", Model: "claude-opus-5", Effort: "low"})
++ 	if err != nil {
++ 		t.Fatalf("Spawn: %v", err)
++ 	}
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	if got := f.effortSent(t); got != "low" {
++ 		t.Errorf("the child asked for effort %q, want the level it was spawned with", got)
++ 	}
++ 	if info, _ := s.Info(id); info.Effort != "low" {
++ 		t.Errorf("Info.Effort = %q", info.Effort)
++ 	}
++ }
++ // Choosing nothing inherits the session's level, the way it always did.
++ func TestASpawnWithNoEffortInheritsTheSessions(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f, func(o *Options) { o.Base.Effort = "xhigh" })
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go", Model: "claude-opus-5"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	if got := f.effortSent(t); got != "xhigh" {
++ 		t.Errorf("the child asked for effort %q, want the session's", got)
++ 	}
++ }
++ // A level that is not a level is a typo, and the model needs to be told which
++ // words exist rather than watching an agent run at something else.
++ func TestAnUnknownEffortLevelIsRefused(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	_, err := s.Spawn(Spec{Preset: "explore", Task: "go", Effort: "lowest"})
++ 	if err == nil {
++ 		t.Fatal("an unknown effort level was accepted")
++ 	}
++ 	for _, level := range llm.EffortLevels {
++ 		if !strings.Contains(err.Error(), level) {
++ 			t.Errorf("error %q does not offer %q", err, level)
++ 		}
++ 	}
++ 	if len(s.Snapshot()) != 0 {
++ 		t.Error("a rejected spawn still created an agent")
++ 	}
++ }
++ // Haiku takes no effort level at all. The spawn is still a good spawn — the
++ // model picked a cheap model for a cheap job — so it runs, and the answer says
++ // plainly that the level was not applied rather than implying it was.
++ func TestEffortOnAModelThatCannotTakeItIsRunAndReported(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, err := s.Spawn(Spec{Preset: "explore", Task: "go", Model: "claude-haiku-4-5", Effort: "low"})
++ 	if err != nil {
++ 		t.Fatalf("Spawn: %v", err)
++ 	}
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	if got := f.effortSent(t); got != "" {
++ 		t.Errorf("the child sent effort %q to a model that rejects it", got)
++ 	}
++ 	info, _ := s.Info(id)
++ 	if info.Effort != "" {
++ 		t.Errorf("Info.Effort = %q, want empty — the level is not in force", info.Effort)
++ 	}
++ }
++ // A borrowed Claude Code credential is only accepted alongside its identity
++ // block: a request without it comes back 429, which reads like a quota problem
++ // and is not one. Subagents authenticate with the same credential, so they
++ // carry the same block — and they get their own system prompt, which is
++ // exactly where it could have been dropped.
++ func TestASubagentCarriesTheIdentityBlockOfItsSession(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Base.SystemPrefix = agent.ClaudeCodeIdentity
++ 	})
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	reqs := f.requestsSeen(t)
++ 	if len(reqs) != 1 {
++ 		t.Fatalf("saw %d requests", len(reqs))
++ 	}
++ 	blocks := reqs[0].System
++ 	if len(blocks) < 2 {
++ 		t.Fatalf("the child sent %d system blocks, want the identity block and its own prompt", len(blocks))
++ 	}
++ 	if blocks[0].Text != agent.ClaudeCodeIdentity {
++ 		t.Errorf("the first system block is %q, want the identity string", blocks[0].Text)
++ 	}
++ 	if !strings.Contains(blocks[1].Text, "You are a subagent") {
++ 		t.Errorf("the child's own brief is missing:\n%s", blocks[1].Text)
++ 	}
++ }
++ // Children authenticate exactly as the session does, including a credential
++ // that is resolved per request and may need refreshing — one source, shared,
++ // rather than a copy per agent that refreshes on its own.
++ func TestChildrenAuthenticateThroughTheSessionsCredential(t *testing.T) {
++ 	var mu sync.Mutex
++ 	var calls int
++ 	var bearers []string
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		mu.Lock()
++ 		bearers = append(bearers, r.Header.Get("authorization"))
++ 		mu.Unlock()
++ 		io.WriteString(w, endTurn("ok"))
++ 	}))
++ 	t.Cleanup(srv.Close)
++ 	client := llm.New(llm.WithBaseURL(srv.URL), llm.WithTokenSource(func(context.Context) (string, error) {
++ 		mu.Lock()
++ 		defer mu.Unlock()
++ 		calls++
++ 		return "borrowed-token", nil
++ 	}))
++ 	log := metrics.NewWriter(&bytes.Buffer{}, "test")
++ 	root := t.TempDir()
++ 	s := New(context.Background(), Options{
++ 		Client: client,
++ 		Log:    log,
++ 		Tools: func(state *agent.State, log *metrics.Logger) *tools.Registry {
++ 			return tools.NewRegistry(log).Register(tools.NewRead(root, state))
++ 		},
++ 	})
++ 	t.Cleanup(s.Shutdown)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	mu.Lock()
++ 	defer mu.Unlock()
++ 	if calls == 0 {
++ 		t.Fatal("the child never asked the session's token source for a credential")
++ 	}
++ 	for _, b := range bearers {
++ 		if b != "Bearer borrowed-token" {
++ 			t.Errorf("the child sent authorization %q", b)
++ 		}
++ 	}
++ }

+107−0internal/subagent/tools.goaddedView File

++ package subagent
++ import (
++ 	"context"
++ 	"fmt"
++ 	"strings"
++ 	"harness/internal/tools"
++ )
++ // spawnArgs is what the model sends to start an agent.
++ type spawnArgs struct {
++ 	Preset string `json:"preset" jsonschema:"description=Which kind of agent to start. See the list in this tool's description."`
++ 	Task   string `json:"task" jsonschema:"description=The complete brief for the agent: what to do and what to report back. It cannot ask you questions and it cannot see this conversation, so everything it needs has to be in here — the paths you already know, what you have tried, what the answer should look like."`
++ 	Effort string `json:"effort,omitempty" jsonschema:"description=How hard it should think: low, medium, high, xhigh or max. Low is right for mechanical work — searching, listing, reading something back; reach higher when the answer has to be right. Leave it out to use this session's level. Some models take no effort level at all, and then this is ignored and the answer says so."`
++ 	Model  string `json:"model,omitempty" jsonschema:"description=Which model to run it on. Pick one that suits the job — a small fast model for mechanical search, a strong one for design or code that has to be right. Leave it out to use this session's model, which is the safe answer when you do not know what this endpoint serves."`
++ }
++ type waitArgs struct {
++ 	ID string `json:"id" jsonschema:"description=The agent id returned by spawn_agent, such as a1."`
++ }
++ // Tools are the tools the parent agent gets. Subagents are built from the
++ // caller's own registry factory and never see these, which is what stops an
++ // agent from spawning agents that spawn agents.
++ func (s *Supervisor) Tools() []tools.Tool {
++ 	return []tools.Tool{
++ 		tools.New("spawn_agent", spawnDescription(), func(_ context.Context, in spawnArgs) (string, error) {
++ 			// The context is deliberately ignored: it belongs to the turn that
++ 			// is spawning, and the agent has to outlive that turn. Children
++ 			// descend from the supervisor's own context instead.
++ 			id, err := s.Spawn(Spec{Preset: in.Preset, Task: in.Task, Model: in.Model, Effort: in.Effort})
++ 			if err != nil {
++ 				return "", err
++ 			}
++ 			info, _ := s.Info(id)
++ 			var note string
++ 			switch {
++ 			case info.Effort != "":
++ 				note = " at " + info.Effort + " effort"
++ 			case in.Effort != "":
++ 				// Asked for, and dropped: that model takes no effort level,
++ 				// and letting the parent believe otherwise would be worse
++ 				// than refusing the spawn.
++ 				note = fmt.Sprintf(" — %s takes no effort level, so %q was not applied", info.Model, in.Effort)
++ 			}
++ 			return fmt.Sprintf("started %s (%s) on %s%s, status %s. It runs in the background: carry on, "+
++ 				"and its report will arrive as a message when it finishes. Call agent_wait(%q) only if "+
++ 				"you cannot do anything useful until then.", id, info.Preset, info.Model, note, info.Status, id), nil
++ 		}),
++ 		tools.New("agent_wait", "Block until a subagent finishes and return its report. Use this only when "+
++ 			"you genuinely cannot proceed without the answer — a finished agent's report reaches you on its "+
++ 			"own, and waiting spends this turn doing nothing.",
++ 			func(ctx context.Context, in waitArgs) (string, error) {
++ 				info, err := s.Wait(ctx, in.ID)
++ 				if err != nil {
++ 					return "", err
++ 				}
++ 				// Whoever hands the report over claims it. Losing the claim
++ 				// means the front end has already put it into the
++ 				// conversation, so all this has to do is point at it.
++ 				if !s.ClaimReport(info.ID) {
++ 					return info.AlreadyDelivered(), nil
++ 				}
++ 				return info.Notification(), nil
++ 			}),
++ 	}
++ }
++ // spawnDescription is built from the presets so the two cannot drift apart.
++ func spawnDescription() string {
++ 	var b strings.Builder
++ 	b.WriteString(`Start a subagent to do a piece of work on its own, in the background.
++ A subagent has its own context window and its own conversation: it sees the
++ task you give it and nothing else, and you see its final report and nothing
++ else. That is what makes it worth using — a search that would fill your context
++ with file listings fills its instead, and comes back a paragraph long. Spawn
++ one for work that is self-contained and describable in writing; do the rest
++ yourself, because a task you have to explain at length is quicker to do.
++ Several can run at once, and you can keep working while they do. Their reports
++ arrive as messages when they finish. Subagents cannot spawn subagents, and each
++ spawn is shown to the user to approve before it starts.
++ You choose the model and the effort. The preset says what kind of job it is;
++ what to spend on it is your call, and those two are what decide what a subagent
++ costs.
++ Use the newest model listed in your system prompt unless the user asked for a
++ different one, or that model has already failed for you this session. Omit the
++ model and it runs on this session's, which is the right answer when nothing was
++ listed; an id this endpoint does not serve fails that agent with the API's own
++ error before its first turn.
++ Effort is the other half: low for mechanical work, higher when the answer has
++ to be right rather than quick. Omit it and the agent runs at this session's
++ level. Not every model has one — Haiku 4.5 takes none at all — and where it
++ does not, the level is dropped and the answer tells you so.
++ The presets:`)
++ 	for _, p := range presets {
++ 		fmt.Fprintf(&b, "\n  %s — %s", p.Name, p.Description)
++ 	}
++ 	return b.String()
++ }

+281−0internal/subagent/tools_test.goaddedView File

++ package subagent
++ import (
++ 	"context"
++ 	"encoding/json"
++ 	"strings"
++ 	"sync"
++ 	"testing"
++ 	"time"
++ 	"harness/internal/agent"
++ 	"harness/internal/tools"
++ )
++ func toolNamed(t *testing.T, s *Supervisor, name string) tools.Tool {
++ 	t.Helper()
++ 	for _, tool := range s.Tools() {
++ 		if tool.Name() == name {
++ 			return tool
++ 		}
++ 	}
++ 	t.Fatalf("no %s tool", name)
++ 	return nil
++ }
++ func TestTheParentGetsSpawnAndWaitAndNothingElse(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	var names []string
++ 	for _, tool := range s.Tools() {
++ 		names = append(names, tool.Name())
++ 	}
++ 	if strings.Join(names, " ") != "spawn_agent agent_wait" {
++ 		t.Errorf("tools = %v", names)
++ 	}
++ }
++ // The description is what the model chooses a preset from, so every preset has
++ // to be in it — and so does the rule that subagents cannot spawn subagents,
++ // which it would otherwise discover by trying.
++ func TestTheSpawnDescriptionExplainsThePresetsAndTheRules(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	desc := toolNamed(t, s, "spawn_agent").Description()
++ 	for _, p := range Presets() {
++ 		if !strings.Contains(desc, p.Name) {
++ 			t.Errorf("description never mentions the %q preset", p.Name)
++ 		}
++ 	}
++ 	for _, phrase := range []string{"background", "approve", "cannot spawn"} {
++ 		if !strings.Contains(strings.ToLower(desc), phrase) {
++ 			t.Errorf("description never says %q:\n%s", phrase, desc)
++ 		}
++ 	}
++ }
++ func TestSpawnToolReturnsTheIDToReferToItBy(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	out, err := toolNamed(t, s, "spawn_agent").Execute(context.Background(),
++ 		json.RawMessage(`{"preset":"explore","task":"find the policy"}`))
++ 	if err != nil {
++ 		t.Fatalf("spawn_agent: %v", err)
++ 	}
++ 	if !strings.Contains(out, "a1") {
++ 		t.Errorf("spawn_agent returned %q, which does not name the agent", out)
++ 	}
++ 	f.release()
++ }
++ func TestSpawnToolReportsAnUnknownPresetToTheModel(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	_, err := toolNamed(t, s, "spawn_agent").Execute(context.Background(),
++ 		json.RawMessage(`{"preset":"researcher","task":"go"}`))
++ 	if err == nil {
++ 		t.Fatal("an unknown preset was accepted")
++ 	}
++ 	if !strings.Contains(err.Error(), "explore") {
++ 		t.Errorf("error %q does not offer a preset that exists", err)
++ 	}
++ }
++ // The spawning tool call belongs to one turn; the agent it starts does not.
++ // Interrupting that turn — or simply the turn ending — must not take the
++ // subagent with it.
++ func TestASpawnedAgentOutlivesTheTurnThatSpawnedIt(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	ctx, cancel := context.WithCancel(context.Background())
++ 	if _, err := toolNamed(t, s, "spawn_agent").Execute(ctx,
++ 		json.RawMessage(`{"preset":"general","task":"keep going"}`)); err != nil {
++ 		t.Fatalf("spawn_agent: %v", err)
++ 	}
++ 	cancel()
++ 	time.Sleep(settle)
++ 	if got := statusOf(t, s, "a1"); !got.Live() {
++ 		t.Fatalf("the agent is %s after the spawning turn ended", got)
++ 	}
++ 	f.release()
++ 	waitFor(t, "the agent to finish anyway", func() bool { return statusOf(t, s, "a1") == Done })
++ }
++ func TestAgentWaitHandsBackTheReport(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	out, err := toolNamed(t, s, "agent_wait").Execute(context.Background(),
++ 		json.RawMessage(`{"id":"`+id+`"}`))
++ 	if err != nil {
++ 		t.Fatalf("agent_wait: %v", err)
++ 	}
++ 	if !strings.Contains(out, "handled: find it") {
++ 		t.Errorf("agent_wait returned %q, want the agent's report", out)
++ 	}
++ }
++ func TestAgentWaitOnAnUnknownIDIsAnError(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	_, err := toolNamed(t, s, "agent_wait").Execute(context.Background(), json.RawMessage(`{"id":"a9"}`))
++ 	if err == nil {
++ 		t.Fatal("waiting on an unknown agent succeeded")
++ 	}
++ }
++ // Nesting is the way a spawn loop becomes a fork bomb with a credit card. A
++ // subagent's tool set simply does not contain the spawn tools, and calling one
++ // comes back as an ordinary unknown-tool error it can read.
++ func TestASubagentCannotSpawnSubagents(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.callTool = "spawn_agent"
++ 	var mu sync.Mutex
++ 	var errors []string
++ 	s := newSupervisor(t, f, func(o *Options) {
++ 		o.Observe = func(ev Event) {
++ 			if ev.Agent.Kind == agent.EventToolResult && ev.Agent.IsError {
++ 				mu.Lock()
++ 				errors = append(errors, ev.Agent.Result)
++ 				mu.Unlock()
++ 			}
++ 		}
++ 	})
++ 	id, _ := s.Spawn(Spec{Preset: "general", Task: "go"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	mu.Lock()
++ 	defer mu.Unlock()
++ 	if len(errors) != 1 || !strings.Contains(errors[0], "unknown tool") {
++ 		t.Fatalf("a subagent's spawn attempt produced %v", errors)
++ 	}
++ 	if n := len(s.Snapshot()); n != 1 {
++ 		t.Errorf("%d agents exist; the subagent managed to spawn one", n)
++ 	}
++ }
++ // The model is the main thing that decides what a subagent costs, and nothing
++ // else picks it any more — so the description has to say how to choose. It
++ // names no ids of its own: what this endpoint serves is in the system prompt,
++ // and a list in two places is a list that goes out of step.
++ func TestTheSpawnDescriptionExplainsHowToChooseAModel(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	desc := toolNamed(t, s, "spawn_agent").Description()
++ 	for _, phrase := range []string{"you choose the model", "newest model", "system prompt"} {
++ 		if !strings.Contains(strings.ToLower(desc), phrase) {
++ 			t.Errorf("the description never says %q:\n%s", phrase, desc)
++ 		}
++ 	}
++ 	if strings.Contains(desc, "claude-") {
++ 		t.Errorf("the description hardcodes a model id, which will drift from what the endpoint serves:\n%s", desc)
++ 	}
++ 	// And it must not promise a model per preset, which is what it used to do.
++ 	for _, p := range Presets() {
++ 		line := p.Name + " — " + p.Description
++ 		if !strings.Contains(desc, line) {
++ 			t.Errorf("preset line missing or changed shape: %q", line)
++ 		}
++ 	}
++ }
++ // Waiting on an agent whose report the front end has already put into the
++ // conversation returns a pointer to it, not the text again: the parent is
++ // paying for context, and it already has this.
++ func TestWaitingOnAnAlreadyDeliveredReportDoesNotRepeatIt(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	waitFor(t, "the agent to finish", func() bool { return statusOf(t, s, id) == Done })
++ 	// The front end delivered it.
++ 	if !s.ClaimReport(id) {
++ 		t.Fatal("could not claim a fresh report")
++ 	}
++ 	out, err := toolNamed(t, s, "agent_wait").Execute(context.Background(), json.RawMessage(`{"id":"`+id+`"}`))
++ 	if err != nil {
++ 		t.Fatalf("agent_wait: %v", err)
++ 	}
++ 	if strings.Contains(out, "handled: find it") {
++ 		t.Errorf("agent_wait repeated a report the conversation already has:\n%s", out)
++ 	}
++ 	for _, want := range []string{id, "already"} {
++ 		if !strings.Contains(out, want) {
++ 			t.Errorf("agent_wait's answer does not say %q:\n%s", want, out)
++ 		}
++ 	}
++ }
++ // And when nobody has delivered it, agent_wait is the delivery.
++ func TestWaitingFirstHandsOverTheWholeReport(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	s := newSupervisor(t, f)
++ 	id, _ := s.Spawn(Spec{Preset: "explore", Task: "find it"})
++ 	out, err := toolNamed(t, s, "agent_wait").Execute(context.Background(), json.RawMessage(`{"id":"`+id+`"}`))
++ 	if err != nil {
++ 		t.Fatalf("agent_wait: %v", err)
++ 	}
++ 	if !strings.Contains(out, "handled: find it") {
++ 		t.Errorf("agent_wait did not hand over the report:\n%s", out)
++ 	}
++ 	if s.ClaimReport(id) {
++ 		t.Error("the front end would send it again after agent_wait delivered it")
++ 	}
++ }
++ // The effort argument is the answer to "spawn these on low", which the tool
++ // could not express before.
++ func TestSpawnToolTakesAnEffortLevel(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	out, err := toolNamed(t, s, "spawn_agent").Execute(context.Background(),
++ 		json.RawMessage(`{"preset":"explore","task":"find it","model":"claude-opus-5","effort":"low"}`))
++ 	if err != nil {
++ 		t.Fatalf("spawn_agent: %v", err)
++ 	}
++ 	if !strings.Contains(out, "low effort") {
++ 		t.Errorf("the answer does not say what it is running at:\n%s", out)
++ 	}
++ 	if info, _ := s.Info("a1"); info.Effort != "low" {
++ 		t.Errorf("Info.Effort = %q", info.Effort)
++ 	}
++ 	f.release()
++ }
++ // Asking for an effort level on a model that has none must not read as though
++ // it worked.
++ func TestSpawnToolSaysWhenTheEffortCouldNotBeApplied(t *testing.T) {
++ 	f := newFakeAPI(t)
++ 	f.hold()
++ 	s := newSupervisor(t, f)
++ 	out, err := toolNamed(t, s, "spawn_agent").Execute(context.Background(),
++ 		json.RawMessage(`{"preset":"explore","task":"find it","model":"claude-haiku-4-5","effort":"low"}`))
++ 	if err != nil {
++ 		t.Fatalf("spawn_agent: %v", err)
++ 	}
++ 	for _, want := range []string{"takes no effort level", "not applied"} {
++ 		if !strings.Contains(out, want) {
++ 			t.Errorf("the answer does not say the level was dropped (%q):\n%s", want, out)
++ 		}
++ 	}
++ 	f.release()
++ }
++ // And the description has to say the knob exists, or nothing will reach for it.
++ func TestTheSpawnDescriptionMentionsEffort(t *testing.T) {
++ 	s := newSupervisor(t, newFakeAPI(t))
++ 	desc := strings.ToLower(toolNamed(t, s, "spawn_agent").Description())
++ 	for _, want := range []string{"effort", "low"} {
++ 		if !strings.Contains(desc, want) {
++ 			t.Errorf("the description never mentions %q", want)
++ 		}
++ 	}
++ }