Extending the agent
Installing tools from the registry
Find a tool someone already wrote, install it into a running session, and publish your own — with a trust policy deciding what may install without asking.
A SPEC is a packaged tool someone published. The registry is where they live, and the agent can drive the whole lifecycle itself: search, install, use, publish, share.
From the agent
Fourteen tools cover the lifecycle. Read-side: spec_search, spec_info,
spec_list, spec_validate, spec_update. Authoring: spec_init,
spec_build. State-changing: spec_install, spec_uninstall,
spec_rollback, spec_publish, spec_yank, spec_unyank, spec_share.
The seven that change state require confirmation before they run.
A freshly installed tool is registered into the running registry, so it is usable in the same turn. No restart.
From the command line
snaga spec search <query>
snaga spec info <name>
snaga spec install <name>
snaga spec list
snaga spec update
And to publish your own:
snaga spec init # scaffold a SPEC project here
snaga spec build # build the bundle locally, without publishing
snaga spec publish # build + publish
snaga spec share # manage who can see a private SPEC
snaga spec yank <ver> # withdraw a version you own
What happens on install
The SPEC is resolved, downloaded, and its integrity verified by SHA-256 before
anything is unpacked. Extraction is bounded, and the install is recorded in an
append-only ledger at .snaga/specs-history.jsonl — every install, uninstall
and rollback, in order.
That ledger is what makes the next part possible.
Undoing an install
snaga spec uninstall <name> # remove every version
spec_rollback is the narrower one: it undoes the current install of a
single SPEC, using the ledger to know what "current" was. Use it when an
upgrade made something worse and you want the previous state, not a clean
removal.
Deciding what may install itself
When the agent is running autonomously, "install this tool" is a decision nobody
is present to approve. .snaga/trust.toml sets the boundary in advance.
The defaults are deliberately strict:
| Setting | Key | Default |
|---|---|---|
| Scopes that may install without prompting | auto_install_scopes | ["@official/*", "@platform/*"] |
| Supply-chain attestation required | require_slsa | true |
| Declared capabilities before prompting | max_capabilities_without_prompt | 5 |
| Capabilities that always prompt | always_prompt_caps | shell_exec, file_write, http_post |
The last row matters most. shell_exec, file_write and http_post prompt
regardless of scope — so a package from a trusted namespace cannot quietly gain
shell or write access by declaring it. Trust in a publisher is not trust in
every capability that publisher might ask for.
Widen it when you have reason to:
auto_install_scopes = ["@official/*", "@platform/*", "@your-org/*"]
The keys are top level — there is no [trust] section. A misspelled section
name cannot silently relax the policy, because an unrecognised file parses to
the strict defaults rather than to nothing; that property has a test of its own.
An empty auto_install_scopes means "never auto-install from the registry".
Why installable rather than built in
The kernel ships a small tool set on purpose — every always-present tool costs context in every session, whether or not your work touches it. The domain tools that used to be built in are expected to return here instead, as things you install when you need them.
Combined with the agent writing its own tools, this closes a loop: a tool gets written locally to solve one problem, published, and installed by somebody who had the same problem. See The agent writes its own tools.