subagent

type AgentRunInfo struct {
	InnerSessionID string
	AgentRunner    string
}

type Config struct {
	RoleName         string
	Cmd              string
	PromptContent    string
	SessionEnvVar    string
	SessionMetaField string
	DebugSessionEnv  string
	AgentRunnerEnv   string
	ModelEnv         string
	// SessionRetryHint formats the suggested retry CLI when session id cannot be
	// auto-detected. Receives sessionID and prompt. When nil, defaults to
	// `doctest agent <Cmd> --session-id <id> <prompt>`.
	SessionRetryHint func(sessionID, prompt string) string
	// AutoGenerateSessionID when true generates a session ID when flag, env var,
	// and CODEX_THREAD_ID are all unset. Default false returns an error with retry hint.
	AutoGenerateSessionID bool
	// HomeDir overrides os.UserHomeDir when resolving the default sessions base
	// (SessionBase and debug-session env empty). Prefer Options.SessionBase in
	// production; HomeDir is mainly for parallel-safe tests.
	HomeDir string
	// EnvLookup, when non-nil, is consulted before os.Getenv for library env
	// reads (session ID, debug session home, model, detection). Return
	// (value, true) to force a value (empty string = treat as unset); ( "", false)
	// falls through to the process environment. Request-scoped and parallel-safe.
	EnvLookup func(key string) (string, bool)
}

type Options struct {
	Prompt        string
	AgentRunner   string
	MockConfig    string
	SessionID     string
	Requirement   string
	CatchUp       bool
	Status        bool
	ListSessions  bool
	SessionBase   string
	SessionLayout SessionLayout
	Timeout       time.Duration
	// StdoutWriter receives streamed agent output instead of os.Stdout when set.
	StdoutWriter io.Writer

	// When true, subagent must not read or write meta.json. Session match/resume
	// uses SessionID and ResumeInnerSessionID; host persists via OnAgentComplete.
	HostOwnsMeta bool
	// Inner runner session for resume (from host meta.opencode_session_id).
	ResumeInnerSessionID string
	// Called after successful agent run; host persists to its meta.
	OnAgentComplete func(AgentRunInfo) error
}

type SessionLayout struct {
	// Dir is the session root. When set, use this directory directly
	// (no date nesting, no sess_* auto-create). Required for task-hub integration.
	Dir string

	// Per-file overrides. Empty = filepath.Join(Dir, <default-name>).
	MetaPath     string
	MessagesPath string // empty = skip messages.jsonl writes
	EventsPath   string
	PIDPath      string
	QuestionsDir string // custom path when questions enabled
	ProgressDir  string // custom path when progress enabled

	// Optional features — default ON in legacy mode (Dir unset).
	// When Dir is set, caller must set these explicitly.
	QuestionsEnabled bool
	ProgressEnabled  bool
}