Documentation
¶
Overview ¶
Package agent defines shared DTOs for typed subagent spawn across hawk-eco.
Stdlib only. No engine, CLI, or storage imports.
Index ¶
Constants ¶
const ( HookPreToolUse = "PreToolUse" HookPostToolUse = "PostToolUse" HookUserPromptSubmit = "UserPromptSubmit" HookSessionStart = "SessionStart" HookSessionEnd = "SessionEnd" HookStop = "Stop" HookSubagentStart = "SubagentStart" HookSubagentStop = "SubagentStop" HookNotification = "Notification" HookPermissionRequest = "PermissionRequest" HookPreCompact = "PreCompact" HookFailure = "Failure" )
Hook event names for lifecycle and tool gates.
Hawk may accept vendor aliases (Claude/Cursor); normalize to these canonical names at the boundary. Constants are shared so hawk, plugins, and SDKs agree on wire/event vocabulary without importing engines.
const ( ThoroughnessQuick = "quick" ThoroughnessMedium = "medium" ThoroughnessVeryThorough = "very-thorough" )
Thoroughness levels for explore subagents.
const ( StatusRunning = "running" StatusCompleted = "completed" StatusFailed = "failed" )
Spawn status values for SpawnResult.Status.
Variables ¶
var VendorHookAliases = map[string]string{ "pretooluse": HookPreToolUse, "pre_tool_use": HookPreToolUse, "posttooluse": HookPostToolUse, "post_tool_use": HookPostToolUse, "userpromptsubmit": HookUserPromptSubmit, "user_prompt_submit": HookUserPromptSubmit, "sessionstart": HookSessionStart, "session_start": HookSessionStart, "sessionend": HookSessionEnd, "session_end": HookSessionEnd, "stop": HookStop, "subagentstart": HookSubagentStart, "subagent_start": HookSubagentStart, "subagentstop": HookSubagentStop, "subagent_stop": HookSubagentStop, "notification": HookNotification, "permissionrequest": HookPermissionRequest, "permission_request": HookPermissionRequest, "precompact": HookPreCompact, "pre_compact": HookPreCompact, "failure": HookFailure, "onerror": HookFailure, "on_error": HookFailure, }
VendorHookAliases maps common third-party hook names to canonical Hawk names. Keys are lower-case for case-insensitive lookup.
Functions ¶
func CanonicalHookEvent ¶
CanonicalHookEvent returns the Hawk canonical event name for s, or "" if unknown.
func ParseThoroughness ¶
ParseThoroughness normalizes explore thoroughness. Empty → medium.
Types ¶
type CapabilityMode ¶
type CapabilityMode string
CapabilityMode limits what tools a subagent may use.
const ( CapReadOnly CapabilityMode = "read-only" CapReadWrite CapabilityMode = "read-write" CapExecute CapabilityMode = "execute" CapAll CapabilityMode = "all" )
func DefaultCapabilityForType ¶
func DefaultCapabilityForType(t SubagentType) CapabilityMode
DefaultCapabilityForType returns the capability implied by a subagent type when the request does not set capability_mode.
func ParseCapabilityMode ¶
func ParseCapabilityMode(s string) (CapabilityMode, error)
ParseCapabilityMode normalizes capability aliases. Empty input returns CapReadOnly when defaultFromType is empty; callers should prefer DefaultCapabilityForType.
type IsolationMode ¶
type IsolationMode string
IsolationMode selects filesystem isolation for a subagent.
const ( IsoNone IsolationMode = "none" IsoWorktree IsolationMode = "worktree" )
func ParseIsolationMode ¶
func ParseIsolationMode(s string) (IsolationMode, error)
ParseIsolationMode normalizes isolation aliases. Empty → none.
type Normalized ¶
type Normalized struct {
Prompt string
Description string
SubagentType SubagentType
CapabilityMode CapabilityMode
Isolation IsolationMode
ResumeFrom string
CWD string
Model string
Background bool
Thoroughness string
ParentSession string
}
Normalized is a validated, alias-resolved spawn request.
type SpawnRequest ¶
type SpawnRequest struct {
Prompt string `json:"prompt"`
Description string `json:"description,omitempty"`
SubagentType string `json:"subagent_type,omitempty"`
CapabilityMode string `json:"capability_mode,omitempty"`
Isolation string `json:"isolation,omitempty"`
ResumeFrom string `json:"resume_from,omitempty"`
CWD string `json:"cwd,omitempty"`
Model string `json:"model,omitempty"`
Background bool `json:"background,omitempty"`
Thoroughness string `json:"thoroughness,omitempty"`
ParentSession string `json:"parent_session,omitempty"`
}
SpawnRequest is the cross-repo contract for spawning a subagent.
func (SpawnRequest) Normalize ¶
func (r SpawnRequest) Normalize() (Normalized, error)
Normalize validates and resolves aliases on r.
Rules:
- prompt is required unless resume_from is set
- cwd and isolation=worktree are mutually exclusive
- thoroughness only applies to explore (ignored otherwise after parse)
- empty capability_mode uses DefaultCapabilityForType
func (SpawnRequest) Validate ¶
func (r SpawnRequest) Validate() error
Validate is an alias for Normalize when only the error is needed.
type SpawnResult ¶
type SpawnResult struct {
SubagentID string `json:"subagent_id,omitempty"`
SubagentType string `json:"subagent_type,omitempty"`
Status string `json:"status,omitempty"`
Output string `json:"output,omitempty"`
Summary string `json:"summary,omitempty"`
ToolCalls int `json:"tool_calls,omitempty"`
Turns int `json:"turns,omitempty"`
DurationMs int64 `json:"duration_ms,omitempty"`
WorktreePath string `json:"worktree_path,omitempty"`
Persona string `json:"persona,omitempty"`
Error string `json:"error,omitempty"`
}
SpawnResult is the cross-repo contract returned after spawn completes or is accepted.
type SubagentType ¶
type SubagentType string
SubagentType selects the built-in subagent profile.
const ( TypeGeneralPurpose SubagentType = "general-purpose" TypeExplore SubagentType = "explore" TypePlan SubagentType = "plan" )
func ParseSubagentType ¶
func ParseSubagentType(s string) (SubagentType, error)
ParseSubagentType normalizes aliases (e.g. "general" → general-purpose). Empty input defaults to explore (conservative read-oriented default).
Source Files