subagent

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: AGPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package subagent tracks the subagents and agent-team teammates a Claude session has spawned, from the hook events session/hooks collects. See docs/superpowers/specs/2026-09-16-subagent-nesting-design.md.

It has no dependency on tmux, the UI or the app, so every piece can be tested against payloads captured from a real Claude session.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MetaPath

func MetaPath(transcriptPath, agentID string) string

MetaPath returns where Claude writes agentID's sidecar for the session whose transcript is at transcriptPath. It returns "" when either is empty, or when agentID could escape the subagents folder.

func ReadMeta added in v0.14.0

func ReadMeta(events []hooks.Event, missing []MetaRef) map[string]Meta

ReadMeta reads the metadata sidecars for the SubagentStart events in events and for the agents still missing one. An unreadable sidecar is skipped; the tracker keeps the agent hidden and the next scan retries it. It only touches the filesystem, so it is safe to run from a tea.Cmd.

Types

type Meta

type Meta struct {
	AgentType   string `json:"agentType"`
	Name        string `json:"name"`
	Description string `json:"description"`
	TaskKind    string `json:"taskKind"`
}

Meta is the part of Claude's agent-<id>.meta.json sidecar loom reads. Several key sets exist across CLI versions; every field is optional.

func ParseMeta

func ParseMeta(data []byte) (Meta, error)

ParseMeta decodes a metadata sidecar.

func (Meta) DisplayName

func (m Meta) DisplayName() string

DisplayName is the label shown for the agent: its name when it has one, else its agent type.

func (Meta) IsTeammate

func (m Meta) IsTeammate() bool

IsTeammate reports whether the sidecar describes an agent-team teammate, which goes idle after a turn rather than ending.

type MetaRef

type MetaRef struct {
	AgentID string
	Path    string
}

MetaRef locates one agent's sidecar.

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker derives the live agent set from hook events. It is not safe for concurrent use; session.Instance guards it with its own mutex.

func NewTracker

func NewTracker() *Tracker

NewTracker returns an empty tracker.

func (*Tracker) Apply

func (t *Tracker) Apply(events []hooks.Event, meta map[string]Meta)

Apply folds events, in order, into the tracker. meta holds sidecars read since the last call, keyed by agent ID. They are applied to known agents first, so an agent that started and stopped within one batch already has its kind when its SubagentStop is processed.

func (*Tracker) MissingMeta

func (t *Tracker) MissingMeta() []MetaRef

MissingMeta lists agents still waiting for their sidecar, sorted by ID, so the next scan can retry them.

func (*Tracker) Reset

func (t *Tracker) Reset()

Reset forgets every agent. Called at a new launch and before a replay rebuilds state from the full event log.

func (*Tracker) Visible

func (t *Tracker) Visible() []View

Visible returns the agents to render: those with a sidecar, working first, then idle, each group in spawn order. Never nil.

type View

type View struct {
	Name        string
	Description string
	Idle        bool
}

View is one agent as the UI renders it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL