claude

type AgentDir string

type AgentResult struct {
	Status    AgentStatus `json:"status"`
	Message   string      `json:"message,omitempty"`
	Files     []string    `json:"files,omitempty"`
	NextPhase string      `json:"next_phase,omitempty"`
	// Output is the payload the agent declares for the configured output
	// section — typically a heading plus a fenced JSON block, with newlines
	// escaped as they are on the wire. It is the value AgentStep.Run writes
	// into the output section, so the next phase can parse that section
	// directly instead of unwrapping the result envelope first.
	//
	// Distinct from AgentResultInfo.Output, which carries a fully rendered
	// section body including its heading, produced by BuildResultSection on
	// the single-shot task-runner path. The two must not be conflated: this
	// field is an input from the agent, that one is rendered output.
	Output string `json:"output,omitempty"`
}

type AgentResultLike interface {
	GetStatus() AgentStatus
	GetMessage() string
	GetFiles() []string
	GetNextPhase() string
	RenderResultSection() string
}

type AgentStatus = agentlib.AgentStatus

type AgentStepConfig struct {
	// Name is the step name for logs.
	Name string

	// Runner is the Claude CLI invocation backend (pre-configured with
	// AllowedTools, Model, ClaudeConfigDir via ClaudeRunnerConfig).
	Runner ClaudeRunner

	// Instructions is the system prompt for this step.
	Instructions Instructions

	// EnvContext is forwarded to the Claude CLI tool-invocation environment.
	EnvContext map[string]string

	// OutputSection is the body section heading for the LLM's output
	// (e.g. "## Analysis", "## Review").
	OutputSection string

	// NextPhase is the phase to advance to on success. Empty means
	// in-place save (multi-step phase intermediate).
	NextPhase string
}

type AllowedTools []string

type ClaudeConfigDir string

type ClaudeModel string

type ClaudeResult struct {
	Result string `json:"result"`
	// Partial is the assistant text the CLI streamed before the run ended, bounded
	// to the most recent 16 KiB. Empty when the CLI streamed no assistant text.
	Partial string `json:"partial,omitempty"`
	// InputTokens is the count of fresh (non-cached) input tokens the session consumed.
	InputTokens int64 `json:"input_tokens,omitempty"`
	// OutputTokens is the count of output tokens the session produced.
	OutputTokens int64 `json:"output_tokens,omitempty"`
	// CacheCreationTokens is the count of input tokens written into the prompt cache.
	CacheCreationTokens int64 `json:"cache_creation_tokens,omitempty"`
	// CacheReadTokens is the count of input tokens served from the prompt cache.
	CacheReadTokens int64 `json:"cache_read_input_tokens,omitempty"`
	// NumTurns is the number of conversation turns the session took. Zero when the
	// CLI reported no usage summary.
	NumTurns int64 `json:"num_turns,omitempty"`
	// SessionID is the CLI session identifier the stream reported. Empty when the CLI
	// reported no session id.
	SessionID string `json:"session_id,omitempty"`
	// InteractionCount is the number of human-authored entries the session's own
	// transcript recorded. Nil when the evidence was unavailable — no session id, no
	// transcript, or an unreadable or unparseable transcript. A non-nil zero is an
	// observation: the transcript was read and contained no human-authored entry.
	InteractionCount *int64 `json:"interaction_count,omitempty"`
}

type ClaudeRunner interface {
	Run(ctx context.Context, prompt string) (*ClaudeResult, error)
}

type ClaudeRunnerConfig struct {
	// ClaudeConfigDir overrides the Claude CLI config directory via CLAUDE_CONFIG_DIR.
	ClaudeConfigDir ClaudeConfigDir
	// AllowedTools is passed to claude --allowedTools to restrict tool access.
	AllowedTools AllowedTools
	// Model selects the Claude model (e.g. "sonnet", "opus").
	Model ClaudeModel
	// WorkingDirectory sets the CLI process working directory.
	WorkingDirectory AgentDir
	// Env holds extra KEY=VALUE entries appended to the subprocess environment
	// AFTER the allowlist + CLAUDE_CONFIG_DIR layers (see buildSubprocessEnv in claude-runner.go). This is
	// the escape hatch for passing through secrets or vars the allowlist would
	// otherwise strip (e.g. GH_TOKEN for gh CLI auth). Values here cross the
	// trust boundary into the Claude CLI subprocess — only add what the agent
	// genuinely needs.
	Env map[string]string
}

type Instruction struct {
	Name    string
	Content string
}

type Instructions []Instruction

type PermissionDecider interface {
	DecidePermission(ctx context.Context, request PermissionRequest) (PermissionDecision, error)
}

type PermissionDecision struct {
	// Allow reports whether the tool invocation may proceed.
	Allow bool
	// Message is an optional explanation returned to the CLI on denial.
	Message string
}

type PermissionRequest struct {
	// ToolName is the name of the tool the CLI wants to invoke.
	ToolName string
	// Description is the CLI's human-readable description of the invocation.
	Description string
	// InputPreview is a preview of the tool input. It is not logged.
	InputPreview string
}

type PluginCommander interface {
	Run(ctx context.Context, name string, args ...string) (string, error)
}

type PluginInstaller interface {
	EnsureInstalled(ctx context.Context, specs []PluginSpec) error
}

type PluginSpec struct {
	Marketplace string // e.g. "bborbe/coding"
	Name        string // e.g. "coding"
}

type ResultDeliverer[T AgentResultLike] interface {
	DeliverResult(ctx context.Context, result T) error
}

type TaskRunner[T AgentResultLike] interface {
	Run(ctx context.Context, taskContent string) (*T, error)
}