subagents

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Feb 27, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TypeGeneralPurpose = "general-purpose"
	TypeExplore        = "explore"
	TypePlan           = "plan"

	ModelSonnet = "sonnet"
	ModelHaiku  = "haiku"
)
View Source
const DispatchSourceTaskTool = "task_tool"

Variables

View Source
var (
	ErrDuplicateSubagent    = errors.New("subagents: duplicate registration")
	ErrUnknownSubagent      = errors.New("subagents: unknown target")
	ErrNoMatchingSubagent   = errors.New("subagents: no matching subagent")
	ErrEmptyInstruction     = errors.New("subagents: instruction is empty")
	ErrDispatchUnauthorized = errors.New("subagents: dispatch not authorized")
)

Functions

func WithContext

func WithContext(ctx context.Context, subCtx Context) context.Context

WithContext stores the runtime Context inside ctx for downstream consumers.

func WithDispatchSource

func WithDispatchSource(ctx context.Context, source string) context.Context

WithDispatchSource tags ctx with an allowed dispatch origin.

func WithTaskDispatch

func WithTaskDispatch(ctx context.Context) context.Context

WithTaskDispatch marks ctx as originating from the Task tool.

Types

type Context

type Context struct {
	SessionID     string
	Metadata      map[string]any
	ToolWhitelist []string
	Model         string
}

Context stores execution metadata for an individual subagent run.

func FromContext

func FromContext(ctx context.Context) (Context, bool)

FromContext retrieves a Context previously injected with WithContext.

func (Context) Allows

func (c Context) Allows(tool string) bool

Allows reports whether the tool may be used under this context. Empty whitelists imply full access for backward compatibility with legacy agents.

func (Context) Clone

func (c Context) Clone() Context

Clone produces a deep copy to maintain isolation between runs.

func (Context) RestrictTools

func (c Context) RestrictTools(tools ...string) Context

RestrictTools narrows the tool whitelist to the provided names.

func (Context) ToolList

func (c Context) ToolList() []string

ToolList returns the current whitelist (sorted, deduplicated) for inspection.

func (Context) WithMetadata

func (c Context) WithMetadata(meta map[string]any) Context

WithMetadata merges metadata into the context.

func (Context) WithSession

func (c Context) WithSession(id string) Context

WithSession sets the session identifier when provided.

type Definition

type Definition struct {
	Name         string
	Description  string
	Priority     int
	MutexKey     string
	BaseContext  Context
	Matchers     []skills.Matcher
	DefaultModel string
}

Definition describes a single subagent.

func BuiltinDefinition

func BuiltinDefinition(name string) (Definition, bool)

BuiltinDefinition looks up a predefined subagent type by name.

func BuiltinDefinitions

func BuiltinDefinitions() []Definition

BuiltinDefinitions returns the predefined metadata for core subagent types.

func (Definition) Validate

func (d Definition) Validate() error

Validate ensures the definition is safe to register.

type Handler

type Handler interface {
	Handle(context.Context, Context, Request) (Result, error)
}

Handler executes a subagent request.

type HandlerFunc

type HandlerFunc func(context.Context, Context, Request) (Result, error)

HandlerFunc adapts a function to Handler.

func (HandlerFunc) Handle

func (fn HandlerFunc) Handle(ctx context.Context, subCtx Context, req Request) (Result, error)

Handle implements Handler.

type LoaderOptions

type LoaderOptions struct {
	ProjectRoot string
	ConfigRoot  string
	// Deprecated: user-level scanning has been removed; this field is ignored.
	UserHome string
	// Deprecated: user-level scanning has been removed; this flag is ignored.
	EnableUser bool
	FS         *config.FS
}

LoaderOptions controls how subagents are discovered from the filesystem.

type Manager

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

func NewManager

func NewManager() *Manager

NewManager builds a new manager.

func (*Manager) Dispatch

func (m *Manager) Dispatch(ctx context.Context, req Request) (Result, error)

Dispatch selects and executes a subagent. When Target is empty, automatic matchers choose the best candidate subject to priority/mutex ordering.

func (*Manager) List

func (m *Manager) List() []Definition

List returns registered subagent definitions sorted by priority + name.

func (*Manager) Register

func (m *Manager) Register(def Definition, handler Handler) error

Register installs a subagent definition + handler.

type Request

type Request struct {
	Target        string
	Instruction   string
	Activation    skills.ActivationContext
	ToolWhitelist []string
	Metadata      map[string]any
}

Request carries execution parameters for a subagent run.

type Result

type Result struct {
	Subagent string
	Output   any
	Metadata map[string]any
	Error    string
}

Result captures handler output.

type SubagentFile

type SubagentFile struct {
	Name     string
	Path     string
	Metadata SubagentMetadata
	Body     string
}

SubagentFile captures an on-disk subagent definition.

type SubagentMetadata

type SubagentMetadata struct {
	Name           string `yaml:"name"`
	Description    string `yaml:"description"`
	Tools          string `yaml:"tools"`          // comma separated
	Model          string `yaml:"model"`          // sonnet/opus/haiku/inherit
	PermissionMode string `yaml:"permissionMode"` // default/acceptEdits/bypassPermissions/plan/ignore
	Skills         string `yaml:"skills"`         // comma separated
}

SubagentMetadata mirrors the YAML frontmatter fields.

type SubagentRegistration

type SubagentRegistration struct {
	Definition Definition
	Handler    Handler
}

SubagentRegistration wires a definition to its handler.

func LoadFromFS

func LoadFromFS(opts LoaderOptions) ([]SubagentRegistration, []error)

LoadFromFS loads subagent definitions. Errors are aggregated so a single bad file will not block other registrations.

Jump to

Keyboard shortcuts

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