agent

type Assessment struct {
	Candidate

	// Resolved is the version that would actually be installed when the command
	// did not pin one. Empty when nothing could resolve it, which is not the
	// same as the package being fine.
	Resolved string

	// NameLevel records that the command named no version and nothing could
	// resolve the one it would install, so Insight describes the package's
	// whole history rather than a release. A malware flag at that level means
	// "some version has been malicious", which is true of express and is not a
	// reason to refuse `npm i express`.
	NameLevel bool

	Vulns   []scan.EnrichedVuln
	Insight *vdb.CliPackageInsight

	// Unknown records that the lookup could not answer for this package: no
	// credential, no network, an unparseable manifest, a timeout. It is never a
	// verdict, and it never blocks. Absence of an answer is not an answer.
	Unknown bool
	// ExploitsGated records that the server withheld exploit intelligence
	// rather than reporting none.
	ExploitsGated bool
}

type Auth struct {
	// Community is true when no credential of the user's own was found and the
	// built-in Community credentials are in use.
	Community bool
	// Missing is true when there is no credential at all, community included.
	Missing bool
}

type BashInput struct {
	Command     string `json:"command"`
	Description string `json:"description"`
}

type Candidate struct {
	// Name is the registry name, scope included for npm.
	Name string
	// Version is the requested version when the command pinned one, empty when
	// the command left resolution to the package manager. Empty is the common
	// case and is not an error: the guard resolves what would be installed.
	Version string
	// Ecosystem is the purl-style ecosystem, matching what VDB expects.
	Ecosystem string
	// Manager is the tool that would perform the install, for the message.
	Manager string
}

type Capabilities struct {
	SchemaVersion int    `yaml:"schema_version"`
	DetectedAt    string `yaml:"detected_at"`

	// Binaries reports which tools resolve on PATH.
	Binaries map[string]bool `yaml:"binaries"`
	// Repo reports which project markers exist in the tree.
	Repo map[string]bool `yaml:"repo"`
	// Derived is the small set of conclusions worth drawing once rather than in
	// every consumer.
	Derived CapabilityDerived `yaml:"derived"`
}

type CapabilityDerived struct {
	PrimaryPackageManager string   `yaml:"primary_package_manager"`
	HasContainers         bool     `yaml:"has_containers"`
	HasIAC                bool     `yaml:"has_iac"`
	HasCI                 bool     `yaml:"has_ci"`
	DetectionStack        []string `yaml:"detection_stack,flow"`
	SBOMStack             []string `yaml:"sbom_stack,flow"`
	SOAR                  string   `yaml:"soar"`
	AuthStatus            string   `yaml:"auth_status"`
}

type Decision int

type EditInput struct {
	FilePath  string `json:"file_path"`
	Path      string `json:"path"`
	OldString string `json:"old_string"`
	NewString string `json:"new_string"`
	Content   string `json:"content"`
}

type Event string

type GuardPolicy struct {
	Block []Signal `yaml:"block"`
	Warn  []Signal `yaml:"warn"`
}

type HookDialect string

type Host struct {
	// ID is the stable identifier, matching what `gh skill install --agent`
	// calls the host wherever one exists.
	ID string
	// Name is what the host calls itself.
	Name string

	// SkillDirs are the user-scope skill directories, most preferred first.
	// Several hosts read the interoperable ~/.agents/skills alongside their own.
	SkillDirs []string
	// ProjectSkillDirs are the repository-scope equivalents.
	ProjectSkillDirs []string

	// HookDialect is how this host's hooks are configured, if this build can.
	HookDialect HookDialect
	// HookConfig is the user-scope file the hook configuration lives in.
	HookConfig string

	// MCP records whether the host can be pointed at an MCP server.
	MCP bool

	// Detect are paths whose existence means the host is installed. A missing
	// binary is not proof of absence — several hosts ship as an extension
	// rather than a command — so a configuration directory counts.
	Detect []string
}

type InstallOptions struct {
	// DryRun reports what would change without writing.
	DryRun bool
	// Hooks configures lifecycle hooks where the host supports them.
	Hooks bool
}

type InstallResult struct {
	Host Host
	// Wired lists the surfaces configured.
	Wired []Surface
	// Changed is false when everything was already in place, which is the
	// common case on a re-run and is worth saying rather than reporting work
	// that did not happen.
	Changed bool
	// Notes carry anything the user should know, including surfaces this build
	// deliberately did not configure.
	Notes []string
	Err   error
}

type Lookup interface {
	Assess(ctx context.Context, cands []Candidate) []Assessment
}

type Payload struct {
	SessionID      string          `json:"session_id"`
	TranscriptPath string          `json:"transcript_path"`
	CWD            string          `json:"cwd"`
	HookEventName  Event           `json:"hook_event_name"`
	PermissionMode string          `json:"permission_mode"`
	ToolName       string          `json:"tool_name"`
	ToolInput      json.RawMessage `json:"tool_input"`
	ToolUseID      string          `json:"tool_use_id"`
	// UserInput carries the prompt on UserPromptSubmit. Hosts disagree on the
	// key, so both spellings are accepted.
	UserInput string `json:"user_input"`
	Prompt    string `json:"prompt"`
}

type Policy struct {
	// SafeHarbourStrategy picks which safe version counts as the target.
	//
	// Defaults to safest rather than the CLI's stable, matching the editor. An
	// agent adding a dependency on its own initiative gets less deliberation
	// than a version someone typed, so the default prefers the smallest risk
	// over the smallest change.
	SafeHarbourStrategy fix.Strategy `yaml:"safeHarbourStrategy"`

	// MaxMajorBump caps how far a recommendation may travel. Zero refuses major
	// versions, which are almost always a code change rather than a version
	// change.
	MaxMajorBump int `yaml:"maxMajorBump"`

	// CooldownDays is the age below which a version is considered too new to
	// trust. Zero disables the check.
	CooldownDays int `yaml:"cooldownDays"`

	DependencyGuard GuardPolicy `yaml:"dependencyGuard"`
	ChangeGuard     GuardPolicy `yaml:"changeGuard"`

	// Enabled turns the whole surface off without uninstalling it.
	Enabled *bool `yaml:"enabled"`
}

type Response struct {
	Event    Event
	Decision Decision
	// Message is the text the model receives, as context on Inform and as the
	// refusal reason on Block.
	Message string
}

type Runner struct {
	Policy Policy
	Lookup Lookup
	// Root is the repository the hook is running in.
	Root string
}

type Signal string

type Surface string

type VDBLookup struct {
	Root       string
	CLIVersion string
	// contains filtered or unexported fields
}