Documentation
¶
Overview ¶
Package extension loads skills, sub-agents, MCP servers and hooks from built-ins, the user, the project and plugins. The project wins name clashes over the user, and the user over built-ins; plugin resources are namespaced, and all hooks run.
Anything that runs code or skips permission prompts needs the user's consent (see Surface and Consents), because a project or a plugin may come from anyone: a project's item by item, since its settings are odds and ends from many hands, and a plugin's as a whole, since its author tested it as one. A project's instructions for the model always load; a plugin not agreed to is off entirely.
Index ¶
- func AgreeToPlugin(src plugin.Source, commit string, surface Surface) error
- func EditConsents(edit func(*Consents)) error
- func LatestCommit(ctx context.Context, src plugin.Source) (string, error)
- func PluginBase(scope Scope, root string) string
- func ReadPlugin(ctx context.Context, src plugin.Source, commit string) (p *plugin.Plugin, got string, problems []error, err error)
- func SweepCache() error
- type Consent
- type Consents
- type Hook
- type Item
- type MCPServer
- type Options
- type Plugin
- type PluginConsent
- type PluginState
- type Scope
- type Set
- type Shadow
- type Standing
- type Surface
- type Trust
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AgreeToPlugin ¶
AgreeToPlugin records the user's agreement to everything the plugin runs, surface, at commit for a git plugin.
func EditConsents ¶
func PluginBase ¶
func ReadPlugin ¶
func ReadPlugin(ctx context.Context, src plugin.Source, commit string) (p *plugin.Plugin, got string, problems []error, err error)
ReadPlugin reads a plugin for the user to review. A git plugin is fetched at commit, or at its ref when commit is "", and the resolved commit is returned.
Types ¶
type Consent ¶
type Consent struct {
// Denied means the user distrusts the project and is not asked again.
Denied bool `json:"denied,omitempty"`
// Declined items are not asked about again.
Surface Surface `json:"surface,omitempty"`
Declined Surface `json:"declined,omitempty"`
}
Consent is the user's decision on a project, item by item.
type Consents ¶
type Consents struct {
Projects map[string]Consent `json:"projects,omitempty"`
Plugins map[string]PluginConsent `json:"plugins,omitempty"`
}
Consents records what the user agreed to run, per project root and per plugin source (plugin.Source.ID). It lives in the user's home so no project can grant itself consent, and only an explicit user decision writes it: reading, fetching or loading never does.
func ReadConsents ¶
type Hook ¶
type Item ¶
type Item struct {
// Kind is "hook", "mcp", "allow", "read", "write", "skill" or "plugin".
Kind string `json:"kind"`
// Key is the full content of the item: any change makes it a different
// item that needs consent again.
Key string `json:"key"`
// Detail is the escaped, human-readable form of the item.
Detail string `json:"-"`
}
type MCPServer ¶
type Options ¶
type Options struct {
Cwd string
Layers config.Layers
Consents Consents
// PluginDirs are command-line plugins, loaded for this session only with
// implicit consent.
PluginDirs []string
// TrustAll consents, for this session, to everything the project and
// its declared plugins run.
TrustAll bool
}
type Plugin ¶
type Plugin struct {
// Source is as written in settings or on the command line.
Source string
Scope Scope
// Src is Source parsed relative to the declaring settings file; zero if
// it does not parse.
Src plugin.Source
// Commit is the agreed commit of a git plugin; "" for a local plugin or
// one not agreed to yet.
Commit string
State PluginState
// Err is set when State is PluginBroken.
Err error
// Surface is everything the plugin runs; New is the part the user has
// not agreed to, which keeps all of it off.
Surface, New Surface
// Plugin is nil unless State is PluginOn, PluginShadowed or
// PluginWaiting.
*plugin.Plugin
}
type PluginConsent ¶
type PluginConsent struct {
// Commit pins a git plugin to the commit the user agreed to.
Commit string `json:"commit,omitempty"`
Surface Surface `json:"surface,omitempty"`
}
PluginConsent is the user's agreement to a plugin as a whole: its author tested it as one, so it runs all of Surface or nothing.
type PluginState ¶
type PluginState string
const ( PluginOn PluginState = "on" PluginShadowed PluginState = "shadowed" // another plugin of the same name won PluginUntrusted PluginState = "untrusted" // the user has not agreed to the project declaring it PluginNotInstalled PluginState = "not installed" // a git plugin the user has not agreed to yet PluginNotCached PluginState = "not cached" // the agreed commit is no longer cached PluginWaiting PluginState = "waiting" // it runs something the user has not agreed to, so none of it runs PluginBroken PluginState = "broken" )
type Set ¶
type Set struct {
// Skills, Agents and MCP hold the winner of each name.
Skills []skill.Spec
// Agents excludes the built-in ones; subagent.Definitions layers these
// over them.
Agents []subagent.AgentDefinition
MCP []MCPServer
// Hooks are ordered user, project, then plugins.
Hooks []Hook
// Plugins lists command-line plugins, then the project's, then the
// user's, including those not in effect.
Plugins []Plugin
Trust Trust
// Granted holds the project grants the user agreed to. See
// config.ForProject.
Granted config.Settings
Shadowed []Shadow
// Problems lists what was left out: files that failed to load and
// project settings only the user may set. They are escaped for the
// terminal.
Problems []error
}
func (*Set) HooksConfig ¶
func (s *Set) HooksConfig() config.HooksConfig
type Shadow ¶
type Shadow struct {
Kind string // "skill", "agent", "MCP server" or "plugin"
Name string
// Lost and Won are the files of the replaced and the winning resource,
// or "builtin".
Lost, Won string
}
Shadow is a resource replaced by another of the same name.
type Standing ¶
type Standing struct {
Surface, Agreed, Declined Surface
}
Standing splits a surface into what the user agreed to and what they declined.
type Surface ¶
type Surface []Item
Surface is the part of a project or plugin that runs code or skips permission prompts, so it needs the user's consent: hooks, MCP servers, allow rules, roots, plugins a project declares, and skill privileges. It stores the items themselves rather than a digest, so the user is asked only about items that are new. Items are sorted.
func PluginSurface ¶
PluginSurface lists the plugin's MCP servers, hooks and skill privileges. Paths are written as ${PLUGIN_ROOT} and ${PLUGIN_DATA}, so moving to another commit's directory alone does not need new consent.
type Trust ¶
type Trust struct {
// Root is "" outside a project; the home directory never counts as one.
Root string
Standing
// Denied means the user distrusts the project: none of its surface takes
// effect and they are not asked about it.
Denied bool
// ForRun is set by --trust, which overrides the saved decision for this
// run.
ForRun bool
}