Introduction

Symposium makes Rust dependencies actionable for AI agents. It discovers crate-matched plugins and wires in skills, hooks, and MCP servers so your agent can work with project-specific context.

About ⁄ Install ⁄ Blog

Getting started

cargo binstall symposium # or: cargo install symposium
cargo agents init

After initialization, start your agent in a Rust project as usual.

• For first-time setup details, see Installing Symposium.
• For command reference, see The cargo agents command.
• For agent compatibility, see Supported agents.

Recent posts

What is Symposium?

Symposium is a one-stop shop to help agents write great Rust code. It connects you to best-in-class tools and workflows but it also serves up skills and extensions tailored to the crates you are using, all authored by the people who know those crates best – the crate authors.

init and go

Getting started with Symposium is easy:

#![allow(unused)]
fn main() {
cargo binstall symposium       # or `cargo install` if you prefer
cargo agents init
}

The init command will guide you through picking your personal agent. It will then configure the agent to use Symposium (e.g., by installing hooks). This will immediately give you some benefits, such as introducing Rust guidance and reducing token usage with the rtk project.

Leveraging the wisdom of crates.io

To truly get the most out of Symposium, use it in your Rust projects. When your agent starts a session in one, or when you run cargo agents sync, Symposium scans your dependencies and installs customized skills, tools, and other improvements. These extensions come from our central recommendations repository and from the crates themselves: crate authors can embed extensions in their crates, and you enable them with a single confirmation.

Everybody picks their own agent

Work on an open-source project or a team where people use different agents? No problem. Your Symposium configuration is agent agnostic, and the cargo agents tool adapts it to the agent that each person is using. You can also specify the agent centrally if you prefer.

Staying synchronized

By default, Symposium is setup to synchronize itself. It’ll source the latest skills automatically and add them to your project. If you prefer, you can disable auto-updates and run cargo agents sync manually.

For crate authors

If you maintain a Rust crate, you can publish skills for Symposium so that every AI-assisted user of your library gets your best practices built in. See Supporting your crate for how to get started.

Blog

Welcome to the Symposium blog.

• Announcing Symposium — April 21, 2026
  A short launch post introducing the project, its goals, and how to get involved.

Announcing Symposium - AI The Rust Way

Authored By: Jack Huey

Are you using an AI agent to write Rust code (or curious to try it)? If so, GREAT NEWS! We’d like to share with you Symposium - a Rust-focused interoperability layer that connects AI agents to crate-authored skills, tools, and workflows.

(If you’ve read Niko’s previous blog posts talking about Symposium, this is pretty different! The tool we’re announcing today is the result of many iterations of figuring out what exactly the “thing we want” is. So please, read on!)

Also, this announcement comes with exciting news: Symposium has joined the Rust Foundation’s Rust Innovation Lab (RIL)! Be sure to check out the Foundation’s blog post.

What is Symposium?

There are really two answers to that question. The first one is that Symposium is a tool that examines what crates your project depends on and uses that to automatically install new skills, MCP servers, or other extensions. These extensions help your AI agent to write better code, avoid common footguns and pitfalls, and even leverage ecosystem tools like the Rust Token Killer (RTK) to save you tokens.

The second one is that Symposium is an organization dedicated to one goal, “AI the Rust way”, meaning reliable, efficient, and extensible. We are focused on interoperable, vendor-neutral, and community-oriented ways to make agents more reliable and efficient.

Getting started

You interact with Symposium through the cargo agents CLI command. If you want to try it, do this:

#![allow(unused)]
fn main() {
cargo binstall symposium # or `cargo install`
cargo agents init
}

The init command will prompt you to select what agents you want to use and a few other things. Based on that we install hooks that will cause Symposium to be invoked automatically. The next time you start an agent on a Rust project, Symposium will check if there are available skills or other extensions for the crates you use and set them up automatically. You shouldn’t have to do anything else.

Symposium helps your agent write better code and use fewer tokens

You may be familiar with various extensions that agents can work with, such has MCP servers, Skills, or Hooks. You may also know that different agents have different levels of support for these, and even different takes on them (Hooks, for example, are not as well-standardized as MCP servers and Skills). However, that doesn’t diminish the fact that many people have built many tools around these extension systems. We want you to easily use these ecosystem tools.

You may also have run into cases where a model is “outdated” compared to either the Rust language itself (e.g., there may be a newer language feature that is more idiomatic) or was trained on an older versions of a crate that you are using. It’s generally not hard to get models to follow newer conventions, but they need to be told to do so. We want to make that easier and more automated.

Finally, we want writing code with agents to be more efficient and reliable. Some of this comes from the above two goals, but part of it also comes from making sure that agents write code the way you would write it. For example, when you finish writing Rust code, you likely run cargo check, run your tests, or format your code - and we think that you should expect your agent to do the same. Simulatenously, efficiency also means that we want these tools to use as few tokens as possible.

Symposium Plugins

A Symposium plugin defines a set of extensions (mcp servers, skills, hooks, etc) and the conditions in which they should be used (currently: when a given version of a given crate is in the project’s dependencies). Plugins are hosted on repositories called a “plugin source”; we define a central repository with our globally recommended plugins, but you can additional plugin sources of your own if you like.

Skills

Agent Skills are a lightweight format for defining specialized knowledge or workflows for agents to use. Most agents have a pre-defined list of places that they look for skills, but don’t currently have a way to dynamically make them available.

In Symposium, we automatically discover skills from plugins applicable to the current crate. By default, we automatically sync them to the current project’s directory so they can be used by your agent (either .agent/skills or .claude/skills). This is done through a custom hook (if your agent supports it), but can be disabled or manually synced with cargo agents sync.

Hooks

Unlike skills which are dynamically loaded by agents, hooks are dispatched on certain events such as on agent start, after a user prompt, or prior to a tool use. Symposium has a small number of hooks it installs (when available) that it uses to ensure that plugins are discovered and loaded for an agent to use.

Additionally, today, hooks defined by plugins are also dispatched through Symposium. This allows, for example, dispatching hooks written for one agent when using a different agent (to the extent that we’ve implemented support). The list of supported hooks is fairly small, but we’re far from done with expanding hooks support.

MCP servers

MCP servers were one of the first extensions made available by agents. They expose a set of tools, either local or remote, that agents can call. MCP servers defined by a Symposium plugin get installed into your agent’s settings for use.

What’s next?

As we said in the beginning, the Symposium org is focused on “AI the Rust way” – so what does that mean? We’re starting with a minimal, usual product for users to experiment with and hopefully find use from. But, we’re far from done. We have a number of really interesting ideas to make Symposium even more useful.

We want to continue to expand the set of agent features that Symposium supports. When an agent supports a tool or similar, we want it to be a minimal process to be able to recommend that users of your crate also use that tool. Often, this means that we should “just install” those tools into project-local agent settings; but, we want to make sure that this is done correctly and supports the agents that our users use. However, we also want to support (when possible) more dynamic loading - such as by dispatching hooks through Symposium itself, or having Symposium register a transparent MCP server layer. There are lots of things we can do here, and we’re excited to hear what people want and need first.

We currently have pretty minimal support for how to run hooks or MCP servers - really just a command to run. We already have in-progress work to support declarative dependencies, which in turns allows both auto-installation and auto-updates. Using a symposium plugin should “just work”.

The work we’re presenting today is focused mainly around Rust crates, but our vision also includes better recommendations around the Rust language. We’ve already seen a few ecosystem-driven projects with this goal - we plan to review these and find what works best for Symposium users and make it the default for the best experience possible when writing Rust code. Similarly, we plan to write our own plugins that help your agent format and test Rust code that it has written, before you even look at it.

Symposium previously was focused around the Agent Client Protocol (ACP), which provides a programmatic way to interact with and extend agent capabilities. We still love this vision, but our current focus is on an ecosystem-first approach of meeting agents where they are today. We do expect that as ACP adoption continues to increase and we have a solid foundation with the work we’ve presented today, that we will again focus on ACP to further increase the interoperability and extensibility we provide for users of Symposium.

Finally, although our initial work is focused around Rust, we think this idea - discoverability and use of plugins defined by dependencies - is applicable and useful for other language ecosystems too. We would love to expand this to other languages.

In all, we’re really excited for people to use Symposium. We hope that what we’ve shared today gets you excited about building better Rust with AI, and we think that this is only the beginning. If you have thoughts or questions, either open an issue on Github or join the Symposium Zulip; we’d love to hear your thoughts!

A Maturing Symposium

Authored By: Jack Huey

We announced an initial MVP release of Symposium just about two months ago, and figured it would be good to give an update on what we’ve added since!

Tl;dr we’ve added a number of different features that allow Symposium to do more things for different workflows, and to keep your plugins updated!

More powerful plugins

The first set of changes to discuss all cover essentially the things that you can do with plugins.

Unified predicate system. In the MVP, a plugin only had a single crates field to filter when it was activated. We’ve added a more robust and more general predicates field that supports more complex logic for plugin (and e.g. skills) activation. We currently support builtin crate, shell, path_exists, and env predicates; as well as not/any/all combinators. So, you can, for example gate the activation of a plugin based on if a program is installed, or if a workspace env var is set. The existing crates field desugars into any(crate(..), ..). Additionally, plugins can register custom predicates, available globally across plugins. This is particularly useful to gate plugin use on if something like battery packs is enabled or if async is used.

Plugin-vended subcommands. Skills, hooks, and MCP servers cover a lot, but sometimes a plugin just wants to offer a command that you, or your agent, can run directly. Now plugins can contribute their own cargo agents <name> subcommands, and they only appear when the surrounding project makes them relevant.

Hooks 2.0. One thing we really want is the ability to just use the ecosystem - so if a Claude Code hook exists, you should just be able to use that in a plugin. But, we also want to support the ability to “write once, run anywhere”. We’ve added support for a common hook infrastructure, and hook dispatch will fall back to that if a native hook doesn’t exist. We eventually want to potentially extend that to custom hook events too, to enable something like “post cargo test run”.

Of course, the schema has changed a couple times since the initial MVP. But, we try to validate plugin definitions to ensure that what you wrote makes sense.

More control of your plugin sources and where they are installed

In addition to making your plugins more powerful, we also have given you more control of where your plugins are sourced and where they are installed.

Global install + env vars. By default, plugin dependencies (installations) are installed into the ~/.symposium directory. However, we’ve added the ability to install globally. Additionally, we’ve added env vars that are set to the installation paths and binaries, for more control.

Crate-sourced skills. Crates can now ship agent skills directly. Skills can use source = "crate". You can use either the current crate, or a separate crate. Additionally, you can decide what skills are active when developing the current crate, and which skills are active when using the current crate. Skills written to ./skills are used for crate use; skills written to .agents/skills are for crate development. When you write a skill to .agents/skills , they will be synced to .claude/skills or other agent skills directories, if needed. Automatically synced skills are git-ignored (as are all symposium-installed skills), so you don’t need to worry about your git workspace getting cluttered!

Keeping Symposium and your plugins up to date

We all want our software to be up-to-date. Similarly, when a crate author publishes a newer version of a skill, we want to ensure that the latest version is used.

Plugin and Symposium Auto-Update. We’ve added a auto-update config option (on by default) that will automatically update Symposium. This can be manually triggered with cargo agents self-update. Plugin hooks and dependencies now also automatically update; skills already updated automatically.

Smarter, cheaper sync. Auto-sync of skills now skips when Cargo.lock is unchanged, has a configurable debounce (sync-debounce-secs, default 5s), is change-aware (no disk churn when nothing differs), and dedups/disambiguates installed skill dirs by origin rather than name.

Helping agents (and humans) use Symposium better

Although we want Symposium to be mostly “hands off” once set up, we recognize that sometimes we (humans and agents) need to interact with it. We’ve added a couple things to help with this.

Audience-grouped --help. cargo agents --help now renders two sections: “Commands for humans” and “Commands for agents”. It also lists workspace-applicable plugin subcommands alongside built-ins. SessionStart also nudges the agent to run --help when relevant subcommands exist.

Structured output (--verbose / --json). A new report layer renders command output three ways: human-readable (default), verbose decision trace to stderr, or a machine-readable JSON array. This is intended in large part for debugging or machine/tooling consumption.

Upcoming opt-in telemetry to help us ensure Symposium is effective

We’ve added the basic infrastructure to support anonymous, local, opt-in telemetry. Nothing is collected, yet. But, we want to be able to eventually let users help us make Symposium better: we want to know what’s working and what isn’t. Telemetry status and information can be checked with cargo agents telemetry status and cargo agents telemetry show.

Conclusions

In general, we’re proud of the progress we’ve made. But, we still have more that we want to do! We’re looking into supporting additional language ecosystems (e.g. npm or pypi) and we want to be flexible to new standards as they are developed. We want Symposium to empower you to do things you otherwise couldn’t or wouldn’t due to complexity or cognitive overhead, while also meeting the ecosystem where it is.

Getting Started

Install

The fastest way to install Symposium is with cargo binstall:

cargo binstall symposium

If you prefer to build from source, use cargo install instead:

cargo install symposium

On Arch Linux, install the symposium package from the official repositories:

pacman -S symposium

Initialization

Once you have installed Symposium, you need to run the init command:

cargo agents init

Select your agents

This will prompt you to select the agents you use (Antigravity, Claude Code, Copilot, etc.) — you can pick more than one:

Which agents do you use? (space to select, enter to confirm):
> [ ] Antigravity CLI
  [ ] Claude Code
  [x] Codex CLI
  [ ] GitHub Copilot
  [ ] Goose
  [x] Kiro
  [x] OpenCode

Global vs project hook registration

Next, Symposium will ask you whether you want to register hooks globally or per-project:

• global registration means Symposium will activate automatically for all Rust projects.
• project registration means Symposium only activates in projects once you run cargo agents sync to add hooks to that project.

We recommend global registration for maximum convenience.

Tweaking other settings

You may wish to browse the configuration page to learn about other settings, such as how to disable auto-sync.

After setup

Symposium will now install skills, MCP servers, and other extensions based on your dependencies automatically.

Most plugins come from two places: the central recommendations repository, which is enabled by default, and crates your project depends on directly that ship their own. A dependency’s plugin stays off until you enable it: an interactive cargo agents sync asks about each one, and cargo agents status lists the ones waiting for an answer. If you have a crate and would like to add a plugin for it to symposium, see the Supporting your crate page.

If you have private crates or would like to install plugins for your own use, you can consider adding a custom plugin source.

Workspace skills

In addition to adding skills based on your dependencies, Symposium will also install skills your workspace defines for itself: skills found in skills/ or .agents/skills in the workspace root or any member crate install into the directory appropriate for your configured agent(s).

This allows your project to add skills in one central location that will work for all developers, regardless of which agent they use (for example, Claude Code users will have the skills synced to .claude/skills).

The default skill location therefore varies depending on the intended audience:

Workspace plugins

The workspace root and every member crate directory can define a workspace plugin: add a Symposium.toml manifest (see the plugin definition), or just a bare skills/ directory — a directory with skills and no manifest counts as a plugin whose only content is those skills.

Workspace plugins are always active while you work in that workspace: no plugin source configuration or depends-on gate is needed. A skills/ directory in a member crate serves double duty: it installs for everyone working in the workspace and, once published, for projects that depend on the crate and enable its plugin.

Every workspace plugin gets two default skill groups (unless disabled with [defaults] skills = false):

[[skills]]
source.path = "skills"

[[skills]]
predicates = ["workspace-member()"]
source.path = ".agents/skills"

The second group is how the .agents/skills convention works: it is gated by the workspace-member() predicate, so maintainer skills apply while working in the workspace but never install for dependents of a published crate. (The group can also be turned off globally with agents-syncing = false in the user config.)

Two details specific to workspace manifests:

• name may be omitted; it defaults to the directory name.
• No top-level depends-on is required — workspace membership is the gate, so a workspace plugin never goes dormant the way a gateless registry plugin does.

Components that should apply only to people developing the workspace (not to dependents of a published crate) can be gated with the workspace-member() predicate.

Informal skills

Workspace skills are your own notes, so the skill frontmatter requirements are relaxed: the name and description fields — and the frontmatter block itself — are optional. A SKILL.md that is just plain markdown works; its name defaults to the directory that contains it. Skills distributed through a registry or a published crate still require the full frontmatter.

Recommended git setup

We recommend you commit your .agents/skills or skills/ into the repository. Symposium installs a .gitignore file into every skill that it creates, so automatically copied and installed skills should not dirty your git status.

Pre-existing files

Symposium never touches skills in .claude/skills/, .kiro/skills/ etc. that it did not put there itself. If you previously hand-wrote a skill with the same name as one in .agents/skills/, your existing directory stays in place and the workspace skill installs under a suffixed name (<name>-<hash>) alongside it.

Custom plugin sources

Custom plugin sources let you define your own sets of plugins without putting them in the central recommendations repository.

Custom plugin sources are useful for:

• Company-specific plugins — internal tools and guidelines for your organization
• Development plugins — local plugins you’re working on

Custom plugins in your home directory

plugin definitions or standalone skills added to the ~/.symposium/plugins directory will be registered by default and propagated appropriately to your other projects.

Adding your own custom sources

You can also define a custom plugin source in a git repository or at another path on your system. Each one is a [[registry]] entry ([[plugin-source]] is the retired spelling of the same table, still accepted).

Git repository

Add a remote Git repository as a registry:

# In ~/.symposium/config.toml
[[registry]]
name = "my-company"
git = "https://github.com/mycompany/symposium-plugins"
auto-update = true

We recommend creating a CI tool that runs cargo agents plugin validate on your repository with every PR to ensure it is properly formatted.

Local directory

Add a local directory as a registry:

[[registry]]
name = "local-dev"
path = "./my-plugins"
auto-update = false

Structure of a plugin source

See the reference section for details on what a plugin source looks like.

Managing sources

The cargo agents plugin command allows you to perform operations on the installed plugin sources, like synchronizing their contents or validating their structure.

Supporting your crate

Working with an agent? Point it at llms.txt, a single file written for agents with what it needs to write a Symposium plugin. Ask it to download the file with curl -fsSL https://symposium.dev/crate-authors/llms.txt and read all of it: web-fetch tools can hand the agent a summary instead of the text.

If you maintain a Rust crate, you can extend Symposium with skills, MCP servers, or other extensions that will teach agents the best way to use your crate.

Embed skills in your crate

The recommended approach is to ship skills directly in your crate’s source tree. Add a skills/ directory with SKILL.md files and publish your crate. Users who depend on it directly are asked whether to enable its plugin when they run cargo agents sync, and then get guidance that matches the exact version of your crate they’re using.

See Authoring a plugin for the full walkthrough.

Skill layout metadata

By default Symposium looks in your crate’s skills/ directory. To customize the layout (a different subdirectory, several skill groups, a git source, or delegating to another crate), you describe your crate’s plugin inline under [package.metadata.symposium] in Cargo.toml. This block uses the exact same schema as a Symposium.toml plugin manifest: it is just that manifest embedded in Cargo.toml:

# Optional — absence means "look in skills/ by default"
[[package.metadata.symposium.skills]]
source.path = "guidance"   # custom subdirectory for skills

Because it is a plugin manifest, the same rules apply as for a crate-embedded Symposium.toml: name defaults to the crate, a top-level depends-on is unnecessary (reaching your crate, through the user’s enablement or a chained reference, is the gate), and the default skills/ group is appended unless you opt out with [package.metadata.symposium.defaults] skills = false.

If you ship both a [package.metadata.symposium] block and a Symposium.toml, they are combined — list entries (skill groups, chained references, …) from both are kept; where the two set the same scalar, the Symposium.toml file wins.

Resolution rules

1. No metadata section and no Symposium.toml: Symposium uses the default skills/ subdirectory.
2. Opt out of the default group: [package.metadata.symposium.defaults] skills = false and declare no skill groups: no skills from this crate.
3. source.path groups: look in that subdirectory of your crate’s source, in addition to the default skills/ group unless you opt out of it.
4. [[package.metadata.symposium.plugins]] chained references: load another crate’s plugin (see Delegating to another crate).

Delegating to another crate

A [[package.metadata.symposium.plugins]] chained reference lets your crate delegate skill hosting to another crate. This is useful when:

• Your main crate is small but skills live in a larger companion package.
• Multiple crates in a workspace want to share a single set of skills.
• You want to version skills separately from the library.

# In dial9-tokio-telemetry/Cargo.toml
[[package.metadata.symposium.plugins]]
source.cargo = "dial9-viewer"   # or { name = "dial9-viewer", version = ">=1.0" }

A chained reference can target any crate, not just workspace dependencies. The referenced crate is itself resolved as a plugin (its own metadata / Symposium.toml / default skills/), so delegation composes transitively. When a user enables your crate, the crates it delegates to load with it.

Cycles are safe: a crate reached a second time is skipped, so A -> B -> A loads each crate once. Crate name comparison is hyphen/underscore-insensitive (my-crate and my_crate are the same crate).

Edge cases

• Malformed metadata: If [package.metadata.symposium] or Symposium.toml doesn’t parse as a manifest (wrong types, unknown fields), Symposium ignores that layer and still resolves the rest (at minimum the default skills/ group). A manifest that parses but fails validation, for example a hook naming an installation that doesn’t exist, disables your crate’s whole plugin, default skills/ group included. Both problems are reported only in Symposium’s log (~/.symposium/logs/), so try your plugin in a project before publishing.
• Missing path directory: If a source.path group references a directory that doesn’t exist, Symposium silently produces zero skills for that group. Other groups are still processed.
• Diamond references: If multiple crates all delegate to the same target crate, the target loads once and its skills are installed once (a skill’s identity is the location of its SKILL.md, not who referenced it).

Want to write a skill for someone else’s crate?

We prefer crates to ship their own skills, but some crates may not want to or may not be actively maintained. We also accept skills for those crates to help bootstrap the ecosystem. External skills must be uploaded directly into our central recommendations repository so that we can vet them.

See Authoring a plugin for the details.

Moar power!

Beyond skills, there are three more extension types you can publish through a plugin:

• Hooks: checks and transformations that run when the AI performs certain actions, like writing code or running commands.
• MCP servers: tools and resources exposed to agents via the Model Context Protocol.
• Subcommands: your crate’s own command-line tool, which agents and users run as cargo agents my-crate <command>.

See Authoring a plugin for how to set one up.

Authoring a plugin

Working with an agent? Point it at llms.txt, a single file written for agents with what it needs to write a Symposium plugin. Ask it to download the file with curl -fsSL https://symposium.dev/crate-authors/llms.txt and read all of it: web-fetch tools can hand the agent a summary instead of the text.

Symposium lets you ship skills, hooks, and MCP servers to the AI agents of people whose projects depend on your crate. This page walks through how to create a plugin and configure each extension type.

Step 1. Decide where your plugin lives

A plugin can live in one of two places:

• In your crate. If you maintain the crate, ship the plugin in its source tree: a skills/ directory is enough, and a Symposium.toml adds hooks, MCP servers, and more. See Embedding skills in your crate.
• In the central recommendations repository. This is the place for plugins for crates you don’t maintain.

A recommendations entry is a Symposium.toml manifest declaring your plugin’s name, which crates it applies to, and what extensions it provides:

# `my-crate/Symposium.toml` on the symposium-dev/recommendations repository
name = "my-crate"
depends-on = ["my-crate"]

The depends-on field controls when the plugin is active: depends-on=["foo"] means that your plugin will load if the current workspace directly depends on "foo". Use ["*"] to apply to all projects.

See the plugin definition reference for the full manifest schema.

Will users get every crate from all their dependencies by default?

No, the default is that Symposium makes users away when there are suggested plugin for their workspace, but users must explicitly run cargo agents sync and then agree for those plugins to be enabled. However, once a plugin has been enabled in one workspace, it will automatically be enabled in other workspaces.

NB: Plugins in the recommendations repository are reviewed before they are merged so they do not require explicit confirmation.

Step 2. Add skills, hooks, and/or MCP servers

Wherever your plugin lives, you can add any combination of the extension types below.

Skills

Skills are guidance documents that teach AI assistants how to use a crate. Each skill is a directory containing a SKILL.md file with YAML frontmatter and a markdown body:

---
name: my-crate-basics
description: Basics of my-crate. Use when building or validating widgets with my-crate.
---

Prefer using `Widget::builder()` over constructing widgets directly.
Always call `.validate()` before passing widgets to the runtime.

See the Skill definition reference for the full format and the agentskills.io quickstart for writing effective skills.

Embedding skills in your crate (recommended)

If you maintain the crate, we recommend shipping skills directly in your source tree. This way users always get skills matching the exact version they have installed.

1. Put skills in your crate sources under skills/

my-crate/
    Cargo.toml
    src/
        lib.rs
    skills/
        basics/
            SKILL.md
        advanced-patterns/
            SKILL.md

2. Publish your crate

That is all Symposium needs. When a project depends directly on my-crate, an interactive cargo agents sync offers to enable its plugin, and cargo agents status lists it as a candidate until the user decides. cargo agents use my-crate enables it directly, even for a project that doesn’t depend on the crate.

Symposium reads your plugin from the published package, so make sure skills/ (and Symposium.toml, if you have one) are part of it: check with cargo package --list (add --allow-dirty if you have uncommitted changes), and add them to include if your Cargo.toml uses that field.

Prefer a directory other than skills/?

Add [package.metadata.symposium] to your crate’s Cargo.toml to declare your own skills directory. This block uses the same schema as a Symposium.toml plugin manifest:

# In your crate's Cargo.toml
[[package.metadata.symposium.skills]]
source.path = "docs/agent-skills"

By default, Symposium looks for skills in skills/. Adding a skills section does not disable this default, it adds another source for skills in addition to the default. If you wish to disable the default, set [package.metadata.symposium.defaults] skills = false. If you only want to use the default location, you don’t even need a Symposium.toml. See Supporting your crate for the full schema including chained references to other crates.

Ship a full Symposium.toml in your crate

For more than a single custom directory (several skill groups, per-group predicates, a git skill source, hooks, or MCP servers), put a Symposium.toml at your crate root. When the crate’s plugin loads, whether the user enabled it or a [[plugins]] source.cargo reference reached it, that manifest is loaded as a first-class plugin:

# `my-crate/Symposium.toml` (in your crate's source tree)
[[skills]]
source.path = "docs/agent-skills"

[[skills]]
depends-on = ["tokio"]
source.path = "docs/async-skills"

Because reaching your crate is already the gate, a crate manifest doesn’t need name (it defaults to the crate) or a top-level depends-on. The default skills/ group is still appended unless you opt out with [defaults] skills = false. The [package.metadata.symposium] block and a Symposium.toml file are the same manifest schema and are combined when both are present: lists from both are kept, and where both set the same value the Symposium.toml file wins. Use whichever is convenient.

Hooks, MCP servers, and subcommands declared in a crate Symposium.toml load just like its skills.

Standalone skills (on the recommendations repo)

You can also upload skills directly to the recommendations repo — without embedding them in the crate source. This is the right approach when you’re writing skills for a crate you don’t maintain.

Place skill directories alongside your Symposium.toml:

my-crate/
    Symposium.toml
    basics/
        SKILL.md
    advanced-patterns/
        SKILL.md

And point the manifest at the local directory:

name = "my-crate"
depends-on = ["my-crate"]

[[skills]]
source.path = "."

The manifest’s depends-on says which crate the skills apply to, so the skills themselves don’t need one.

A skill can also be an entry on its own: a directory in the recommendations repo holding just a SKILL.md, with no Symposium.toml. Such a skill names the crates it applies to with depends-on in its frontmatter (or a depends-on(...) predicate in predicates). Without one it loads dormant, and only users who run cargo agents use <skill-name> get it:

---
name: widgetlib-basics
description: Basics of widgetlib. Use when building or configuring widgets with widgetlib.
depends-on: widgetlib=1.0
---

Guidance body here.

Skills from a git repository

Symposium also supports fetching skills from a GitHub URL:

[[skills]]
source.git = "https://github.com/org/my-crate/tree/main/symposium/skills"

This is useful for hosting skills in a dedicated repository or a subdirectory of a monorepo. Note that the central recommendations repository does not currently accept source.git entries by policy — use a [[plugins]] source.cargo chained reference or source.path for submissions there.

Installing auxiliary tools

An installation tells symposium how to obtain a binary that your hooks or subcommands will run. The recommended approach is a cargo installation, which installs a crate binary from crates.io:

[[installations]]
name = "my-crate-hooks"
source = "cargo"
crate = "my-crate-hooks"
executable = "my-crate-hooks"

Symposium installs the binary into its cache (~/.symposium/cache/) the first time a hook needs it, and checks crates.io for a newer release at the start of each agent session, unless the installation pins an exact version.

The binary must be installable with cargo install: publish it as its own crate, as above, or add a [[bin]] target to your main crate and set crate = "my-crate" with executable naming that binary.

See the plugin definition reference for other installation sources (GitHub repositories, local paths) and advanced options like install_commands.

Hooks

Hooks run when the AI performs certain actions — invoking a tool, starting a session, or submitting a prompt. They receive JSON on stdin describing the event and can return guidance, inject context, or block the action.

Every agent varies in the specifics of what hooks it offers and how those hooks are configured. Symposium allows you to provide agent-specific hook handlers, but we recommend instead using a Symposium hook handler, which is portable across agents. Hooks run on every supported agent except Goose and OpenCode, which have no shell hooks Symposium can register (they still receive skills and MCP servers).

Symposium hooks (portable across agents)

To define a Symposium hook handler you add a [[hooks]] section. This defines the command to run as well as the events it expects and other filters.

[[hooks]]
name = "check-usage"
event = "PreToolUse"
matcher = "^(Bash|bash|run_command|execute_bash)$"
command = "my-crate-hooks"

The matcher is a regular expression tested against the tool name. Agents name the same tool differently (the shell is Bash in Claude Code and Codex, bash in Copilot, run_command in Antigravity, and execute_bash in Kiro). The tool name reaches your handler exactly as the agent sent it, and the input keeps the agent’s own argument names, so match every name you care about. See Matcher for the details.

The command field references the name of an installation defined in the [[installations]] section described previously. For example:

[[installations]]
name = "my-crate-hooks"
source = "cargo"
crate = "my-crate-hooks"
executable = "my-crate-hooks"

The hook binary receives symposium canonical JSON on stdin and writes symposium canonical JSON to stdout. Symposium handles converting to and from each agent’s wire format, so a single implementation works on every agent that runs hooks. See Writing a hook handler for how to implement the binary using the symposium-sdk crate, and Symposium hook events for input/output JSON schemas.

Agent-specific hooks

You can also provide hooks specialized for a particular agent by setting format to an agent name. The handler receives that agent’s native wire format on stdin — giving you access to agent-specific features (e.g., Claude Code’s updatedInput, Copilot’s modifiedArgs). Symposium still intermediates; it just delivers in the declared format instead of converting to canonical. On agents without a matching hook, symposium falls back to delivering any symposium-format hook the plugin declares.

[[hooks]]
name = "check-usage-claude"
event = "PreToolUse"
format = "claude"
command = "my-crate-hooks"
args = ["--claude"]

On Claude, check-usage-claude fires (receives Claude’s native JSON). On other agents, check-usage fires (receives symposium canonical JSON). See the plugin definition reference for the full [[hooks]] manifest syntax.

MCP servers

MCP servers expose tools and resources to agents via the Model Context Protocol. Symposium registers them into each agent’s configuration during sync — you declare the server once and it works across all agents.

[[mcp_servers]]
name = "my-crate-tools"
command = "my-crate-mcp"
args = ["--stdio"]
env = []

command is written into the agent’s MCP configuration as is, so it must be an absolute path or a program on the user’s PATH. Unlike hooks, MCP servers don’t use [[installations]]: Symposium does not install the server, so tell your users how to install it, for example in your README (cargo install my-crate-mcp). args and env are required, even when empty.

See the plugin definition reference for HTTP and SSE transports, crate filtering, and registration details.

Subcommands

A subcommand lets agents run your crate’s own command-line tool through cargo agents, so they can find crate-aware tooling before they work on the code. By convention a crate adds one subcommand named after itself, and its tool handles everything typed after that name: cargo agents my-crate --help prints your tool’s help, and cargo agents my-crate check runs its check command.

[[installations]]
name = "my-crate-cli"
source = "cargo"
crate = "my-crate-cli"
executable = "my-crate-cli"

# `cargo agents my-crate check` runs `my-crate-cli check`
[subcommand.my-crate]
description = "Check and inspect the widgets in this workspace"
command = "my-crate-cli" # the [[installations]] entry that provides the tool

cargo agents --help lists the subcommand under “Commands for agents” with its description, and on agents that run hooks, Symposium suggests running cargo agents --help at the start of each session in a project that has one. Your tool’s output and exit code are passed through. See the plugin definition reference for the other [subcommand.<name>] fields.

Step 3. Validate your plugin

Before submitting a PR to the recommendations repo, validate your entry to catch errors early: missing fields, bad crate predicates, unreachable skill paths, and crate names that don’t exist on crates.io. Run this from the root of your local checkout once you’ve prepared your changes:

# Validate every entry in the checkout
cargo agents plugin validate .

# Skip the crates.io name check (e.g., for private crates)
cargo agents plugin validate . --no-check-crates

Pass the directory that contains your entry, not the entry’s own directory: a directory holding a Symposium.toml or SKILL.md is an entry, not a registry.

To try the entry before opening the pull request, copy its directory into ~/.symposium/plugins/ (a registry Symposium reads by default), run cargo agents sync in a project that depends on the crate, and delete the copy when you are done.

Step 4. Try it in a project

Before publishing, check what your users will get. In a scratch project that depends on your crate by path, enable the plugin (this assumes you have run cargo agents init):

cargo new try-my-crate && cd try-my-crate
cargo add my-crate --path ../my-crate
cargo agents use my-crate
cargo agents status

cargo agents use records the choice and syncs, and cargo agents status should list your plugin as active; if it doesn’t, see Edge cases. Its skills are now in each configured agent’s skills directory, for example .claude/skills/ for Claude Code.

To try a hook or subcommand before its binary is published, point the installation at your local build: drop source and crate, and set executable to the binary’s absolute path:

[[installations]]
name = "my-crate-hooks"
executable = "/path/to/my-crate-hooks/target/debug/my-crate-hooks"

Then, from the scratch project, run a subcommand as an agent would, for example cargo agents my-crate --help. To try a hook, send Symposium the payload an agent would send, using a tool call your hook reacts to (this one runs ls). This runs the same dispatch the agent triggers, so it prints what the agent would receive:

echo '{"session_id":"test","cwd":"'"$PWD"'","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls"}}' \
  | cargo agents hook claude pre-tool-use

Each agent has its own payload format; see Agent details for the others. If nothing happens, rerun the command with --verbose to see which plugins and hooks Symposium considered, and check the logs in ~/.symposium/logs/.

When you are done, remove the test enablement with cargo agents use my-crate --remove. Before you publish, restore the source = "cargo" installation and publish the hook or subcommand crate first: your users’ agents install it from crates.io.

A path dependency reads your source tree, so it doesn’t catch files missing from the published package; check those with cargo package --list (see step 2 of Embedding skills in your crate).

Inside your crate’s own repository, a Symposium.toml or skills/ directory is already active as a workspace plugin ([package.metadata.symposium] is not read there), which is handy while writing skills. Its hooks and MCP servers are active there too; gate a component with predicates = ["not(workspace-member())"] to keep it for your users only.

Writing a hook handler

This guide walks through writing a symposium hook handler in Rust using the symposium-sdk crate.

Step 1. Create a new binary crate

Create your new crate. A separate crate next to your library (for example my-crate-hooks) keeps the SDK out of your library’s dependencies:

cargo new my-crate-hooks
cd my-crate-hooks

And then add symposium-sdk to your dependencies, along with anyhow, which the handler methods return:

cargo add symposium-sdk anyhow

Step 2. Write the handler

A hook handler is a program that reads a JSON event on stdin and writes a JSON response to stdout. The symposium-sdk crate provides a HookHandler trait and a run() harness that handles the plumbing.

Implement HookHandler and override the methods for the events you care about:

// src/main.rs
use std::process::ExitCode;
use symposium_sdk::hook::{HookHandler, PreToolUseInput, PreToolUseOutput, run};

// The shell tool's name in Claude Code and Codex, Copilot, Antigravity, and Kiro.
const SHELL_TOOLS: &[&str] = &["Bash", "bash", "run_command", "execute_bash"];

struct MyHook;

impl HookHandler for MyHook {
    async fn pre_tool_use(&self, event: &PreToolUseInput) -> anyhow::Result<PreToolUseOutput> {
        if SHELL_TOOLS.contains(&event.tool_name.as_str()) {
            Ok(PreToolUseOutput::context("Remember: prefer non-destructive commands"))
        } else {
            Ok(PreToolUseOutput::default())
        }
    }
}

fn main() -> ExitCode {
    run(MyHook)
}

The run() function:

1. Reads symposium canonical JSON from stdin.
2. Deserializes it into an Input event.
3. Calls handler.handle_event(), which dispatches to the appropriate method.
4. Serializes the output to stdout.

You only need to override the methods you care about — unimplemented methods return the default (empty) output for their event type.

tool_name arrives exactly as the agent sent it, and tool_input keeps the agent’s own argument names, so check every name you want to handle (Antigravity’s shell, for example, takes CommandLine rather than command); see Matcher.

Step 3. Register it in your plugin manifest

Publish the handler to crates.io, then reference it as a hook command in your plugin’s Symposium.toml:

[[hooks]]
name = "check-usage"
event = "PreToolUse"
matcher = "^(Bash|bash|run_command|execute_bash)$"
command = { source = "cargo", crate = "my-crate-hooks", executable = "my-crate-hooks" }

Symposium installs the binary (with cargo binstall or cargo install) the first time the hook runs. A manifest shipped in your crate needs nothing else; a recommendations-repository entry also sets name and depends-on (see Authoring a plugin).

Output types

Each handler method returns its event-specific output type:

Each output type has convenience constructors:

• ::default(): empty output, no-op.
• ::context("..."): inject text into the agent’s context. On Stop, agents treat this output differently; see Stop output.
• PreToolUseOutput::with_updated_input(value): replace the tool input. Not every agent can apply a rewrite; see how each agent receives the decision.
• PreToolUseOutput::deny("reason"): block the tool call with a reason.

Return Err(...) from any method to report an error (exit code 1, message on stderr).

The HookHandler trait

#![allow(unused)]
fn main() {
pub trait HookHandler {
    async fn handle_event(&self, input: &Input) -> anyhow::Result<Output> { /* dispatches */ }
    async fn pre_tool_use(&self, event: &PreToolUseInput) -> anyhow::Result<PreToolUseOutput> { /* default */ }
    async fn post_tool_use(&self, event: &PostToolUseInput) -> anyhow::Result<PostToolUseOutput> { /* default */ }
    async fn user_prompt_submit(&self, event: &UserPromptSubmitInput) -> anyhow::Result<UserPromptSubmitOutput> { /* default */ }
    async fn session_start(&self, event: &SessionStartInput) -> anyhow::Result<SessionStartOutput> { /* default */ }
    async fn stop(&self, event: &StopInput) -> anyhow::Result<StopOutput> { /* default */ }
}
}

Override handle_event only if you need custom dispatch logic (e.g., shared state across events). Otherwise, just override the per-event methods.

Testing locally

You can test your handler by piping JSON directly:

cargo build
echo '{"PreToolUse":{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":null,"cwd":"/tmp"}}' \
  | ./target/debug/my-crate-hooks

To run it through Symposium the way an agent does, see Try it in a project.

Example: blocking destructive commands

This example reads Claude Code’s Bash tool; to cover other agents, check their tool names as in Step 2 and read Antigravity’s CommandLine as well.

//! A `PreToolUse` handler that refuses destructive shell commands.
//!
//! ```bash
//! echo '{"PreToolUse":{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":null,"cwd":"/tmp"}}' \
//!   | cargo run --example block_destructive
//! ```

use std::process::ExitCode;

use symposium_sdk::hook::{HookHandler, PreToolUseInput, PreToolUseOutput, run};

/// Fragments that are never worth running, whatever the surrounding command.
const DESTRUCTIVE: &[&str] = &["rm -rf /", "mkfs", "dd if=", ":(){ :|:& };:"];

struct BlockDestructive;

impl HookHandler for BlockDestructive {
    async fn pre_tool_use(&self, event: &PreToolUseInput) -> anyhow::Result<PreToolUseOutput> {
        if event.tool_name != "Bash" {
            return Ok(PreToolUseOutput::default());
        }

        let command = event
            .tool_input
            .get("command")
            .and_then(|value| value.as_str())
            .unwrap_or_default();

        match DESTRUCTIVE.iter().find(|needle| command.contains(**needle)) {
            Some(needle) => Ok(PreToolUseOutput::deny(format!(
                "refusing a command containing `{needle}`"
            ))),
            None => Ok(PreToolUseOutput::default()),
        }
    }
}

fn main() -> ExitCode {
    run(BlockDestructive)
}

Example: injecting context on session start

//! A `SessionStart` handler that puts a project's notes in front of the agent.
//!
//! ```bash
//! echo '{"SessionStart":{"session_id":null,"cwd":"/path/to/project"}}' \
//!   | cargo run --example inject_context
//! ```

use std::path::Path;
use std::process::ExitCode;

use symposium_sdk::hook::{HookHandler, SessionStartInput, SessionStartOutput, run};

struct InjectContext;

impl HookHandler for InjectContext {
    async fn session_start(&self, event: &SessionStartInput) -> anyhow::Result<SessionStartOutput> {
        let Some(cwd) = event.cwd.as_deref() else {
            return Ok(SessionStartOutput::default());
        };

        // A missing file is the ordinary case, not an error: most sessions
        // start somewhere with no notes to offer.
        match std::fs::read_to_string(Path::new(cwd).join("NOTES.md")) {
            Ok(notes) => Ok(SessionStartOutput::context(notes)),
            Err(_) => Ok(SessionStartOutput::default()),
        }
    }
}

fn main() -> ExitCode {
    run(InjectContext)
}

Reference

The reference defines the behavior of the Symposium system in detail.

The cargo agents command

cargo agents manages agent extensions for Rust projects. It discovers skills based on your project’s dependencies and configures your AI agent to use them.

Subcommands

Global options

The -v and --json flags work with sync, plugin list, and plugin validate. During hook dispatch, decision events are emitted at debug level and appear in verbose output when testing hooks.

cargo agents init

Set up Symposium for the current user.

Usage

cargo agents init [OPTIONS]

Behavior

Prompts for which agents you use (e.g., Antigravity CLI, Claude Code, Copilot) and where to install hooks, writes ~/.symposium/config.toml, and registers hooks for each selected agent.

If a user config already exists, init updates it (preserving existing settings not affected by the flags).

Options

Examples

Interactive setup:

cargo agents init

Non-interactive, specifying agents directly:

cargo agents init --add-agent claude --add-agent antigravity

Adding an agent to an existing config:

cargo agents init --add-agent copilot

Removing an agent:

cargo agents init --remove-agent antigravity

cargo agents sync

Synchronize skills with workspace dependencies.

Usage

cargo agents sync

With the global -v flag, sync additionally shows each plugin, skill group, and skill that was evaluated and why each was included or skipped. With --json, stdout receives a JSON array of structured event objects (see global options).

Behavior

Must be run from within a Rust workspace. Performs the following steps:

1. Find workspace root: runs cargo metadata to locate the workspace.

2. Scan dependencies: reads the full dependency graph from the workspace.

3. Discover applicable skills: loads plugin sources (from user config) and matches skill predicates against workspace dependencies.

4. Install skills: for each configured agent, copies applicable SKILL.md files into the agent’s expected skill directory (e.g., .claude/skills/ for Claude Code, .agents/skills/ for Antigravity/Copilot/Codex). A .gitignore containing * is written into every new skill directory, and an empty .symposium marker file is dropped into each installed skill directory.

5. Mirror workspace skills: if agents-syncing is enabled (default), user-authored skills in <workspace>/.agents/skills/ are propagated into the skill directories of any configured agent that doesn’t natively use .agents/skills/ (e.g., .claude/skills/, .kiro/skills/). See Workspace skills.

6. Clean up stale skills: scans every agent’s skills parent directory and removes any subdirectory containing the .symposium marker that wasn’t installed (or propagated) this sync. Directories without the marker (user-managed) are left untouched. If a registry cannot be read (a path that is missing, unreadable or itself a plugin, or a git registry that has not been fetched yet), sync warns, naming the registry, and skips this step: nothing is removed until it can be read again.

7. Register hooks: ensures hooks and MCP servers are registered for all configured agents, at the scope set by hook-scope: the user’s home directory for "global" (the default), the project for "project" (MCP servers fall back to the user level for agents without a project-level file). Unregisters hooks for agents no longer in the config. An agent config file symposium cannot parse is left untouched: sync names it in a warning and carries on with the skills and the other agents, while cargo agents init stops with that error.

Consent prompt

Before syncing, an interactive cargo agents sync asks about each dependency whose source embeds an agent plugin that you have not decided about yet. Depending on a crate means compiling its code, not letting its author inject agent context, so these stay off until you say otherwise. Three answers:

• Ask me later (the default) — records nothing; you are asked again next time.
• Enable — recorded in [plugins] auto-enable, and installed by this same sync.
• No — don’t ask again — recorded in [plugins] disable.

Only explicit answers are recorded, so hitting Enter through the prompt never permanently declines anything. Escape leaves the remaining questions undecided.

The prompt only runs in a real terminal session. The automatic sync below — and anything else an agent triggers — never prompts. Instead, your agent is told so it can point you here: pending candidates are named when a session starts, and when your dependencies change mid-session the agent hears that there may be new ones. cargo agents status lists them as candidate.

Automatic sync

By default (auto-sync = true), cargo agents sync runs automatically during hook invocations. This keeps skills in sync with workspace dependencies without manual intervention. Set auto-sync = false in the user config to disable this and sync manually.

Example

# One-time setup
cargo agents init --add-agent claude

# Sync skills for the current workspace
cargo agents sync

cargo agents search

Find plugins across every configured registry.

Usage

cargo agents search <QUERY>

Options

Behavior

The query is a case-insensitive substring match — the same looseness cargo search has. Results come from two arms and are printed grouped by the instance each hit came from:

1. Already loaded — plugin names in the plugin registry (a bare SKILL.md is loaded as a plugin, so it appears here too). A configured registry is a trust root, so a hit here is available now, with no use needed (unless the plugin is dormant, which is noted).
2. Offered by a package manager — each configured registry’s package manager is searched in turn.

A package manager without a searchable registry contributes nothing rather than failing, and an instance that errors outright (an offline registry, say) is skipped — so search degrades to the results it can get instead of failing the command.

With --json, each hit is emitted as a search_match event carrying its origin, name, and — where the registry provides them — version and description.

Example

$ cargo agents search widget
ℹ️  from user-plugins:
  widget-guidance
      Guidance for working with widgets
ℹ️  from symposium-recommendations:
  widget-skills 1.2.3
      Skills for widget

Pass a name from the output to cargo agents use to enable it.

cargo agents use

Enable a plugin by name, and sync it into the workspace immediately.

Usage

cargo agents use <NAME> [--global]
cargo agents use <NAME> --remove [--global]

Options

Behavior

use is the durable, by-name form of consent. It records a use entry in the [plugins] section of the user config:

[plugins]
use = [
  "everywhere-plugin",                                    # --global
  { name = "crate-a", workspace = "/home/me/my-project" }, # default
]

Then it runs a sync, so the plugin’s skills install right away rather than waiting for the next one.

Two things a use entry can enable:

• A dependency’s embedded plugin. Depending on a crate means compiling its code, not letting its author inject agent context, so a dependency is not a trust root — its embedded plugin stays off until you say otherwise. use is the by-name way to say so ([plugins] auto-enable is the ahead-of-time way).
• A dormant registry plugin. A plugin whose manifest names no dependency has nothing to gate it on, so it loads dormant. A use entry naming it is what wakes it.

Anything a configured registry already offers under a depends-on gate is enabled by configuration — pointing config at a registry is the act of trusting its curation — so use-ing it is a no-op and reports as such.

Enablement is not activation: use only adds to what may run. The plugin’s own predicates still decide when it applies.

The name must resolve to something before it is recorded — a dormant registry plugin, a workspace dependency, or a registry search hit — otherwise the command errors and writes nothing. Use cargo agents search to find the right name.

--remove

Removes the entry in the matching scope: without --global the entry recorded for the current workspace, with it the unscoped one. A scope mismatch (or no entry at all) is an error rather than a silent success. The sync that follows reaps the plugin’s installed skills.

Example

cargo agents search widget      # find it
cargo agents use widget-skills  # enable it here
cargo agents status             # confirm why it is on
cargo agents use widget-skills --remove

cargo agents status

Show which plugins are enabled for this workspace, and why.

Usage

cargo agents status

Must be run from within a Rust workspace.

Behavior

Symposium separates two questions. Enablement asks whether a plugin may run at all; activation predicates ask when it applies. status reports both, one line per plugin, each naming its enablement root — so it answers “why is this here?” with “enabled via serde”.

Each line is in one of four states:

Discovery is cache-only, so a dependency whose source has not been fetched yet is simply not listed as a candidate. Enabling it by name still works.

With --json, each line is emitted as a plugin_status event carrying name, state, root, and — for a discovered dependency plugin — the resolved version.

Example

$ cargo agents status
✅ my-tool — workspace member
✅ serde-skills 1.0.0 — `[plugins] use`
💤 team-conventions — registry `user-plugins` (dormant: awaiting `cargo agents use`)
❓ widget-lib 0.3.1 — found via dependency `widget-lib`, awaiting consent (`cargo agents use widget-lib`)
➖ noisy-crate — declined (`[plugins] disable`)

cargo agents self-update

Update symposium to the latest version.

Usage

cargo agents self-update

Behavior

1. Check for updates — runs cargo search against the configured registry to find the latest published version of symposium. If the installed version is already current, prints a message and exits.

2. Install — runs cargo install symposium --force to build and install the latest version.

Configuration

The auto-update key in ~/.symposium/config.toml controls update behavior. It is also configurable during cargo agents init.

auto-update

The 24-hour throttle is tracked in ~/.symposium/state.toml. The check is skipped for self-update itself (which always checks unconditionally).

State file

~/.symposium/state.toml tracks:

• version — the semver of the binary that last ran. Updated on every invocation. Future versions can use a version mismatch to trigger migrations.
• last-update-check — timestamp of the last registry query. Used to throttle checks to once per 24 hours.

Examples

Manual update:

cargo agents self-update

Disable all update checks:

# ~/.symposium/config.toml
auto-update = "off"

Warn instead of auto-updating:

# ~/.symposium/config.toml
auto-update = "warn"

cargo agents plugin

Manage plugin sources.

Usage

cargo agents plugin <SUBCOMMAND>

Subcommands

cargo agents plugin sync

cargo agents plugin sync [PROVIDER]

Fetch or update git-based plugin sources. If a provider name is given, syncs only that provider (ignoring auto-update settings). If omitted, syncs all providers that have auto-update = true.

cargo agents plugin list

cargo agents plugin list

List all configured plugin sources and the plugins they provide.

cargo agents plugin show

cargo agents plugin show <PLUGIN>

Show a plugin: its id and its effective configuration as TOML, after validation has filled in defaults and promoted inline installations.

cargo agents plugin validate

cargo agents plugin validate <PATH> [--no-check-crates]

Validate a plugin source directory or a single TOML manifest file. Useful when authoring plugins.

cargo agents crate-info

Find crate sources and guidance.

This is an agent-facing command, listed under “Commands for agents” in cargo agents --help. Its output format and exit codes may change in future releases.

Usage

cargo agents crate-info <NAME> [--version <VERSION>]

Behavior

Fetches the crate’s source code and returns:

• Path to the extracted crate source
• Available skills for the crate

Options

cargo agents telemetry

Manage opt-in, per-user usage telemetry. See the telemetry design chapter for the event format and the [telemetry] configuration for the underlying config key.

Telemetry is off by default, local-first, and never uploaded automatically — you share it yourself. The preference is also offered during cargo agents init.

Usage

cargo agents telemetry [status]      # whether enabled, where data lives, how much is stored (default)
cargo agents telemetry enable        # turn on collection (writes [telemetry] enabled = true)
cargo agents telemetry disable       # turn it off
cargo agents telemetry show [--count N]   # print recent events (JSON lines) for inspection

Where the data lives

When recording is wired in, anonymous events will be appended as JSON lines to per-day files under ~/.symposium/telemetry/ (e.g. events-2026-06-23.jsonl), with files older than 30 days rolled off automatically. Events record counts and coarse metadata only (session starts, prompts, tool names) — no prompt text, command lines, or file paths.

Unstable agent commands

The commands in this section are invoked by AI agents, not by users directly. They are hidden from cargo agents --help, and their arguments, output format, and exit codes may change in future releases without notice.

Currently this is cargo agents hook, the hook protocol entry point. (crate-info is also agent-facing but is no longer hidden — it appears under “Commands for agents” in cargo agents --help.)

cargo agents hook

Entry point invoked by your agent’s hook system. This is an internal command — you generally don’t need to run it yourself.

Usage

cargo agents hook <AGENT> <EVENT>

Behavior

When your agent triggers a hook event, it calls cargo agents hook with the agent name and event type. The hook does two things:

1. Auto-sync (if enabled) — when auto-sync = true in the user config, runs cargo agents sync to ensure skills are current for the workspace. The workspace root is resolved from the hook payload’s cwd field; if the payload does not include a working directory, the process’s current working directory is used as a fallback. Failures are logged but don’t block hook dispatch.

2. Dispatches to plugin hooks — runs any hook handlers defined by plugins for the given event.

Output

Stdout carries only the response for your agent, in its own format. Sync progress goes to the log file, and whatever a plugin’s install_commands print goes to stderr. To see the progress when running a hook by hand, pass -v: cargo agents -v hook <AGENT> <EVENT> prints it to stderr.

Events

The specific events depend on which agent you are using. cargo agents init configures the hook registration appropriate for your agents.

When is the hook invoked?

The hook is registered globally during cargo agents init. It runs automatically when your agent triggers supported events (e.g., session start, tool use).

Supported agents

Symposium supports seven AI coding agents. Each agent gets skill installation; hook support varies by agent.

Antigravity CLI

Config name: antigravity

Google’s Antigravity CLI, invoked as agy. Antigravity ships three surfaces — the CLI, the IDE and the web app — which share the same configuration roots, so what symposium writes applies to all of them.

Skills

Hooks

Symposium merges a single named entry, symposium, into Antigravity’s hooks.json. Other entries in the file are left alone, and only symposium’s own is removed when the agent is unconfigured.

Events registered: PreToolUse, PostToolUse, PreInvocation, SessionStart, Stop.

Output format: JSON. Timeouts are in seconds (30 by default). Exit codes are ignored — only what a hook writes to stdout affects the agent. Context reaches the model at session start and on the first PreInvocation of a turn; after a tool call it does not (PostToolUse output carries nothing back), and on PreToolUse only a denial’s reason is shown.

Caveat: PreInvocation stands in for symposium’s user-prompt-submit because Antigravity has no prompt event. It fires before every model call, so symposium runs the prompt event only on the first invocation of a turn.

Caveat: in headless print mode (agy -p), Antigravity adopts no workspace unless it is given --add-dir <absolute path> — it cannot read project files and loads no project .agents/ configuration. A relative path is ignored. Ordinary interactive use is unaffected; this only matters for automation and CI.

MCP servers

Unlike Gemini CLI, MCP configuration lives in its own file rather than sharing one with hooks. agy mcp add has no scope flag and writes the global file.

Claude Code

Config name: claude

Skills

Claude Code does not support the vendor-neutral .agents/skills/ path.

Hooks

Symposium merges hook entries into Claude Code’s settings.json.

Events registered: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop (PascalCase).

Output format: JSON with hookSpecificOutput wrapper. Exit code 2 blocks tool use.

MCP servers

MCP servers do not go in settings.json, which holds only the hooks.

GitHub Copilot

Config name: copilot

Skills

Copilot has no global skills path.

Hooks

Symposium creates a symposium.json file in the project hooks directory, and merges entries into the hooks key of the global settings.

Events registered: preToolUse, postToolUse, userPromptSubmitted, sessionStart (camelCase).

Output format: JSON. Uses "bash" key instead of "command" for platform-specific dispatch. Any non-zero exit code denies (not just exit 2).

Caveat: Copilot loads a project’s hooks only once you trust the folder (it asks the first time you open it).

Caveat: Copilot also runs the hooks in .claude/settings.json. In a project where Claude Code is configured too, each Copilot event runs cargo agents hook twice, once as each agent.

MCP servers

Copilot reads no project-level MCP file, so a project-scoped registration goes to the global file.

Codex CLI

Config name: codex

Skills

Hooks

Symposium merges hook entries into Codex’s hooks.json.

Events registered: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart (PascalCase).

Output format: JSON. Exit code 2 blocks tool use.

Caveat: Codex runs a hook only after you trust it. Until then it skips the hook, warning at startup; open /hooks in Codex to review and trust symposium’s entries. A changed entry needs trusting again. Project hooks also require the project itself to be trusted.

MCP servers

Codex reads no project-level MCP file, so a project-scoped registration goes to the global file.

Kiro

Config name: kiro

Skills

Kiro uses its own skill path, not the vendor-neutral .agents/skills/.

Hooks

Kiro requires hooks to be registered with a named agent. We create a symposium agent by creating a symposium.json agent definition file in .kiro/agents/. This registers Symposium as a Kiro agent with hooks attached. If you use a different agent, you won’t benefit from hook-based features like token reduction unless you manually add the hooks into your agent definition.

Events registered: preToolUse, postToolUse, userPromptSubmit, agentSpawn (camelCase; agentSpawn maps to session-start internally).

Output format: plain text on stdout (not JSON). Exit code 2 blocks preToolUse only.

The generated agent file includes "tools": ["*"] (all tools available) and "resources": ["skill://.kiro/skills/**/SKILL.md"] (auto-discover skills). Without tools, a Kiro custom agent has zero tools.

Caveat: Kiro uses a flat hook entry format ({ "command": "..." }) unlike the nested format used by Claude/Codex. Unregistration deletes the symposium.json file entirely.

MCP servers

OpenCode

Config name: opencode

Skills

Hooks

OpenCode does not support shell-command hooks. Its extensibility is based on TypeScript/JavaScript plugins. Symposium cannot register hooks for OpenCode.

OpenCode is supported as a skills-only agent — cargo agents sync will install skill files, but no hooks are registered.

MCP servers

Goose

Config name: goose

Skills

Hooks

Not supported. Goose has no hook system. It uses MCP extensions for extensibility.

Skill files are installed but cargo agents hook will never be called by this agent.

MCP servers

Goose reads no project-level MCP file, so a project-scoped registration goes to the global file.

Configuration

cargo agents uses a single user-wide configuration file at ~/.symposium/config.toml. Created by cargo agents init.

Full example

auto-sync = true
agents-syncing = true
hook-scope = "global"
auto-update = "on"

[[agent]]
name = "claude"

[[agent]]
name = "antigravity"

[logging]
level = "info"

[defaults]
symposium-recommendations = true
user-plugins = true

[[registry]]
name = "my-org"
git = "https://github.com/my-org/symposium-plugins"

[[registry]]
name = "local-dev"
path = "my-plugins"

Top-level keys

Agents syncing: mirror user-authored skills

Agents such as Antigravity, Copilot, Codex, Goose, and OpenCode all read skills from the vendor-neutral .agents/skills/ directory, but Claude Code and Kiro use their own paths (.claude/skills/ and .kiro/skills/). When agents-syncing is enabled, every workspace plugin — the workspace root and each member directory — carries a second default skill group, gated by the workspace-member() predicate:

[[skills]]
predicates = ["workspace-member()"]
source.path = ".agents/skills"

Skills you author in .agents/skills/ therefore flow through the same pipeline as every other skill and install into each configured agent’s own skill directory, so a single authored copy is visible to every agent. The workspace-member() gate is what keeps these maintainer skills from installing for dependents of a published crate — they apply only while working in the workspace itself.

Two .symposium-marker rules keep sources and copies distinct (symposium never writes a marker into a source, only into directories it installs):

• Skill discovery skips marker-bearing directories, so copies symposium installed into .agents/skills/ (for agents that read it natively) are never re-discovered as sources.
• For an agent whose skill directory is .agents/skills/, a skill whose source already sits at its install slot is left in place — nothing is copied.

Installed copies receive the same marker and * .gitignore that plugin-installed skills get, which means: updates to the source are re-copied on each sync; removing the source removes the copies on the next sync (the normal stale-skill reap); disabling agents-syncing = false does the same; and a pre-existing user-managed directory in a target is never overwritten (the skill installs under a suffixed name instead).

Because these are real skills now, SKILL.md frontmatter must carry name and description like any other skill definition.

Hook scope: control whether Symposium activates in all projects or only those you select

Registering hooks globally ensures that Symposium activates whenever you use the selected agent, which means that it will work in any Rust project automatically.

Registering hooks at the project level requires you to run cargo agents sync within each project at least once to create the hooks. After that, the auto-sync feature will keep you up-to-date.

[[agent]]

Each [[agent]] entry identifies an agent you use. You can configure multiple agents.

[logging]

[telemetry]

Opt-in, per-user usage telemetry. Off by default. When enabled, Symposium appends anonymous events as JSON lines to a local, per-day log under ~/.symposium/telemetry/. Nothing is uploaded automatically — you inspect and share the data yourself with cargo agents telemetry show. The preference is also collected during cargo agents init. See the telemetry design chapter for the event format.

[telemetry]
enabled = true

[defaults]

Controls the two built-in registries. Both are enabled by default.

[[registry]]

Defines additional registries — directories or repositories offering plugins. Each entry must have exactly one of git or path. [[plugin-source]] is the retired spelling of this table and is still accepted.

[plugins]

Enablement: which plugins are allowed to run at all, as distinct from the predicates that decide when an enabled plugin applies.

Symposium trusts two things without asking: the workspace you are in, and the registries it is configured with. A registry exists to curate plugins, so enabling one is the act of accepting its curation. Both built-in registries count here and are on by default — user-plugins is your own directory, while symposium-recommendations is a list curated by the Symposium project and trusted until you turn it off in [defaults].

Your dependency list is deliberately not a trust root. Depending on a crate means compiling its code; it should not silently let the crate’s author add instructions to your agent. So a plugin embedded in a dependency runs only once you say so, and a registry plugin that names no dependency anywhere is dormant — loaded and listed, but inactive — until you enable it by name.

Trust follows whoever supplies the content, not the package the content is about: a registry entry recommending a plugin for serde is the registry’s own content and is trusted, while serde’s embedded plugin is not. One consequence is worth knowing: a trusted plugin may name a crate with a [[plugins]] chained reference, and that crate’s plugin content then loads without a [plugins] entry of its own — the registry is vouching for it.

Names are matched hyphen/underscore-insensitively, like crate names: widget-lib and widget_lib are the same entry.

[plugins]
auto-enable = ["widget-lib"]
disable = ["noisy-crate"]
use = ["standalone-plugin", { name = "team-tools", workspace = "/home/me/work/service" }]

use is what wakes a dormant plugin, and it also enables a plugin whether or not any dependency references it. auto-enable is narrower: it is consent for what a dependency you already have carries with it.

You rarely edit this section by hand. cargo agents use writes and removes use entries; the consent prompt in an interactive cargo agents sync writes auto-enable and disable; and cargo agents status reports what the section currently decides.

Directory resolution

User-wide data lives under ~/.symposium/ by default. Override with environment variables:

SYMPOSIUM_HOME takes precedence over XDG variables.

File locations

Plugin sources

A plugin source, configured as a [[registry]] entry and called a registry in the rest of these docs, is a local directory or a GitHub repository containing plugins and standalone skills that Symposium discovers automatically. Symposium searches it recursively to find all available extensions.

Discovery rules

Symposium scans a registry recursively to find plugins and standalone skills:

• A plugin is a directory that contains a Symposium.toml file. A registry plugin gets no default skills/ group: its skills load only through the [[skills]] groups its manifest declares (for example source.path = "skills").
• A directory that contains a SKILL.md and no Symposium.toml is loaded as a plugin with default values: named for the skill’s frontmatter name (required, as for every registry skill), with the skill’s frontmatter depends-on and predicates acting as the plugin’s activation gate. depends-on is optional: a skill that names no dependency loads dormant (it activates once you enable it by name with cargo agents use), exactly like a gateless Symposium.toml plugin.

We do not allow these entries to be nested within one another. When we find a directory that is either a plugin or a skill, we do not search its contents any further. The registry root itself must not be an entry: a root that contains a Symposium.toml or a SKILL.md is an error (cargo agents plugin validate fails, and a configured registry loads nothing). Put each plugin or skill in a subdirectory instead.

Example structure

plugin-source/
  my-plugin/
    Symposium.toml        # plugin
    skills/               # not a separate entry (loaded through my-plugin's [[skills]] groups)
      basic/
        SKILL.md
  serde-skill/
    SKILL.md              # standalone skill
  nested/
    deep/
      tokio-skill/
        SKILL.md          # standalone skill (found recursively)
  mixed/
    Symposium.toml        # plugin
    SKILL.md              # ignored (the plugin takes precedence)

Configuration

Registries are configured in your config.toml file. See the Configuration reference for details on setting up local directories, GitHub repositories, and built-in sources.

Validation

You can validate a registry directory:

# Validate all plugins and skills in a directory, checking that crate names exist on crates.io
cargo agents plugin validate path/to/plugin-source/

# Same, but skip the crates.io check
cargo agents plugin validate path/to/plugin-source/ --no-check-crates

This scans the directory, attempts to load all plugins and skills, and reports any errors found.

Plugin definitions

A symposium plugin collects together all the extensions offered for a particular crate. Plugins are directories containing a Symposium.toml manifest file that references skills, hooks, MCP servers, and other resources relevant to your crate. These extensions can be packaged within the plugin directory or the plugin can contain pointers to external repositories.

Plugins enable capabilities beyond standalone skills — they’re needed when you want to add hooks or MCP servers. For simple skill publishing, see Authoring a plugin instead.

Example: a plugin definition with inline skills

You could define a plugin definition with inline skills by having a directory struct like this:

myplugin/
  Symposium.toml
  skills/
    skill-a/
      SKILL.md
    skill-b/
      SKILL.md

where myplugin/Symposium.toml is as follows:

name = "example"
depends-on = ["*"]

[[skills]]
source.path = "skills"

Top-level fields

A registry plugin gets no default skill group: its skills load only through the [[skills]] groups it declares, so a registry plugin that ships a skills/ directory needs [[skills]] source.path = "skills". Crate and workspace plugins get the default skills/ group unless [defaults] skills = false (workspace plugins also get a .agents/skills group by default, see Workspace skills).

Note: A registry plugin that references no dependency anywhere is dormant: it loads, but it never activates until the user enables it by name in the [plugins] use config (for example with cargo agents use). Use depends-on = ["*"] for a plugin that should always be active. These count as referencing a dependency:

• a depends-on field, or a depends-on(...) predicate in a predicates list, on the plugin itself, a [[skills]] group, an [[mcp_servers]] entry, or a [[plugins]] edge;
• a depends-on(...) predicate in a [[hooks]] entry’s predicates;
• a custom predicate used directly in the plugin-level predicates.

A depends-on(...) predicate counts wherever it sits in the list, including depends-on(*) and one nested inside not, any, or all.

These do not count: the crate named by a [[plugins]] edge’s source.cargo, a [subcommand.<name>]’s depends-on or predicates, and the frontmatter of a SKILL.md inside a [[skills]] group. Crate and workspace plugins never go dormant: what loaded the crate (a chained reference or the user’s enablement), or membership in the active workspace, is their gate.

Plugin-level filtering

The top-level depends-on field controls when the entire plugin is active:

name = "my-plugin"
depends-on = ["serde", "tokio"]  # Only active in projects using serde OR tokio

Use the wildcard depends-on = ["*"] instead for a plugin that always applies.

Plugin-level filtering is combined with skill group filtering using AND logic — both must match for skills to be available.

[[skills]] groups

Each [[skills]] entry declares a group of skills.

A skill group must have exactly one of source.path or source.git. A crate is not a skill-group source; to load a crate’s own skills, name it in a chained plugin.

Chained plugins

A [[plugins]] entry names another plugin that loads whenever this plugin is active (the “a package is a plugin” edge). Today the referenced plugin is a crate, which always loads as a first-class plugin built from its manifest sources (see Crate-embedded manifest below). The referenced crate loads without a consent step of its own: the plugin that names it vouches for it (see Configuration).

name = "serde-plugin"

# When serde is a dependency, load serde's plugin (its skills).
[[plugins]]
depends-on = ["serde"]
source.cargo = "serde"

The edge’s depends-on decides whether to load the referenced crate; the crate name in source.cargo decides which crate. List several [[plugins]] entries to load several crates.

Only source.cargo is supported today; source.git / source.path chained plugins are reserved and rejected with a clear error.

Crate-embedded manifest

A referenced crate describes its plugin with the ordinary plugin-manifest schema, from two interchangeable sources: a Symposium.toml at its source root, and/or a [package.metadata.symposium] table in its Cargo.toml. Both are honored the same as a registry manifest: [[skills]] groups, per-group predicates, source.path / source.git sources, and further [[plugins]] chained references. The crate’s effective manifest is the two sources merged over the crate defaults (merge order defaults -> [package.metadata.symposium] -> Symposium.toml): list entries from both are kept; where the two set the same scalar, the file wins. Each source is parsed leniently: a malformed layer is logged and dropped, and the crate still resolves through the remaining layers (at minimum the default skills/ group). A merged manifest that parses but fails validation (for example a hook naming an unknown installation) disables the crate’s whole plugin, default skills/ group included.

Because the chained reference is already the gate, a crate manifest may omit name (defaults to the crate) and a top-level depends-on; the default skills/ group is appended unless [defaults] skills = false. A crate with no manifest sources at all still resolves as a plugin whose only content is that default skills/ group.

The opt-out belongs to the referenced crate, not the referrer. The edge decides only whether to load the crate (via its depends-on / predicates); it cannot toggle the crate’s defaults. So for an active edge to crate foo:

• foo ships nothing → its skills/ directory loads.
• foo declares [[skills]] source.path = "guidance" → both guidance/ and skills/ load (combined with defaults).
• foo declares [defaults] skills = false plus a custom group → only the custom group loads.
• foo declares [defaults] skills = false and nothing else → nothing loads.
• foo carries its own [[plugins]] source.cargo = "bar" → bar resolves the same way, recursively.

Everything a crate manifest declares loads like a registry plugin’s: skills, hooks, MCP servers, subcommands, custom predicates, and further [[plugins]] references.

Delegating to another crate

A crate can delegate to another crate with a [[plugins]] chained reference of its own:

# In the referenced crate's Cargo.toml (in its Symposium.toml, write the table as [[plugins]])
[[package.metadata.symposium.plugins]]
source.cargo = "companion-crate"

Chained references are followed until no new crate is reached; there is no depth limit. A crate reached through several references loads only once (crates are identified by name, hyphen/underscore-insensitively), which also makes cycles harmless, and a SKILL.md reached two ways installs once, since a skill is identified by the path of its SKILL.md. See Supporting your crate for the full crate-author walkthrough.

Installations

An installation describes how to obtain (and optionally pre-configure) something a hook, subcommand, or custom predicate will run. They reference an installation as their command, either by name (command = "mytool") or inline at the use site (command = { script = "scripts/x.sh" }).

A [[installations]] entry has a name plus any of:

executable and script are mutually exclusive — pick one. The hook layer applies the same rule, and at most one of executable / script may be set across the hook AND the installation it references. An installation may have neither (then it’s pure setup — useful as a requirements entry). For a hook to run, the chosen layer pair must end up with exactly one runnable.

Inline installations (used as command or as a requirement entry) accept the same fields, including requirements.

Installation sources

cargo

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
version = "13.0.0"     # optional; defaults to latest stable
executable = "rg"      # the binary to run; if omitted and the crate has a single binary, that one is used
args = ["--version"]   # optional default args

Symposium attempts cargo binstall first, falls back to cargo install, and caches the result under ~/.symposium/cache/binaries/<crate>/<version>/bin/ (passing --root so the install doesn’t pollute ~/.cargo/bin). The chosen executable resolves to <cache>/bin/<executable>. Hooks that depend on this installation get <cache>/bin/ prepended to $PATH, so scripts can invoke the binary by name.

To install from a git repo instead of crates.io, set git:

[[installations]]
name = "tool"
source = "cargo"
crate = "tool"
git = "https://github.com/example/tool"
executable = "tool"   # required for git sources (crates.io is not consulted)

To install into the user’s global cargo location (~/.cargo/bin) instead of a symposium-managed cache, set global = true. No --root is passed; $PATH is not augmented (the binary is expected to already be on $PATH). This can be useful if you are using scripts which require globally-installed programs, or if you want to use tools separately in a CLI. A global = true installation must set executable.

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
executable = "rg"
global = true

github

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"   # optional; see below
args = ["--format"]

Acquires the repo (or a subtree, if url points at …/tree/<ref>/<path>) into a local cache. The chosen executable / script resolves to a file inside the cached tree.

executable/script may be set on the installation or on the hook (but not both, in any combination). Setting it on the installation pins this entry to a specific file; omitting it lets multiple hooks each pick a different file.

no source

Omit source entirely when you just need to point at a path on disk (or rely on install_commands to put one there):

[[installations]]
name = "tool"
executable = "/usr/local/bin/tool"

Or “shell-only” installations — useful as side-effect requirements:

[[installations]]
name = "setup"
install_commands = [
    "ln -sf $HOME/.cache/foo $HOME/.local/bin/foo",
]

[[hooks]]

Each [[hooks]] entry declares a hook that responds to agent events. For the JSON schemas that symposium-format hooks receive and produce, see Symposium hook events.

Examples

Run a cargo-installed binary as the hook:

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
executable = "rg"

[[hooks]]
name = "rg-version"
event = "PreToolUse"
command = "rg"
args = ["--version"]

Install a tool as a side requirement and run a hook script from a separate github source:

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"

[[hooks]]
name = "rewrite"
event = "PreToolUse"
requirements = ["mytool"]
command = "mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"
args = ["--format"]

Inline a one-off cargo install directly:

[[hooks]]
name = "rg-test"
event = "PreToolUse"
command = { source = "cargo", crate = "ripgrep", executable = "rg" }
args = ["--version"]

Run a script file on disk (no source):

[[hooks]]
name = "check"
event = "PreToolUse"
command = { script = "scripts/check.sh", args = ["--strict"] }

A cargo install with a post-install step (e.g. to symlink a wrapper script):

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"
install_commands = [
    "ln -sf $HOME/.symposium/cache/binaries/mytool/*/bin/mytool $HOME/.local/bin/mytool",
]

[[hooks]]
name = "mytool-rewrite"
event = "PreToolUse"
command = "mytool"
args = ["rewrite"]

Agent-specific hooks

An agent-specific hook expects a particular agent’s native wire format on stdin. Use this when you need full access to an agent’s event schema. Symposium still intermediates, but an agent-specific hook fires only when Symposium runs for that agent, and receives that agent’s input unchanged. On every other agent it does not fire, and nothing is converted. To cover the other agents, pair it with a format = "symposium" hook.

A plugin with a Claude-specific hook and a symposium fallback:

[[installations]]
name = "my-hook-binary"
source = "cargo"
crate = "my-hook-binary"

[[hooks]]
name = "check-claude"
event = "PreToolUse"
format = "claude"
command = "my-hook-binary"

[[hooks]]
name = "check-portable"
event = "PreToolUse"
format = "symposium"
command = "my-hook-binary"
args = ["--symposium"]

On Claude, check-claude fires (receives Claude’s native JSON). On other agents, check-portable fires (receives symposium canonical JSON).

Requirements

requirements ensures other installations are acquired before the hook runs. Useful when the hook’s command relies on something else being on disk (or eventually on $PATH).

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[hooks]]
name = "uses-mytool-via-script"
event = "PreToolUse"
requirements = ["mytool", { source = "cargo", crate = "ripgrep" }]
command = { script = "scripts/uses-mytool.sh" }

Requirements may also be declared on an [[installations]] entry. Whenever that installation is referenced — as a hook’s command or in another requirements list — its declared requirements are appended (one level, prerequisites first):

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"
requirements = ["mytool"]   # mytool gets installed whenever mytool-hooks is used

[[hooks]]
name = "rewrite"
event = "PreToolUse"
command = "mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"

Requirement installation is best-effort: failures are logged and dispatch continues.

Hook environment

Hooks are spawned with the following extras on top of the parent environment:

<name> is the installation name with non-alphanumeric characters replaced by _ (e.g. mytool-hooks -> SYMPOSIUM_DIR_mytool_hooks). Both the hook’s command installation and every requirement (recursively, one level via installation-level requirements) contribute.

Global cargo installs (global = true) don’t set $SYMPOSIUM_DIR_<name> or augment $PATH — the binary is expected to already be on the user’s $PATH via ~/.cargo/bin.

install_commands runs before env vars are set. The $SYMPOSIUM_* vars and the augmented $PATH are only available to the hook’s spawned process. install_commands runs earlier, inside the symposium dispatch process, so it cannot reference its own (or any other) installation’s env vars. Use absolute paths in install_commands instead.

Supported hook events

Not every agent delivers every event, and agents name them differently. See Agent support for which events each agent delivers.

Hook semantics

• Exit codes:

  • 0 — success: the hook’s stdout is parsed as JSON and merged into the overall hook result.
  • 2 (or no reported exit code): block. The action is blocked, dispatch stops, and the hook’s stderr becomes the reason the agent is given. See exit codes for how each agent receives the block.
  • any other non-zero code — treated as success for dispatching purposes; stdout is still parsed and merged when possible.

• Stdout handling: Hooks should write a JSON object to stdout to contribute structured data back to the caller. Valid JSON objects are merged together across successful hooks; keys from later hooks overwrite earlier keys. The exception is additionalContext on SessionStart, UserPromptSubmit and PostToolUse: symposium’s own context and every hook’s are joined, in order, so none replaces another.

• Stderr handling: If a hook exits with code 2 (or no exit code), dispatch returns immediately with the hook’s stderr as the block reason. Otherwise stderr is captured but not returned on success.

Testing hooks

To exercise a hook end to end, pipe a real agent payload into cargo agents hook <agent> <event>, using the event’s CLI name from the table above. For Claude Code:

echo '{"session_id":"s","cwd":"/path/to/project","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | cargo agents hook claude pre-tool-use

This runs the full dispatch (including the automatic sync, when auto-sync is on) for the workspace at cwd, so the plugin must be installed and active there; the output is in the agent’s own format. The payload must be the named agent’s native JSON: you can also use antigravity, copilot, codex, or kiro as the agent name, each with that agent’s payload. To test a symposium-format handler on its own, pipe canonical JSON straight into it (see Testing).

[[predicate]]

Each [[predicate]] entry defines a custom predicate function that can be used in predicates expressions anywhere a predicate is accepted. Custom predicates extend the built-in predicate language with plugin-specific checks.

How custom predicates work

Custom predicates are registered globally — a predicate defined in one plugin can be used by any other plugin’s predicates expressions. Registration is unconditional: even if the defining plugin’s own crate predicates don’t match the current workspace, its [[predicate]] entries are still available.

When a predicate expression uses a function name that isn’t a builtin, Symposium looks it up in the custom predicate registry. If found, it spawns the declared command with the static args followed by the raw argument text from the expression.

[[installations]]
name = "cargo-bp-install"
source = "cargo"
crate = "cargo-bp"
executable = "cargo-bp"

[[predicate]]
name = "battery_pack"
command = "cargo-bp-install"
args = ["bp", "status", "--check"]

Usage in a predicates expression:

predicates = ["battery_pack(cli>=0.3)"]

This evaluates as:

cargo-bp bp status --check cli>=0.3

Exit 0 means the predicate passes; non-zero means it fails.

The argument is trimmed of leading/trailing whitespace before being passed. An empty argument — battery_pack() or battery_pack( ) — does not append anything to the command (only the static args are passed).

A custom predicate is a boolean gate only: it passes if the command exits 0. Its stdout does not affect the result; it may carry watch events that control caching.

Collisions

If two plugins define the same predicate name, both definitions are skipped and a warning is emitted. Skills referencing the collided name evaluate as false.

Caching

Symposium caches a custom predicate’s result on disk, per workspace (under ~/.symposium/cache/predicates/), keyed by the call as written (battery_pack(cli>=0.3)). Later syncs reuse the cached result without spawning the command until one of the inputs the predicate reported changes. Within one run, the same call is spawned at most once.

The predicate reports its inputs by printing watch events on stdout as JSON Lines, one object per line:

{"watchFile":"/path/to/project/Config"}
{"watchEnv":"LAMBDA_ENV"}
{"watchTime":60000}

The events from one run are combined, and a line that is not a known event is skipped with a warning. A predicate that exits non-zero is cached the same way as one that exits 0. A predicate that prints no events is cached forever, so report every input the result depends on, or print {"watchTime":0}. The cache is also discarded when a Symposium upgrade changes its format; delete ~/.symposium/cache/predicates/ to force every predicate to run again.

In Rust, the symposium-sdk crate prints these events for you: symposium_sdk::env::var and symposium_sdk::fs::read_to_string read a value and report it as an input, and symposium_sdk::predicate::PredicateEmitter writes events directly (watch_file, watch_env, watch_time).

[[mcp_servers]]

Each [[mcp_servers]] entry declares an MCP server that Symposium registers into the agent’s configuration during cargo agents sync (and the automatic sync that hooks run).

Symposium does not install MCP servers: unlike hooks and subcommands, they do not use [[installations]]. A stdio server’s command is written into the agent’s MCP configuration verbatim, so it must be an absolute path, or a command name the agent can find on the user’s PATH.

There are multiple MCP transports:

Stdio

[[mcp_servers]]
name = "my-server"
command = "/usr/local/bin/my-server"
args = ["--stdio"]
env = [{ name = "RUST_LOG", value = "info" }]

Stdio entries do not need a type field.

HTTP

[[mcp_servers]]
type = "http"
name = "my-server"
url = "http://localhost:8080/mcp"
headers = []

SSE

[[mcp_servers]]
type = "sse"
name = "my-server"
url = "http://localhost:8080/sse"
headers = []

How registration works

During cargo agents sync, each MCP server entry is written into each configured agent’s config file in the format that agent expects. Registration is idempotent — existing entries with correct values are left untouched, stale entries are updated in place.

When a user runs cargo agents sync (or the hook triggers it automatically), Symposium:

1. Collects [[mcp_servers]] entries from all enabled plugins.
2. Writes each server into the agent’s MCP configuration file.

All supported agents have MCP server configuration. Symposium handles the format differences — you declare the server once and it works across agents.

Servers are registered at the scope chosen by the hook-scope setting (see Configuration): with "project", in the files above; with "global" (the default), in each agent’s user-level configuration. Agents without a project-level file always get the user-level one. See each agent’s page under Supported agents for the global locations.

[subcommand.<name>]

A [subcommand.<name>] table adds a command that users and agents run as cargo agents <name>. By convention, <name> is the crate’s name, so an agent can run cargo agents <crate> --help to discover the crate’s own CLI. Symposium resolves command through the same installation pipeline hooks use, runs it with the installation’s args followed by the arguments typed after <name>, passes its output through, and exits with its exit code. The command owns its own arguments, validation, and --help.

# A recommendations entry; in a crate's own Symposium.toml, leave out name and depends-on.
name = "widgetlib"
depends-on = ["widgetlib"]

[[installations]]
name = "widgetlib-cli"
source = "cargo"
crate = "widgetlib-cli"
executable = "widgetlib-cli"

# `cargo agents widgetlib check --strict` runs `widgetlib-cli check --strict`
[subcommand.widgetlib]
description = "Check and inspect the widget definitions in this workspace"
audience = "agents"
command = "widgetlib-cli"

<name> is the word typed after cargo agents. It may contain only ASCII letters, digits, -, and _, and it must not be the name of a built-in command: init, sync, search, use, status, hook, plugin, self-update, crate-info, telemetry, or help.

A subcommand is listed in cargo agents --help, and can be run, only while its plugin is active and its own depends-on and predicates hold. If two active plugins define the same name, running it fails with an error naming both plugins. A subcommand’s gate does not keep its plugin out of dormancy.

Example: full manifest

# A recommendations entry; in a crate's own Symposium.toml, leave out name and depends-on.
name = "widgetlib"
depends-on = ["widgetlib"]

# Skills shipped inside the widgetlib crate source (in skills/)
[[plugins]]
source.cargo = "widgetlib"

# Additional skills hosted in a git repo (the recommendations repository does not accept git sources)
[[skills]]
depends-on = ["widgetlib^1.0"]
source.git = "https://github.com/org/widgetlib/tree/main/symposium/skills"

[[hooks]]
name = "check-widget-usage"
event = "PreToolUse"
matcher = "^(Bash|bash|run_command|execute_bash)$"
command = { script = "scripts/check-widget.sh" }

[[mcp_servers]]
name = "widgetlib-mcp"
command = "/usr/local/bin/widgetlib-mcp"
args = ["--stdio"]
env = []

Validation

cargo agents plugin validate path/to/Symposium.toml

This parses the manifest and reports any errors. The file must be named Symposium.toml for Symposium to discover it; to validate every entry in a registry directory, pass the directory instead (see Plugin sources). Crate name checking against crates.io is on by default; use --no-check-crates to skip it.

Symposium hook events

This page documents the JSON schemas for symposium-format hooks — the input your hook receives on stdin and the output it should write to stdout. Symposium converts to and from each agent’s native wire format, so you only need to handle these canonical types.

Events

Agent support

Symposium registers one handler per event with each agent, under the agent’s own name for that event. A “not delivered” cell means Symposium registers no handler for that event on that agent. The table gives each agent’s native event name; the name in parentheses is the agent’s name in a hook’s format and in cargo agents hook <agent>.

Goose and OpenCode have no shell hooks, so no plugin hook ever runs there; they receive skills and MCP servers only. A hook for an event an agent does not deliver simply never fires on that agent. Agents also differ in what they do with a hook’s output; for example, Antigravity shows a PreToolUse hook’s output only when the hook blocks the call. Each agent’s page under Supported agents has the details.

Input schemas

Your hook receives one of the following JSON objects on stdin, depending on which event it is registered for.

PreToolUse

{
  "PreToolUse": {
    "tool_name": "Bash",
    "tool_input": { "command": "cargo test" },
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

PostToolUse

{
  "PostToolUse": {
    "tool_name": "Bash",
    "tool_input": { "command": "cargo test" },
    "tool_response": { "stdout": "test result: ok" },
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

UserPromptSubmit

{
  "UserPromptSubmit": {
    "prompt": "Fix the failing test in src/lib.rs",
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

SessionStart

{
  "SessionStart": {
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

Stop

{
  "Stop": {
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

Output schemas

Your hook writes a JSON object to stdout. The object is wrapped in an enum tag matching the event, just like the input.

PreToolUse output

{
  "PreToolUse": {
    "additionalContext": "Remember to use --release for benchmarks",
    "updatedInput": { "command": "cargo test --release" }
  }
}

To block the call:

{
  "PreToolUse": {
    "decision": "deny",
    "additionalContext": "Refusing to run a command that deletes the filesystem root"
  }
}

Each agent receives the decision in the form it honors:

Tool input is the agent’s own: write updatedInput in the shape that agent’s tool takes.

PostToolUse output

{
  "PostToolUse": {
    "additionalContext": "Note: 3 tests were skipped due to missing fixtures"
  }
}

UserPromptSubmit output

{
  "UserPromptSubmit": {
    "additionalContext": "Relevant context: this project uses tokio 1.x"
  }
}

SessionStart output

{
  "SessionStart": {
    "additionalContext": "symposium 0.5.0 is available (current: 0.4.2). Run `cargo agents self-update` to upgrade."
  }
}

Stop output

{
  "Stop": {
    "additionalContext": "Things look good!"
  }
}

Exit codes

Matcher

The matcher field on a hook entry is a regex matched against tool_name for PreToolUse and PostToolUse events. For UserPromptSubmit, SessionStart, and Stop, the matcher is ignored (all hooks fire). Use "*" to match all tools.

The regex is unanchored: it matches if it is found anywhere in the tool name, so Bash also matches BashOutput. Anchor it with ^...$ (^Bash$) to match one tool exactly.

tool_name is passed through exactly as the agent sends it, and tool_input keeps the agent’s own argument names. Agents name the same tool differently: the shell tool is Bash in Claude Code and Codex, bash in Copilot, execute_bash in Kiro, and run_command in Antigravity, whose input carries CommandLine rather than command. A symposium-format hook meant to fire on several agents must match each name, for example matcher = "^(Bash|bash|run_command|execute_bash)$", and read the input in each shape.

Testing

To unit-test a symposium-format handler, pipe canonical JSON straight into it, the way Symposium does (a script handler runs under sh):

echo '{"PreToolUse":{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":null,"cwd":"/tmp"}}' \
  | sh scripts/check.sh

To test end to end, pipe the agent’s own native JSON into cargo agents hook <agent> <event>, where <agent> is one of antigravity, claude, codex, copilot, or kiro and <event> is pre-tool-use, post-tool-use, user-prompt-submit, session-start, or stop. For Claude Code:

echo '{"session_id":"s","cwd":"/path/to/project","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | cargo agents hook claude pre-tool-use

This runs the full dispatch, including the automatic sync when auto-sync is on, for the workspace at cwd, so the plugin must be installed and active there. Symposium converts the payload to canonical JSON for your hook and prints the result in the agent’s format (for Claude Code, a hookSpecificOutput object). There is no symposium agent name: the canonical format is only what your handler sees.

Skill definitions

A skill is a SKILL.md file inside a skill directory. Skills follow the agentskills.io format, with one restriction: every frontmatter value must be a string, so the spec’s metadata map (or any other list or map) is rejected. See Frontmatter fields.

Skills can be supplied by a plugin or by adding skills into the .agents/skills directory within the workspace.

Directory layout

skills/
  my-skill/
    SKILL.md
    scripts/       # optional
    resources/     # optional

Symlinks in skill content

A skill directory may contain symlinks, and installing a skill follows them: a link to a file arrives as a real file, a link to a directory arrives as a real directory holding a copy of its contents. That is what lets a workspace keep one copy of a shared script and link it into the several skills that use it.

Links are followed wherever they point, including outside the skill directory and outside the crate or registry entry that ships it. Two alternatives were considered and rejected:

• Copying the link itself. The installed skill lives in the agent’s skill directory, a different tree, so a relative link pointing outside the skill directory dangles there — which is exactly the missing-file error this is meant to avoid.
• Following only links that stay inside the source. This breaks layouts that already exist, such as a skill linking a library out of a sibling crate in the same workspace, and it would make installing from a source tree stricter than installing the same crate from crates.io: cargo package follows links, including ones whose target escapes the package root, so the published crate carries that content as a real file either way.

The consequence is worth stating plainly: a skill you install can bring any file its links reach into the directory your agent reads. The boundary that governs that is enablement — a plugin embedded in a dependency does not run without your consent, and a registry is a trust root you added yourself. Symposium does not put a second, filesystem-shaped boundary on top of it.

Two links are skipped rather than followed, each with a warning, and neither fails the sync:

• a broken link, whose target does not exist;
• a link naming a directory the copy is already inside, which would otherwise nest forever.

SKILL.md format

A SKILL.md file has YAML frontmatter followed by a markdown body:

---
name: serde-basics
description: Basics of the serde crate. Use when adding Serialize or Deserialize support to Rust types.
depends-on: serde
---

Prefer deriving `Serialize` and `Deserialize` on data types.

Frontmatter fields

Other string fields from the agentskills.io spec, such as license, are accepted and kept. These rules apply to every field:

• Every value must be a YAML string. Lists, maps (including the agentskills.io metadata map), numbers, booleans, and empty values are rejected, so quote anything YAML would read otherwise (version: "1.0").
• Quote a value that contains : or #. Unquoted, YAML rejects the first and treats everything after # as a comment, silently shortening the value.
• The crates field is rejected; use depends-on.
• In workspace skills the frontmatter is optional: name defaults to the name of the skill’s directory, and description may be omitted. Skills from a registry or a crate need both.

Security: a skill’s name comes from plugin content and becomes a directory on disk, so Symposium treats it as untrusted input. A name that would resolve outside the agent’s skills directory is rejected: the skill fails to load instead of being installed, and cargo agents plugin validate reports it.

Crate atoms

Crate atoms specify a crate name with an optional version constraint:

• serde — any version
• tokio>=1.40 — 1.40 or newer
• tokio>1.40 — strictly above 1.40
• regex<2.0 — below 2.0
• regex<=2.0 — 2.0 or below
• serde^1.0 — compatible with 1.0 (same as =1.0)
• serde~1.2 — patch-level changes only (>=1.2.0, <1.3.0)
• serde=1.0 — compatible-with-1.0 (equivalent to ^1.0)
• serde==1.0.219 — exact version

Write the atom without spaces: serde >=1.0, serde>= 1.0, and serde>=1.0, <2.0 are all rejected. In frontmatter, depends-on is split on commas, so a range with a comma (serde>=1.0,<2.0) cannot be written there; use predicates: depends-on(serde>=1.0,<2.0) instead, since commas inside parentheses do not separate predicates.

See Dependency predicates for the full syntax.

Scope composition

depends-on can be declared at the [[skills]] group level (in the plugin TOML) and at the individual skill level (in SKILL.md frontmatter). They compose as AND: both layers must match for a skill to activate. A skill-level depends-on narrows the group’s scope — it does not widen it.

Dependency predicates (depends-on)

Dependency predicates control when plugins and their components are active. A predicate matches against a workspace’s direct dependency set, not against individual packages in isolation. Today the dependency set is the workspace’s cargo dependency graph; a depends-on atom matches a direct dependency by name.

The depends-on field is accepted on the plugin itself, on [[skills]] groups, [[mcp_servers]] entries, [[plugins]] edges, and [subcommand.<name>] tables (see Plugin definitions), and in SKILL.md frontmatter. [[hooks]] and [[predicate]] entries have no depends-on field; gate a hook on a dependency with predicates = ["depends-on(serde)"].

The depends-on field is shorthand: depends-on = ["serde", "tokio"] lowers to a single any(depends-on(serde), depends-on(tokio)) predicate and is merged into the same list as the predicates field (ANDed together). Everything below describes the dependency-atom syntax depends-on accepts; the equivalent depends-on(<atom>) predicate is also usable directly in predicates.

Predicate syntax

A dependency atom is a package name with an optional version requirement.

Examples:

• serde
• serde>=1.0
• tokio^1.40
• regex<2.0
• serde=1.0
• serde==1.0.219
• *

Semantics:

• bare name: matches if the workspace has this package as a direct dependency (any version)
• >=, <=, >, <, ^, ~: standard semver operators applied to the workspace’s version of the package
• =1.0: compatible-version matching, equivalent to ^1.0
• ==1.0.219: exact-version matching
• *: wildcard — always matches, even a workspace with zero dependencies

= is not Cargo’s =. In a dependency atom, =1.0 means ^1.0 (1.0 or any later 1.x release), which is what a bare 1.0 means in Cargo. To pin an exact version, use ==: serde==1.0.219 matches only 1.0.219.

Further rules:

• Write the atom without spaces. serde >=1.0 is rejected; write serde>=1.0.
• Names match exactly, as the crate is published: a serde-json atom does not match the serde_json crate.
• In TOML, an atom may carry a comma-separated range, every part of which must hold: "serde>=1.0,<2.0". SKILL.md frontmatter splits depends-on on commas, so a range cannot be written there; use predicates: depends-on(serde>=1.0,<2.0) instead.

Predicates match against direct workspace dependencies only, not transitive ones.

Usage in different contexts

Plugin manifests (TOML)

The depends-on field accepts a single atom string or an array of them:

• depends-on = ["serde"]
• depends-on = ["serde", "tokio>=1.40"]
• depends-on = ["*"] (wildcard — always active)

Skill frontmatter (YAML)

The depends-on field uses comma-separated values:

• depends-on: serde
• depends-on: serde, tokio>=1.40

Matching behavior

A depends-on list matches if at least one atom in the list matches the workspace. The wildcard * always matches — even a workspace with zero dependencies.

If there are multiple depends-on declarations in scope, all of them must match (AND composition). For example with skills, depends-on predicates can appear at three distinct levels:

• If a plugin defines depends-on at the top-level, it must match before any other plugin contents will be considered.
• If a skill-group within a plugin defines depends-on, that predicate must match before the skills themselves will be fetched.
• If the skills define depends-on in their front-matter, those dependencies must match before the skills will be added to the project.

depends-on is purely a gate — it decides whether an item activates, not which crate to fetch. To load a crate’s own skills, name that crate explicitly in a [[plugins]] chained reference (source.cargo = "..."), gating the edge with depends-on as usual.

The crates field (in manifests and in SKILL.md frontmatter) and the crate(...) predicate are rejected; use depends-on.

Predicates

A predicate decides whether a plugin, skill group, skill, hook, MCP server, [[plugins]] edge, or subcommand is active, evaluated against the workspace’s dependency graph and the live environment. There is one predicate model, written two ways:

• The depends-on field uses dependency-atom syntax (see dependency predicates) and is sugar: depends-on = ["serde", "tokio"] lowers to a single any(depends-on(serde), depends-on(tokio)) predicate.
• The predicates field uses the function-call syntax below.

Where each field is accepted:

• predicates: the plugin itself, [[skills]] groups, [[hooks]] entries, [[mcp_servers]] entries, [[plugins]] edges, [subcommand.<name>] tables, and SKILL.md frontmatter.
• depends-on: all of the above except [[hooks]], which has no depends-on field. Gate a hook on a dependency with predicates = ["depends-on(serde)"].
• Neither: [[predicate]] entries, which define a predicate rather than being gated by one.

Where both fields are set, they are merged into one list that is ANDed together, so depends-on and predicates compose with AND. A depends-on(...) predicate is available in predicates too; the field just makes the common case terse.

The available predicate functions are:

Predicates compose with AND semantics within a list: every entry must hold. any(...) gives OR within a single entry, all(...) gives an explicit AND group, and not(...) gives negation — together they form full boolean logic. They also compose with AND across levels (plugin ∧ group ∧ skill).

The argument of a leaf predicate (depends-on, shell, path_exists, env) is taken verbatim between the parentheses — it is not quoted. shell(command -v rg) runs command -v rg; do not wrap the argument in quotes (they would become part of the command). An inner ) is fine as long as parentheses balance, so shell(echo $(date)) works. The combinators not, any, and all take nested predicates as their arguments and may be nested arbitrarily, e.g. not(any(env(CI), path_exists(.skip))).

A plugin can also define its own predicate functions with [[predicate]] and use them in any predicates list.

crate(...) is rejected; use depends-on(...).

Loading a crate’s skills

A predicate is purely a boolean gate — it decides whether an item activates, not which crate to fetch. To load a crate’s own skills, name that crate in a [[plugins]] chained reference (source.cargo = "...") and gate the edge as you like:

[[plugins]]
depends-on = ["serde"]      # only when serde is a dependency
source.cargo = "serde"      # load serde's plugin (its skills)

When predicates are evaluated

Predicates are evaluated at the same point the workspace’s dependency predicates are evaluated for that item:

Hook-level predicates run at dispatch (not sync) so they observe live state — e.g. a hook gated on path_exists(jq) will silently disable itself if jq was uninstalled since the last sync, without forcing a re-sync.

Tip: keep predicates fast and side-effect free (path_exists(rg), path_exists(.git), shell(test -f Cargo.toml)). Plugin-level, [[plugins]] edge, and hook-level predicates fire on every hook dispatch.

Usage

Plugin manifests (TOML)

name = "my-plugin"
depends-on = ["*"]
predicates = ["path_exists(rg)", "shell(test -f Cargo.toml)"]

[[skills]]
depends-on = ["serde"]
predicates = ["path_exists(jq)"]
source.path = "skills"

[[hooks]]
name = "h"
event = "PreToolUse"
command = { script = "scripts/x.sh" }
predicates = ["path_exists(.git)"]

[[mcp_servers]]
name = "tool"
command = "/usr/local/bin/tool"
args = []
env = []
predicates = ["path_exists(tool)"]

Skill frontmatter (YAML)

Like depends-on, predicates is comma-separated on a single line in SKILL.md frontmatter. Commas inside (...) are not treated as separators, so a shell(...) command may itself contain commas:

---
name: my-skill
description: Skill that depends on ripgrep
depends-on: serde
predicates: path_exists(rg), shell(test -f Cargo.toml)
---

Example: gating a plugin on tool availability

name = "uses-jq"
depends-on = ["*"]
predicates = ["path_exists(jq)"]

[[hooks]]
name = "format-json"
event = "PreToolUse"
command = { script = "scripts/format.sh" }

This plugin’s hooks dispatch only while jq is on the user’s $PATH. Symposium never registers plugin hooks into agent configs; it checks the plugin’s predicates each time an event arrives. No error, no warning: symposium just skips this plugin’s contributions while jq is missing.

Combining predicates

depends-on, env, not, any, and all cover the cases plain depends-on lists can’t. Each of these is a predicates value for any item that accepts one:

• Opt-in, only when a flag is set: predicates = ["env(SYMPOSIUM_EXPERIMENTAL)"]
• Opt-out or escape hatch, skipped when a marker file is present or in CI: predicates = ["not(path_exists(.skip-hooks))", "not(env(CI))"]
• A tool packaged under different names across distros: predicates = ["any(path_exists(fd), path_exists(fdfind))"]
• A dependency gate that also requires an env flag (vs. the bare depends-on = ["serde"]): predicates = ["all(depends-on(serde), env(USE_SERDE))"]
• Only when a dependency is absent (impossible with depends-on): predicates = ["not(depends-on(legacy-thing))"]

These are equivalent — depends-on is just the terse form for the common case:

depends-on = ["serde", "tokio"]
# is exactly
predicates = ["any(depends-on(serde), depends-on(tokio))"]

Contributing to Symposium

Welcome! This section is for people who want to work on Symposium itself. If you’re a crate author who wants to publish skills or hooks for your library, see Supporting your crate instead.

Building and testing

Symposium is a standard Cargo project with both a library and a binary:

cargo check              # type-check
cargo test               # run the test suite
cargo run -- crate-info tokio # run locally: crate-specific guidance

Tests use snapshot assertions via the expect-test crate. If a snapshot changes, run with UPDATE_EXPECT=1 to update it:

UPDATE_EXPECT=1 cargo test

Logging and debugging

Symposium uses tracing for structured logging. Each invocation writes a timestamped log file to ~/.symposium/logs/.

The default log level is info. To get more detail, set the level in ~/.symposium/config.toml:

[logging]
level = "debug"   # or "trace" for maximum detail

Log files are named symposium-YYYYMMDD-HHMMSS.log. When debugging an issue, the log file from the relevant invocation is usually the best place to start.

What to read next

• Key repositories — the repos that make up Symposium
• Key modules — the main pieces of the codebase
• Important flows — key paths through the code
• Testing guidelines — how to write and run tests
• Governance — how we work together

Tenets

Design principles that guide symposium’s architecture. When in doubt, these break ties.

Unobtrusive

Symposium should never be a reason to opt out. Using it should be non-disruptive to existing workflows:

• Existing projects should be able to adopt symposium without restructuring.
• Never dirty the user’s repo with unexpected files or diffs or require users to manually edit .gitignore.
• Avoid adding “symposium-specific” files or modifications in project repositories (when possible).

Prefer existing standards over our own

When there’s an existing mechanism that works, use it rather than inventing a new one. Adopt agent conventions, standard file layouts, and community norms wherever possible. Symposium’s own canonical format exists only where no cross-agent standard exists.

Union, not least-common-denominator

Symposium’s plugins should be able to take full advantage of what agents can do. We aim for interoperability but we also let plugin authors opt into agent-specific formats or capabilities.

Vendor neutral, interoperable

Plugins and repository provide functionality; users pick their agent. Symposium provides the bridge, exposing plugin functionality in whatever way is requested by an individual user.

Safety

Avoid exposing users to fresh risk. Plugins run code on the user’s machine, so symposium should make it easy to audit, constrain, and revoke. Plugins embedded in dependencies stay off until the user enables them, and plugins in the central repository are reviewed before they load without asking; both exist to prevent supply-chain attacks until we have better decentralized trust mechanisms.

Empower the ecosystem

Crate authors should be able to ship agent extensions independently, without waiting for central approval or coordination beyond the initial plugin registration. Once registered, updates flow through normal crate publishing. The symposium project’s role is infrastructure, not gatekeeping.

Key repositories

All repositories live under the symposium-dev GitHub organization.

symposium

The main repository. Contains the Symposium CLI/library (Rust), the mdbook documentation, and integration tests.

symposium-claude-code-plugin

The Claude Code plugin that connects Symposium to Claude Code. Contains a static skill, hook registrations (PreToolUse, PostToolUse, UserPromptSubmit), and a bootstrap script that finds or downloads the Symposium binary.

recommendations

The central plugin repository, curated by the Symposium project. Symposium fetches this as a registry by default.

Key modules

Symposium is a Rust crate with both a library (src/lib.rs) and a binary (src/bin/cargo-agents.rs). The library re-exports all modules so that integration tests can access internals.

symposium-sdk: the shared plugin vocabulary

Depended on by both Symposium and anything that extends it. Beyond the hook handler SDK, it carries what a package manager needs to speak:

• manifest: the unvalidated Symposium.toml schema (the Raw* types), Serialize as well as Deserialize so a manifest can travel on the wire. Retired fields (crates, source.crate, git/path chained sources) still parse, so validation can reject them with a migration hint rather than an unknown-field error.
• pm: PackageId, PluginInfo, and UnvalidatedPlugin (what a package manager answers with: Symposium validates it into a Plugin), re-exported from Symposium’s pm module.
• predicate::syntax: the predicate tree and its parsing.
• hook::HookAgent, manifest::HookFormat, manifest::Audience: named by manifests, so they travel with the schema. Mapping a HookAgent to its wire-format handler needs Symposium’s agent modules, so that stays behind as hook_schema::agent_event.

What deliberately stays in Symposium is validation: defaults, inline-installation promotion, dormancy, trust. The schema says what a manifest can contain; Symposium decides what it means.

config.rs — application context

Everything hangs off the Symposium struct, which wraps the parsed Config with resolved paths for config, cache, and log directories. Two constructors: from_environment() for production and from_dir() for tests. Agent relocation variables (CLAUDE_CONFIG_DIR, …) are read through env_dir, which consults the process environment only for a from_environment() instance, so a test can never reach a developer’s real agent directories; tests inject one with set_env.

Defines the user-wide Config (stored at ~/.symposium/config.toml) with [[agent]] entries, logging, [[registry]] entries ([[plugin-source]] is the retired spelling, still accepted), defaults, auto-update (off/warn/on, default on), and the [plugins] enablement section. User config is deserialized through RawConfig and validated into the runtime Config; runtime code does not deserialize Config directly. Provides registry_instances() to build the effective registry PmInstances directly (the builtin recommendations entry, the builtin user-plugins entry, then the configured ones): a git [[registry]] entry becomes a GitPm, a path entry a PathPm, each a trust root named for its registry (that name is what its plugins are attributed to). There is no ResolvedRegistry/content_dir intermediate — a git registry’s cache directory and its refresh live on the GitPm itself. package_managers(deps) prepends the fixed cargo transport (a CargoPm built over the shared deps resolver) to those to make the active PmRegistry. detached_managers() is the workspace-independent form (registry listing, crates.io search) — its cargo transport is built over a detached resolver that never runs cargo metadata. The workspace_deps(cwd) factory is the standard way to create a WorkspaceDeps — it wires in cargo_override and cache_dir so callers get both the SYMPOSIUM_CARGO override and cross-invocation disk caching, and returns it as an Arc so a CargoPm can hold one.

PluginsConfig (the [plugins] section) is the config surface of the enablement axis: auto-enable (dependency names pre-consented to, "*" for all), use (UseEntry::Global(name) or { name, workspace } — the durable record of a deliberate enablement, scoped to one workspace or to all), and disable (names pruned from enablement, which is also where a declined discovery is recorded). Its query methods — used_names_in(root), is_auto_enabled, is_disabled, is_used_in — all match names hyphen/underscore-insensitively, since these are user-typed package names; has_enablement_entries is the cheap “could enablement pull in a crate plugin?” check the hook path uses to decide whether to resolve the crate graph. The lists are plain Vecs so a later cargo agents use can add and remove entries and call save_config.

pm/cargo/workspace.rs — cargo workspace resolution

The cargo-workspace resolution is CargoPm’s, so it lives in the cargo PM’s module (not a top-level crate::workspace) — cargo metadata is cargo’s ecosystem, not a generic concern. WorkspaceDeps is the lazy, cached resolver for the cargo dependency graph: the first load() reads a disk cache keyed on Cargo.lock mtime, and on miss runs cargo metadata (extracting root, direct crates, and member dirs into a LoadedWorkspace) and writes through. The result is memoized in a OnceLock, so every accessor reads through a shared &self — which is what lets one resolver be shared as an Arc: a CargoPm holds one and drives it (self.workspace.crates() runs the metadata call), and core code that needs the workspace root/members reads the same instance, rather than each caller resolving its own. WorkspaceCrate carries path (the local dir for a path dependency) and source_dir (the extracted source cargo metadata located, populated for registry crates too), so a workspace dependency’s source is served without a fresh probe. detached() is a resolver pre-set to “no workspace” for workspace-independent operations (registry listing, search). The types re-export at crate::pm for the core consumers of the workspace root/members (registry loading, sync, hook). The config-level dirs.rs (SymposiumDirs: config/cache paths + the SYMPOSIUM_CARGO override) stays in core; Symposium::workspace_deps(cwd) is the factory that wires them together.

agents.rs — agent abstraction

Centralizes agent-specific knowledge: hook registration file paths, skill installation directories, and hook registration logic for each supported agent (Antigravity CLI, Claude Code, GitHub Copilot, Codex CLI, Kiro, OpenCode, Goose). Handles the differences between agents — e.g., Claude Code uses .claude/skills/ and Kiro uses .kiro/skills/, while Antigravity, Copilot, Codex, OpenCode, and Goose use the vendor-neutral .agents/skills/. OpenCode and Goose are skills-only agents (no hook registration).

Hook and MCP registration is scope-dispatched: the project and global locations are genuinely different files for some agents (Antigravity writes .agents/hooks.json but ~/.gemini/config/hooks.json; Copilot .github/hooks/ but ~/.copilot/settings.json), so sync calls the project-scoped functions at project scope rather than rooting the global path at the workspace.

MCP registration is its own axis, and the one place where guessing is expensive: an agent’s MCP file is usually not its hooks file, so a wrong target fails silently - symposium reports success for a file the agent never reads. Agent::mcp_config_path(scope, project_root, sym) is the single seam holding that per-agent truth (the table lives in agent details), with register_mcp_servers / unregister_mcp_servers as the only entry points; there is no separate project/global pair of functions to keep in sync. McpScope is deliberately distinct from HookScope: Antigravity, Claude, OpenCode and Kiro have a project-level MCP file, while Codex, the Copilot CLI and Goose read only a user-level one, so supports_project_mcp_scope reports when project scope is downgraded rather than writing a file nobody reads. Entry shape varies too - OpenCode needs {type, command: [bin, ...args], enabled} and rejects its whole config file otherwise, which is why it has its own serializer (opencode_server_to_json) instead of the shared {command, args} one.

init.rs — initialization command

Implements cargo agents init. Prompts for agents (or accepts --add-agent/--remove-agent flags), hook scope, auto-update behavior, and opt-in telemetry; writes user config; and registers global hooks.

sync.rs — synchronization command

Implements cargo agents sync. Scans workspace dependencies, finds applicable skills from plugin sources, and synchronizes them into each configured agent’s skill directory. The core primitive is sync_skill_dir(source_dir, dest_dir, project_root). It copies the entire source directory (not just SKILL.md) and is change-aware: it compares source and destination content, only performing the delete-and-recopy when files actually differ, so the disk shows no modifications when nothing changed. Copying and comparing share one traversal, walk_tree — they have to agree entry for entry, since a comparison scan that omitted something the copier writes would see a difference on every run and turn each sync into a full recopy. That traversal follows symlinks (see dir_walk.rs), so a linked file installs as a real file and a linked directory as its contents; a broken link and a link back into the tree being copied are reported and skipped rather than failing the sync. A configurable debounce (sync-debounce-secs, default 5s, keyed on the .symposium marker’s mtime) skips even the comparison for recently-synced skills. On each sync, scans every agent’s skills parent directory and reaps any marker-bearing subdirectory it didn’t install this time, leaving user-managed skills (which lack the marker) untouched. Writes a .gitignore with * only into individual skill directories (not parent directories like .claude/ or .claude/skills/). Also provides register_hooks() for use by init, which registers only symposium’s own global hook handler — individual plugin hooks are never written into agent configs.

While PluginRegistry::unreadable_registries is not empty, sync skips that reap and warns once per registry: an unreadable registry offered nothing, so everything it installed would look stale.

One entry point, sync(sym, deps, update). The caller supplies the WorkspaceDeps, so the hook pipeline hands over the resolver its other stages already used rather than resolving the workspace a second time. Callers: the CLI’s sync arm (after the consent prompt), use_command once an enablement is recorded, and the hook pipeline’s auto-sync.

sync takes an UpdateLevel that it threads into skill resolution (skills::collect_skills), controlling how aggressively source.git skill groups are re-fetched. Callers choose: the auto-sync path passes Check on SessionStart (refresh) and None otherwise (debounced); the binary’s global --update flag feeds manual cargo agents sync.

plugins.rs — plugin registry

Loads plugin manifests from the configured registries and validates them into Plugins. Loading goes through the package-manager layer: load_registry asks each trusted PmRegistry instance (the configured registries — the cargo transport is not a trust root) for its plugins via active_plugins. A PathPm returns each entry through entry_plugin: a Symposium.toml manifest read as-is, or a bare SKILL.md synthesized into a manifest (standalone_skill_manifest); dependency-embedded crate plugins never load here. Refreshing a git registry’s content is the GitPm’s refresh operation, driven by ensure_registries (startup) and sync_registries (plugin sync). scan_source_dir remains as the offline form used by the plugin validate CLI, which points at an arbitrary directory rather than a configured registry; it walks the same layout rules and synthesizes bare skills the same way.

load_registry reads each registry through PmInstance::registry_plugins, which fails where active_plugins would come back empty because the source cannot be read (a PathPm whose directory cannot be listed or is itself an entry, and a GitPm that has not been fetched). Such a registry is reported and recorded in PluginRegistry::unreadable_registries (see common issues); plugin list and plugin show read through the same call.

Validation here turns the raw TOML (parsed into the SDK’s RawPluginManifest) into:

• Installation entries (optional source, optional executable/script, optional args, plus requirements and install_commands) collected on PluginManifest.installations. Inline installation references on hooks or other installations are promoted into synthetic Installation entries with derived names (<hook> for an inline command, <owner>__req_<i> for an inline requirement), so all references in the validated form are plain names.
• Hook entries with command: String (the name of an Installation) plus optional hook-level executable / script / args. Validation guarantees at most one of executable/script is set across hook + installation, and at most one layer sets args.
• SkillGroup and PluginMcpServer entries whose depends-on sugar and predicates list are merged into one runtime PredicateSet. Skill group source syntax is deserialized as raw string/table forms, then validated into PluginSource.
• ChainedPlugin entries from [[plugins]]: a per-edge PredicateSet plus a source.cargo reference (dependency-atom string "widget>=1" or { name, version } table) naming the crate that carries the referenced plugin. This is the “package ≡ plugin” edge — how one plugin (e.g. a recommendations manifest) names another plugin by its package. Validation rejects git/path sources and the retired dependency-table form with hints. Expansion is wired in skills.rs: when the owning plugin is active and the edge predicates hold, the referenced crate is loaded (see important flows) — as a first-class plugin from its own Symposium.toml if it ships one, otherwise from the crate’s metadata / default-skills/ path. The recorded version requirement is not yet enforced at resolution — the crate resolves against the workspace.

merge_crate_manifest(metadata, file, crate_name) builds a crate’s unvalidated manifest. It parses each source — the [package.metadata.symposium] table and a Symposium.toml file, both in the ordinary plugin-manifest schema — independently and leniently (a malformed layer is logged and dropped), merges them (RawPluginManifest::merge: list fields append, scalar/keyed fields take the later layer, gates AND together). When the plugin reaches validate_plugin, the result runs through the same validate_manifest pipeline under ManifestOrigin::Crate: the name defaults to the crate, the dormancy rule does not apply (the reference that reached the crate is the gate), [defaults] is accepted, and the default skills/ group is appended (but not the workspace-only .agents/skills group). A crate with neither source still yields that default group. Plugin carries a required canonical: PackageId — the resolved crate id for a crate-sourced plugin, or a placeholder id tagged with the source name (registry) / "local" (workspace) for plugins with no real package identity. It keys chained-plugin cycle/diamond detection on the normalized crate name (skills.rs); it does not affect skill identity, which is the SKILL.md path hash (see skills.rs). Every loader (load_plugin_as, workspace_plugin_for_dir, and validate_plugin) runs resolve_group_sources before returning, so each [[skills]] source.path group carries an absolute directory plus a display source_label — a Plugin needs no base/manifest dir. A Plugin carries no manifest file path or base path at all — its identity is its canonical id. plugin show renders a plugin’s effective config keyed by that id (not a re-read manifest file); plugin validate reports each item by its id/name (a failed load’s error message still carries the file it came from).

There is no separate “standalone skill” concept: a registry directory holding only a SKILL.md (no Symposium.toml) is synthesized by standalone_skill_manifest into a manifest with default values, which ordinary registry validation turns into a plugin — named for the skill’s own frontmatter name (falling back to the directory), carrying a single source.path = "." skill group that rediscovers that SKILL.md, and with the skill’s frontmatter depends-on/predicates hoisted to the plugin gate so the ordinary dormancy rule applies (a bare skill that names no dependency is dormant until used). This mirrors how a crate with no manifest still yields a plugin with the default skills/ group. So PluginRegistry holds only plugins; the plugin validate CLI likewise reports a bare skill as its synthesized plugin, whose one child is the skill. Returns a PluginRegistry — a table of contents that doesn’t load skill content.

A registry manifest that references no dependency anywhere — plugin, [[skills]], [[hooks]], [[mcp_servers]], or [[plugins]] chain edge, via depends-on, a depends-on(...) predicate, or a custom predicate — is not an error: it validates and loads with PluginManifest::requires_use = true, i.e. dormant. PluginManifest::applies short-circuits to false for a dormant plugin unless PredicateContext::is_used says a [plugins] use entry names it, so every activation path (skills, hooks, MCP, subcommands, help) agrees. depends-on = ["*"] remains the explicit always-active spelling, and plugin validate reports dormancy as a warning. So a recommendations-registry entry — an ordinary flat plugin — stays out of dormancy by declaring its own depends-on (the crates it advises, or ["*"]). The positional origins never go dormant, because where they were found supplies the gate.

Workspace-scoped callers use load_registry_with_workspace, which additionally loads workspace plugins (workspace_plugins): the workspace root and every member directory each define a plugin when they carry a Symposium.toml (validated with ManifestOrigin::WorkspaceMember — name defaults to the directory name, membership is the gate so dormancy never applies, and the default groups are appended unless [defaults] skills = false: [[skills]] source.path = "skills" plus, when the agents-syncing config is on, a workspace-member()-gated [[skills]] source.path = ".agents/skills" — the maintainer-skills convention, unified into the ordinary pipeline) or a bare skills/ or .agents/skills/ directory (an all-defaults manifest-less plugin). Workspace plugins are stamped workspace_member = true — the producer of the workspace-member() predicate — and attributed to the "(workspace)" source with skill paths relative to the workspace root.

dir_walk.rs — following symlinks without looping

The two rules every source-tree walk needs once symlinks are followed, in one place.

A live source tree — a workspace member, a path or git dependency, a [[registry]] path entry, ~/.symposium/plugins/, a git-cloned registry cache — can contain symlinks, and what sits behind them is skill content like any other. Such a tree is dereferenced rather than copied link-for-link: the destination is a different tree, so a preserved relative link pointing outside the skill directory would dangle there. Dereferencing also makes a source-tree install agree with a crates.io install, which already delivers real files (cargo package follows links, including ones escaping the package root). Links are followed wherever they point — there is no containment check against the source root; the skill reference records that decision and its rationale.

• resolved_kind(path, file_type) classifies a directory entry with links resolved. DirEntry::file_type reports the link, which is neither a directory nor a regular file, and DirEntry::metadata does not follow it either; fs::metadata does. Err can only come from that follow, so it means a broken link.
• Ancestors records the directories a walk is currently inside, by canonical path, and refuses to enter one twice. A tree of real directories cannot contain itself, so this only fires once a directory link has been followed — but every directory on the way down is recorded, since the link that closes the loop may sit several real directories below the one it names.

Four walks use it: the copy/compare traversal in sync.rs (both rules), and the cycle guard alone in skill discovery (skills::find_skill_files_recursive), registry enumeration (pm::layout::walk), and crate content detection (pm::cargo::contains_skill_md) — those three already followed directory links through Path::is_dir.

installation.rs — sources and acquisition

Defines Source (the source = "..."-tagged enum: cargo, github) and acquire_source, which downloads / installs / clones the source and returns an AcquiredSource whose resolve_executable / resolve_script methods turn a relative executable/script name into a concrete path. The Runnable enum (Exec(PathBuf) or Script(PathBuf)) is the final form a hook command resolves to. The git submodule handles GitHub tarball acquisition and caching.

acquire_source (and the main-crate acquire_installation wrapper) take an UpdateLevel. None serves the cache without touching the network; Check/Fetch re-resolve. Hook dispatch acquires with None; the SessionStart prewarm uses Check. The three source kinds:

• crates.io cargo: the resolved version is recorded in a current pointer (<cache>/binaries/<crate>/current). None reads the pointer and serves that version with no crates.io query — so a per-event dispatch never hits the registry. Check/Fetch query for the newest matching version, install into its version-keyed dir, and rewrite the pointer (so newly published versions are picked up at session start, not on every event). Only Fetch forces a same-version reinstall.
• cargo + git: the cache key folds in only the URL + user version, never the resolved commit, so a moved branch never invalidates it on its own. Check/Fetch resolve the remote HEAD with a cheap git ls-remote and compare against the commit recorded in a .commit-sha file in the cache dir; the binary is reinstalled (cargo install --force) only when the SHA changed (or Fetch, or the binary is missing). None never resolves the remote.
• github (script/subtree sources): honors the level directly via the git cache manager (freshness checks debounced to a 60s window under None).

Validates skill group source constraints during manifest validation: a group must set exactly one of source.path or source.git — a missing source (or an empty source = {}) is rejected, as are both together. A crate is not a skill-group source — source = "crate" (and the legacy source.crate table) is rejected with a hint to use a [[plugins]] source.cargo chained reference instead.

pm/ — package managers

The in-process seam from the registry-centric plugin distribution RFD. A PackageId is the canonical (pm, name, version) tuple; version may still be a requirement (a semver range, or * for “no requirement”), and fetch canonicalizes it — a FetchedPackage carries the exact resolved id plus the content directory. A PluginInfo (id plus optional description) is the lightweight result of search.

The PackageManager trait is the RFD’s operation set. Plugin loading has two forms — active_plugins(deps) (the plugins a PM activates for the workspace deps) and load_plugin(id) (the plugin(s) a specific id maps to) — both returning UnvalidatedPlugins and best-effort (failures logged, not surfaced); plus list_deps, search, fetch, refresh (pull a registry’s content — a no-op default for local/dependency sources), and registry_source (the git-vs-path descriptor, for plugin list). A PM value is an instance, not just an ecosystem: a transport can fetch/load_plugin any id of its ecosystem because the id carries the source, while a registry instance fronts one configured source and enumerates its packages via active_plugins. A registry instance’s name() is the configured registry name (user-plugins, symposium-recommendations, …), which is also the pm component of every id it mints and the name its plugins are attributed to. A PM is self-contained: it holds whatever it needs to resolve its own ecosystem, so operations take no ambient context — mirroring the out-of-process shape, where a PM spawned for a workspace answers from its own state. CargoPm holds an Arc<WorkspaceDeps> and drives it (lazy, cached); PathPm holds its directory. PmRegistry is one flat set of instances — fetch / load_plugin dispatch by PackageId::pm; list_deps / search / load_plugin union across all. An UnvalidatedPlugin is the resolved id, the content root, and an unvalidated RawPluginManifest (plus an optional label_root, the directory resolved skill paths are displayed relative to, so a registry entry reads as path:<entry>/skills). The manifest is the point: a PM may have parsed it from a Symposium.toml, translated another ecosystem’s manifest, or synthesized one for a package that describes itself not at all, and Symposium cannot tell.

Turning an UnvalidatedPlugin into a Plugin is PmInstance’s job, via plugins::validate_plugin: schema validation, inline-installation promotion, default content, dormancy, and resolving source.path groups against the plugin’s root all happen there. Each PmInstance carries two flags, both Symposium’s to set and neither anything a PM says about itself:

• trusted: whether consent is needed. Registries and the workspace are trust roots; the cargo transport (over dependencies) is not. This is the distinction consumers branch on (registry loading takes only trusted instances; discover takes only the untrusted cargo transport).
• kind: PluginKind: which validation policy applies. Registry (must name itself, [defaults] rejected, dormant with no gate) or Package (id supplies the name, the reference that reached it supplies the gate, default skills/ group appended).

So a package manager cannot make itself trusted or wake a dormant plugin by what it returns. A package’s manifest can still turn off the default skills/ group with [defaults] skills = false, since that is part of the package schema. A registry plugin that fails validation is reported, naming its directory, since fixing it is the user’s job; a package’s failure is only logged, since it is its author’s, and a report on the hook path would land next to the agent’s JSON. Symposium::package_managers(deps) builds the set — the cargo instance (trusted = false) plus one registry instance per configured registry (trusted = true: a GitPm for a git entry, a PathPm for a path entry); detached_managers() uses a detached resolver for workspace-independent work. workspace_dep_ids(sym, deps) unions list_deps and degrades to empty on failure. CargoPm (pm/cargo/mod.rs): fetch delegates to crate_sources::RustCrateFetch (path override, workspace pin, registry); list_deps reads self.workspace.crates() as cargo ids; active_plugins(deps) returns (via the shared plugin_from_fetched) each dependency whose source embeds plugin content (a Symposium.toml, [package.metadata.symposium], or the default skills/), fetched cache-only into the already-extracted source (no probe) — these are dependency-embedded, so the caller applies consent; load_plugin(id) returns the named crate whatever it embeds (any fetchable crate yields at least a default skills/ plugin); search queries crates.io (crates_io_api, capped at SEARCH_PAGE_SIZE) so use/search can name a crate the workspace doesn’t depend on. CargoPm also owns crate-to-plugin resolution:

• plugin_from_fetched(fetched) -> UnvalidatedPlugin builds the unvalidated plugin for a fetched crate from its manifest sources ([package.metadata.symposium] in Cargo.toml and a Symposium.toml at the source root) layered by plugins::merge_crate_manifest (see important flows). The offer’s id is the resolved crate. A crate with no manifest sources still yields one carrying an empty manifest, which validation turns into a plugin whose only content is the default skills/ group, so load_plugin returns a plugin for any fetchable crate (a failed fetch is logged and yields nothing). The default group is appended by validation, not by the PM: defaults are policy.

Callers stay ignorant of crates: skills.rs hands over a dependency name and gets back a parsed plugin. Consumers: chained-reference expansion in skills.rs calls load_plugin; crate_command.rs builds ids with CargoPm::id_for and fetches through PmRegistry; every dependency-list site (hook dispatch, sync, help rendering, subcommand dispatch, skill matching) gets its PredicateContext deps from workspace_dep_ids. Sync helpers that used to take &[WorkspaceCrate] and resolve deps themselves (help_render::render, subcommand_dispatch::find_subcommand) now take an already-resolved &[PackageId], so only the async entry points touch the PM layer.

One registry-instance PM exists today, reading content that is already on disk:

• pm/layout.rs — the packaging convention it reads: classify(dir) (a directory with a Symposium.toml is a plugin entry, one with a SKILL.md is a bare-skill entry — loaded as a default plugin — manifest wins) and enumerate(root) (recursive walk that does not descend into a claimed directory, sorted, erroring when the root is itself an entry). The layout carries no dependency information — an entry declares which dependencies activate it through its own manifest depends-on. Interpreting an entry’s manifest stays in plugins.rs.
• pm/path.rs — PathPm — one local directory in the flat layout: ~/.symposium/plugins/, a [[registry]] path entry, or the git cache directory a git registry unpacks into (serving as a GitPm’s inner reader). Its ids name the entry’s subpath within the source. active_plugins returns every entry (via plugins::entry_plugin), load_plugin(id) the entry an id names, fetch joins the subpath back onto the directory, search substring-matches entry names, and registry_source reports it as a Path. A registry is a trust root, so its plugins activate without consent; entry-load failures surface as report warnings.
• pm/git.rs — GitPm — one [[registry]] git entry. Once fetched, a git repo is just a directory, so the reads (active_plugins / load_plugin / search / fetch) delegate to an inner PathPm over the cache directory; the git-specific part is refresh — pull the repository (honoring the entry’s auto-update unless the caller forces it) — and registry_source reports it as a Git. The builtin symposium-recommendations repo is such a registry (an ordinary flat registry — each entry names the crates it advises with its own depends-on, so no namespacing or dedicated convention is involved).

crate_metadata.rs — extract Cargo.toml metadata

Extracts the [package.metadata.symposium] table from a crate Cargo.toml and returns it verbatim as a toml::Table. That table uses the same schema as a Symposium.toml plugin manifest — a crate can define its plugin inline in Cargo.toml instead of (or in addition to) shipping a file. plugins::merge_crate_manifest deserializes the table and merges it with any Symposium.toml; validation happens when the resulting plugin reaches plugins::validate_plugin. There is no longer a separate crate-metadata skill schema: the old path = "..." / crate = {..} redirect forms are now ordinary [[skills]] source.path groups and [[plugins]] source.cargo chained references.

predicate.rs: predicate evaluation

The predicate syntax (the Predicate tree, both surface spellings, parsing, Display, and serde) lives in symposium_sdk::predicate::syntax and is re-exported here, so crate::predicate::Predicate still names the same type. The split lets a manifest carry predicates without linking evaluation. Evaluation is the PredicateEval extension trait, an extension trait because the types are foreign.

The syntax covers both dependency-graph matching and runtime/environment gating: one Predicate enum, PredicateSet (a list ANDed together), and this module’s PredicateContext (the workspace dependency list it evaluates against — PackageIds from the package-manager layer’s list_deps — plus the use-enabled plugin names that wake dormant plugins, threaded in with with_used_names and read by is_used). Two surface syntaxes lower to the same tree:

• The depends-on field uses dependency-atom syntax (serde, serde>=1.0, *) and lowers, via DependsOnList, to depends-on(...) / depends-on(*) predicates OR-combined into a single any(...) that is appended to the same list. So depends-on is sugar — there is no separate dependency-predicate type.
• The predicates field uses function-call syntax: depends-on(<atom>), shell(<cmd>) (verbatim arg, sh -c, exit 0 holds), path_exists(<arg>) (disk, then $PATH for bare names), env(<name>[=<value>]), workspace-member() (the plugin is defined by a member of the active workspace — provenance stamped per plugin into PredicateContext via Plugin::applies; registry loading stamps false, workspace-plugin loading stamps true), and the combinators not(<p>), any(<p>, …), all(<p>, …). The retired crate(...) spelling is rejected with a migration hint, as are the old crates fields.

Each gated struct (plugin, skill group, skill, hook, MCP server, subcommand) stores a single merged predicates: PredicateSet. Evaluation is PredicateSet::evaluate(ctx) -> bool — a predicate is purely a boolean gate. A depends-on atom matches a dependency by exact name; a version requirement is checked when the dependency id’s version component parses as semver. collect_dep_names (crates.io validation) walks all positions regardless. Plugin/group/skill/MCP predicates are evaluated at sync time; hook dispatch evaluates the plugin-level set (so a plugin’s depends-on now gates its hooks) plus the hook-level set. Hook dispatch threads in the workspace crate list, but resolves it (running cargo) only when some plugin- or hook-level predicate references a concrete depends-on(...), or there is crate-plugin expansion to perform — a chained [[plugins]] edge or a [plugins] enablement entry (hook_dispatch_needs_deps) — since expansion evaluates predicates against the crate graph too. A workspace whose plugins have none of these dispatches without a cargo query. See the predicates reference.

skills.rs — skill resolution and matching

Given a PluginRegistry and workspace dependencies, this module resolves skill group sources, discovers SKILL.md files, and evaluates dependency predicates at each level (plugin, group, skill) to determine which skills apply. It also owns active_plugins — the crate-expansion walk that produces the shared active plugin set every facet resolves over (see below) — so the same seam that resolves skills also feeds MCP-server, hook, and subcommand dispatch. Every source funnels through one seam: resolve_group_dirs turns a group into a list of ResolvedSkillDir (a base directory + report labels), then collect_skills_from_dirs scans each base for SKILL.md files. PluginSource has exactly two variants — Path (already on disk, relative to the plugin’s source dir) and Git (fetched via the git cache); a source is required, so there is no “no source” state.

The single seam every facet resolves over is active_plugins: it returns the full active set — every registry plugin whose gate holds (cloned), followed by the crate-sourced plugins transitively reached through [[plugins]] chained references and dependency enablement. Skills, MCP servers, hooks, and subcommands all iterate this one list, so a crate-sourced plugin’s extensions dispatch exactly like a registry plugin’s. Because crate loading is cache-only (CargoPm::load_plugin fetches with UpdateLevel::None), building the set is safe even on the per-event hook path.

active_plugins is a worklist fixed-point over the PM set (pms). It seeds the active set with the trust-root plugins the registry loaded (registry.plugins, each gated by record_active), then works a queue of PackageIds: each active plugin’s [[plugins]] chained source.cargo references (edges whose predicates hold, evaluated against the owning plugin’s provenance) plus the consented enabled-dependency ids (below). For each id it calls pms.load_plugin(id) — dispatched to the owning PM (the cargo transport builds the crate as a first-class Plugin from [package.metadata.symposium] + Symposium.toml + defaults) — gates each result, records it, and enqueues its own edges. A visited set keyed on (pm, normalized name) collapses diamonds (a crate reached two ways loads once, so its hooks don’t double-fire and its subcommands aren’t a false conflict) and breaks cycles; the finite crate universe bounds termination, so there is no depth cap. collect_skills then walks the active set and runs each plugin’s skill groups through the ordinary load_skills_for_group pipeline; each discovered skill’s install identity is the hash of its on-disk SKILL.md path (below), so a crate reached two ways dedupes to one install. A crate plugin’s custom predicate definitions are the one facet not yet wired in — warn_undispatched_crate_features logs when a crate declares one.

The enabled-dependency ids seed the same worklist: discovery::enabled_dependencies names the crates covered by [plugins] auto-enable or an applicable use entry — both the workspace deps it enables and the used crates that aren’t deps at all — and each is pushed as a cargo id, so a crate’s skills/ (or manifest) installs with no plugin manifest anywhere pointing at it. A name a configured registry already provides as a plugin (including a dormant one use wakes) is skipped here, so it isn’t also fetched from crates.io. This is where consent lands — enabled_dependencies reads the [plugins] config, so only consented crates enter the worklist. workspace_root is a parameter because both this and the use-name context are scoped per workspace.

Production sync shares one PredicateContext across the skill and MCP passes, so it calls active_plugins then collect_skills directly rather than the skills_applicable_to convenience wrapper (which builds its own context and is test-only).

Each applicable skill carries an origin hash (a String) describing where its bytes live, used at sync time for dedup and install-path disambiguation. skill_origin_hash computes it as an 8-hex-char prefix of SHA-256 over the SKILL.md’s canonical on-disk path — nothing else. Identity is the file’s location, not which plugin manifest pointed at it: two references that resolve to the same file (the same crate reached through two chained plugins, or two source.path groups landing on the same bundle) produce the same hash and dedupe; skills at different paths stay distinct. Canonicalizing inside the hash is what makes that hold across discovery paths, since group scan dirs are canonicalized inconsistently — so on a platform whose temp prefix is a symlink (macOS /var → /private/var) the same file would otherwise hash two ways and install twice.

Because the hash is the dedup key itself, a 32-bit collision between two genuinely distinct paths would silently drop one skill (rather than clashing loudly at install time) — a deliberate trade for carrying only a string, not a structured origin, to the sync layer.

sync prefers the plain <agent-skills-dir>/<skill-name>/ and only falls back to <skill-name>-<origin-hash>/ when needed: when more than one origin claims the same skill name, or when the unsuffixed slot is already occupied by a user-managed directory (one without the .symposium marker). The suffix is an 8-hex SHA-256 prefix for every origin kind. The .symposium marker, wildcard .gitignore, and stale-cleanup walk all key on the marker file rather than directory name shape, so transitions between unsuffixed and suffixed names self-heal across syncs.

The skill name comes from plugin content and becomes that directory name, so it is untrusted input: load_skill rejects any name is_safe_dir_name refuses (one that could resolve outside the skills directory), and the skill fails to load instead of being installed. Agent::project_skill_dir and global_skill_dir assert the same check before joining the name.

discovery.rs — dependency discovery and enablement

Enablement is the second axis alongside activation predicates: predicates say when a plugin applies, enablement says whether it may run at all. The workspace and the configured registries are trust roots; a dependency deliberately is not, since depending on a crate should not let its author inject agent context. So a plugin embedded in a dependency runs only with consent, and a registry plugin with no gate to infer stays dormant until named. The two trust roots are loaded and gated directly — registry plugins by load_registry + PluginManifest::applies, workspace plugins the same way — so they never reach discovery. What discover classifies is exactly the untrusted offers: the dependency-embedded plugins a transport (CargoPm) surfaces. The trust boundary is structural: a positional registry entry (an offer with a subpath) is loaded directly, while a dependency-embedded offer (no subpath) is the consent path’s concern.

discover(sym, deps) derives the workspace root from the resolver (empty when there is none) and asks the untrusted instances — the cargo transport — for their active_plugins(dep_ids): the plugins embedded in the workspace’s dependencies (fetched cache-only into the already-extracted source, no probe). Each is classified by decide against [plugins] on its crate name — Used, Declined, AutoEnabled, or Candidate — and lands in the matching field of the returned Discovery (active / auto_enabled / candidates / declined). Explicit decisions outrank standing ones, so a declined name stays declined. Discovery writes nothing; the trusted registries are skipped, since their plugins are trust roots and never need consent.

enabled_dependencies(sym, dep_ids, workspace_root) is the activation side, consumed by skills.rs and status_command.rs: the crate names to load — workspace deps that auto-enable or an applicable use entry enables, plus used crates that aren’t deps at all (so cargo agents use <crate> pulls a plugin from crates.io whether or not you depend on it), minus the disabled ones. auto-enable contributes only deps — it is consent for what a dependency carries, not a way to add crates. It reads config rather than the offer list, so a name works even before its source has been fetched.

On top of that read side sits the consent write side. prompt_for_consent(sym, deps, out) asks one question per candidate (enable / ask me later / never ask again) and apply_consent records the answers — approvals into auto-enable, declines into disable, saved to the user config. Only explicit answers are recorded: the default (“ask me later”) and Escape write nothing, so reflexively hitting Enter never permanently declines anything.

The prompt is inert unless out.is_interactive() — a non-quiet, non-capturing Output attached to a terminal on both ends. That is the whole safety property: hook dispatch and anything an agent triggers run with a quiet output, and the library test harness runs with a capturing one, so neither can reach stdin. A bare TTY check would not do, since cargo test inherits the developer’s terminal. The only caller is the Commands::Sync arm in cli.rs — the hook-triggered auto-sync path calls sync::sync directly and never passes through it. pending_candidates is the non-interactive counterpart: hook.rs’s consent_hint renders it into SessionStart context so the agent can tell the user, without symposium ever blocking.

use_command.rs / search_command.rs / status_command.rs — the enablement commands

The user-facing surface over discovery and [plugins].

use_command records enablement. use_plugin first checks whether a configured registry already offers the name — registries are trust roots, so that is a no-op — with dormant plugins the exception, since use is exactly how they wake. It then requires the name to resolve to something (a workspace dependency, checked offline first, or a PmRegistry::search hit — which reaches crates.io via CargoPm::search, so a crate you don’t depend on still resolves) before pushing a UseEntry (workspace-scoped by default, Global with --global) and saving. Both it and remove_plugin re-run sync::sync afterward, so skills install or are reaped immediately. remove_plugin matches on scope and errors when nothing matched rather than silently succeeding.

search_command unions two arms: plugin names in the loaded PluginRegistry (bare skills included, since they are now plugins) and PmRegistry::search across every instance (which matches registry entry subpaths, e.g. a skill’s directory name). A PM without a searchable registry returns an empty list and a failing instance is skipped, so an offline registry degrades the results instead of failing the command. Hits are grouped by originating instance for display; the SearchMatch report event carries the origin for the JSON form.

status_command renders the enablement report. workspace_status walks the registry plugins (root: workspace membership, use, or the registry name; state from Plugin::applies plus the requires_use gate) — this is where every recommendations-registry plugin appears — then every Discovery bucket of dependency-embedded plugins (Used / AutoEnabled → active with that root, Candidate → awaiting consent, Declined), then the used crates that aren’t dependency offers (from enabled_dependencies, e.g. use-ing a crate the workspace doesn’t depend on — otherwise invisible to discovery), then any [plugins] disable name discovery never saw. The four StatusState values — Active, Dormant, Candidate, Declined — are the report’s vocabulary.

subcommand_dispatch.rs — plugin-vended subcommands

Routes the Commands::External arm of clap’s allow_external_subcommands. dispatch_external first resolves the active plugin set (skills::active_plugins), so crate-sourced subcommands dispatch too; find_subcommand walks that set, applying plugin-level and subcommand-level dependency predicates against the workspace (with the applicable use names, so a dormant plugin’s subcommands appear once it is enabled), and returns the matched (Plugin, Subcommand) (or an error if more than one plugin claims the name). dispatch_external then looks up the named Installation, resolves it via installation::resolve_runnable, and spawns the child with stdio inherited — propagating the exit code as a u8 so callers can convert to ExitCode (binary) or treat non-zero as an error (library). applicable_subcommands is the shared iterator over the active set’s applicable subcommands, taking an already-resolved &[Plugin] so help rendering and the SessionStart discovery hint reuse it.

help_render.rs — --help rendering

Renders cargo agents --help as two audience-grouped sections, “Commands for humans” and “Commands for agents”, mixing built-in subcommands with plugin-vended ones filtered by the active workspace. Built-in audience comes from cli::builtin_audience; plugin subcommands come from subcommand_dispatch::applicable_subcommands over the resolved active plugin set (skills::active_plugins), so crate-sourced subcommands appear in help too.

help_text is the single help decision, shared by the binary and the test harness. clap’s own help flag and help subcommand are disabled (in cli::Cli), --help/-h is a manual global bool, and the entry points parse with try_parse_from — so help is decided after parsing and argument order (--help --quiet) is irrelevant. It returns the top-level grouped help for no subcommand / --help / -h / the bare help keyword; for <built-in> --help it re-renders clap’s own per-command help by walking clap’s command tree (so required-arg commands like crate-info, required-subcommand groups like plugin, and nested commands like plugin list all work); a plugin <name> --help returns None so dispatch forwards --help to the child.

render builds the grouped text by slicing clap’s rendered help — keeping the header (before Commands:) and the options block (from Options: on) and hand-rendering only the two section headings between them. If a slice marker is missing (clap format drift), it falls back to clap’s unmodified help rather than panicking.

hook.rs — hook handling

Handles the hook pipeline: parse agent wire-format input → auto-sync → builtin dispatch → plugin hook dispatch → respond. The response is a HookResponse (stdout, stderr, exit code), since some decisions travel only through the exit code: a plugin hook’s exit 2 on PreToolUse becomes a canonical deny (blocked_response), and Kiro receives any denial as exit 2. A single WorkspaceDeps (created via sym.workspace_deps(cwd)) is threaded through all stages — run_auto_sync, dispatch_builtin, dispatch_plugin_hooks, and the SessionStart prewarm. In-process, at most one cargo metadata invocation occurs per hook call (down from up to three previously). Across invocations, the disk cache means zero cargo metadata calls when Cargo.lock hasn’t changed — the common case for PreToolUse hooks.

run_auto_sync takes a session_start flag: on SessionStart it skips the Cargo.lock freshness gate and syncs with UpdateLevel::Check (so upstream skill/source changes land once per session); every other event keeps the gated, UpdateLevel::None path. The matching ensure_registries refresh level is decided in the binary entry point from the same event. SessionStart additionally runs prewarm_hook_sources (best-effort, gated by auto-sync): it walks every applicable plugin’s hooks and refreshes each installation’s already-cached source via refresh_installation_if_present (UpdateLevel::Check). This is what keeps hook binaries/scripts (not just manifests) current once per session — in particular the only path that re-pulls a cargo + git hook binary whose branch moved — so the dispatch path can keep acquiring with None (cache/debounced) and pay no per-event network cost. It is refresh-only: a source that was never acquired is left alone (it installs lazily on first dispatch), so SessionStart never eagerly installs a tool a hook may never use.

On SessionStart, handle_session_start composes three independently-computed additionalContext fragments: a discovery_hint (suggests cargo agents --help when the workspace exposes applicable plugin subcommands, reusing subcommand_dispatch::applicable_subcommands), a consent_hint (names the dependency plugins awaiting consent, via discovery::pending_candidates — a hook must never block on stdin, so the candidates are reported as context pointing at cargo agents sync / cargo agents use rather than asked about), and an update_nudge (the throttled self-update warning); only the nudge is gated behind the update-check throttle. handle_post_tool_use and handle_user_prompt_submit add one generic notice (there may be new plugins, run cargo agents sync) when run_auto_sync reports that it re-synced because Cargo.lock changed. The plugin dispatch path matches plugin Hooks against the event over the active plugin set (skills::active_plugins, so crate-sourced hooks fire too), selects the best format for each plugin (native match > symposium > single-other-agent fallback), builds a ResolvedHook per match (looking up the named installations on the plugin), then for each ResolvedHook: acquires its requirements (best-effort), runs install_commands after the source step, picks a Runnable from (hook-or-install) executable/script, and spawns it (binary directly for Exec, via sh <path> for Script). Input is delivered in the selected format; output is converted back to the agent’s wire format before returning.

state.rs — persistent state

Manages state.toml in the config directory. Deserializes through RawState and validates into the runtime State. Tracks the semver of the binary that last touched the directory (for future migration hooks) and the timestamp of the last update check (to throttle crates.io queries to once per 24 hours). ensure_current() is called on startup to silently stamp the current version. should_check_for_update() / record_update_check() gate the auto-update flow.

telemetry/ — opt-in usage telemetry

Implements the local, opt-in telemetry event log under <config-dir>/telemetry/, one JSONL file per UTC day. Off by default; gated by [telemetry] enabled. A TelemetryEvent is an at timestamp plus a kind-tagged EventKind (session_start / user_prompt / tool_use), serialized one per line. record / record_kind append an event; roll_off deletes files older than RETENTION_DAYS (30); read_events / recent_events read them back; usage + status_text back telemetry status; recent_events backs telemetry show. Events are anonymous by construction — no prompt text, command lines, or file paths. Every write path is best-effort — failures are logged and swallowed so a hook is never broken. The recording entry points are not yet called from the hook pipeline, so no events are produced today even when telemetry is enabled.

The replacement recording contract is being built behind private schema, identity, and state submodules before it is connected to production callers. Within schema, mod.rs owns shared row primitives and version dispatch, macros.rs owns strict versioned-row boilerplate for rows with and without cross-field validation while each row module keeps its validation rules, metrics.rs owns the fixed latency histogram and complete-session validation shared by hook aggregate rows, and hook.rs owns the strict hook-metrics row and read-side validation. Its hook/surface.rs, hook/outcome.rs, hook/key.rs, and hook/update.rs children keep SDK surface mapping, outcome accounting, the typed hook_subject dimension and aggregate key, and atomic write updates with their respective tests. plugin_hook.rs owns the strict plugin-hook aggregate row and read-side validation. Its plugin_hook/outcome.rs, plugin_hook/bucket.rs, and plugin_hook/update.rs children keep outcome accounting, validated public identity and pre-admission attribution, and atomic write updates with their respective tests. name.rs owns validation shared by public name types, agent.rs owns agent vocabulary and agent-originated rows, command.rs owns eligible built-in and public plugin-command coordinates and exhaustively maps parsed CLI commands into the recorded built-in set, extension.rs owns validated public extension coordinates and vocabulary shared across event kinds, and resolution.rs owns resolution summaries and shared resolution vocabulary. Package-resolution vocabulary and validated public coordinates live in resolution/package.rs; resolution/extension.rs owns the strict recursive node vocabulary, the validated path wrapper that enforces whole-path depth, leaf-count, and encoded-size limits, the skill-only attribution persisted by the installation index, and the versioned row that derives extension_subject from its target and path. Timestamped rows validate during deserialization that day is the UTC calendar day containing at; the later archive reader separately validates that the row belongs to its daily file. Private state binds its key and identifier-window or return-cohort anchor into distinct identity scopes. Each identifier domain accepts only its contract-selected scope. Row constructors take a bound recording context, derive identifiers from their own source fields, and take their day from the context: package resolution derives package_subject from its coordinate, agent configuration derives agent_subject from its agent, command derives command_subject from its coordinate, and a full resolution reuses one context for its summary, package, and extension rows. Session start extends that context with a return-cohort scope and derives its timestamp, both subjects, and cohort_day from one bound session transition. Within state, mod.rs owns the versioned private-state file shape, state/lifecycle.rs owns the identifier-window transition for every recording plus return-cohort and identifier-reset transitions, state/open_day.rs centralizes the monotonic day transition used by daily state while persistence remains responsible for sourcing it from the one latest-opened-day high-water mark, state/session_counts.rs owns bounded private hook session sets plus contribution-count reconciliation, state/hook.rs owns the deterministic daily map that selects those trackers by aggregate key, and state/plugin_hook.rs keeps each plugin-hook row’s admitted identity, stable event ID, and session tracker behind one key-checked selection. Its state/plugin_hook/admission.rs child owns the deterministic daily map and the separate 128-public-row allowance for this aggregate family. Only this private-state boundary can create an overflow bucket; row constructors receive the coupled identity from the selected entry rather than accepting its scope, coordinate, and subject separately. A completed recording transition is a single-use value; a session transition extends it with the return-cohort selection. Binding either transition against unchanged anchors exposes only the identity scopes valid for that operation. Each hook row and private tracker share a key made from the UTC day and hook_subject, so equally sized trackers for different aggregates cannot be exchanged. Hook-metrics updates derive their row and session identities from one bound recording, reject impossible per-observation plugin counts, stage every row counter before changing private session state, and publish the two objects only after every checked update succeeds. The private storage submodule owns the new contract’s canonical paths and exclusive filesystem access: StoragePaths keeps inspectable data and its permanent .lock under <config-dir>/telemetry/ while keeping telemetry-state.toml beside that directory, and TelemetryLock makes one non-blocking acquisition whose file handle releases the lock on drop or unwind. The eventual recorder will stage rows and aggregate changes in memory, successfully replace the private state containing their anchors and entries, and only then expose those rows for publication. Their tests remain beside the responsibility they exercise.

state/codec.rs owns canonical private-state serialization, version dispatch, schema decoding, and secret-safe diagnostics. The private storage module owns the bounded file I/O that calls that codec.

Resolution summaries derive an optional session_id from a paired agent and raw vendor session identifier rather than accepting a loose scoped identifier. state/codec.rs owns canonical private-state encoding and content-free decode errors, so malformed state can never expose the identity key in diagnostics.

schema/extension_invocation.rs is the extension-invocation aggregate boundary. Its extension_invocation/vocabulary.rs child keeps the closed version 1 agent, phase, target-scope, and unnamed-reason vocabulary; extension_invocation/bucket.rs accepts only safe public attribution or a fixed unnamed reason, leaving overflow assignment to private state; and extension_invocation/row.rs owns the strict versioned row and its read-side scope, counter, and session validation. The row’s update.rs child applies one phase observation atomically from a bound recording and an admitted private-state selection, so the event id, agent, target identity, identifier epoch, and session tracker cannot be supplied independently. The independent attempted/completed session-count validator lives with the other aggregate primitives in schema/metrics.rs. state/extension_invocation.rs owns the matching bounded private sets and reconciles their independent contribution counts with the stored row. Failed observations add no session id, but still perform this reconciliation so a lost snapshot row cannot leave published counts inconsistent with private state. Its extension_invocation/admission.rs child derives coupled row identity, keeps the stable row identifier and session tracker behind one epoch-aware aggregate key, and sends new public targets beyond the daily allowance to overflow. state/public_row_budget.rs owns the shared 128-row daily allowance used independently by each named aggregate family: day rollover and clear restore it, while identifier reset does not.

Storage acquisition also tightens a pre-existing telemetry directory and lock file to owner-only modes on Unix instead of relying only on their creation modes. storage/atomic.rs writes a complete byte buffer through a same-directory temporary file before atomically replacing its destination; it does not fsync, and callers must finish serialization before replacement. Every telemetry-owned temporary uses the shared .telemetry-tmp- prefix so lazy cleanup and status recognize the same namespace. Activating the replacement recorder must remove the legacy record and roll_off paths in the same change, so two schemas and retention policies never share the telemetry directory.

LockedStorage owns both the canonical paths and TelemetryLock, so private state cannot be loaded or replaced outside the lock. Its private_state.rs child performs a bounded byte read, distinguishes TOML syntax errors, invalid state content, and unsupported versions without retaining parser source text, serializes the complete state before replacement, and requires mutable access to replace it. Its daily_files.rs sibling recognizes only canonical event and metric filenames. When private state is absent, storage initializes the high-water mark and identifier-window anchor from the later of the current UTC day and the newest surviving daily filename; malformed and unsupported state remain errors rather than entering this path.

report.rs — structured report layer

Provides user-facing output for all commands via a custom tracing layer. Commands emit tracing::info! or tracing::debug! events with a report = %ReportEvent::Variant { ... } field; the ReportLayer intercepts these and renders them based on mode:

• Normal — prints format_human() to stdout (default for most commands)
• Verbose (-v) — prints all events (info + debug) to stderr
• Json (--json) — accumulates events in a buffer, drained as a JSON array at the end

The ReportEvent enum is the stable schema — #[derive(Serialize, Deserialize)] with #[serde(tag = "kind")]. Each variant carries the fields needed to render both human and JSON forms. The Display impl serializes to JSON (for passing through tracing’s % formatter), and format_human() renders the pretty-printed form.

The layer is always installed by the binary. Commands that want output simply emit report events at the appropriate tracing level (info for actions, debug for decision trace). The --json flag also suppresses the Output-based messages and drains the JSON buffer at exit.

self_update.rs — self-update

Implements cargo agents self-update. Queries the registry for the latest published version via cargo search, then installs it via cargo install symposium --force. Also provides re_exec() which replaces the current process with the newly installed binary (Unix exec, spawn-and-exit on Windows) — used by the auto-update = "on" startup path. Contains maybe_warn_for_update() (sync, for the warn library path) and maybe_check_for_update() (async, for the binary on + re-exec path).

crate_command.rs — crate source lookup

Contains dispatch_crate(), which resolves a crate’s version and fetches its source code. Called by the CLI’s crate-info command. Path dependencies are resolved to their local source directory via WorkspaceCrate.path.

Configuration loading

Directory resolution

User-wide paths are resolved using the directories crate, which handles XDG Base Directory conventions automatically. If XDG environment variables are set, they are respected; otherwise paths fall back to ~/.symposium/.

See the configuration reference for the full resolution table.

Config loading

The user config (~/.symposium/config.toml) is loaded once at startup into the Symposium struct. The file is deserialized into RawConfig, then validated into the runtime Config used by the rest of the code. If the file is missing or empty, defaults are used. If parsing fails, a warning is printed and defaults are used.

Agents

cargo agents supports multiple AI agents. Each agent has its own hook protocol, file layout, and configuration locations. This page documents the agent-specific details that cargo agents needs to handle.

Supported agents

The agent name is stored in [agent] name in either the user or project config.

Agent responsibilities

For each agent, cargo agents needs to know how to:

1. Register hooks — write the hook configuration so the agent calls cargo-agents hook on the right events.
2. Install extensions — place skill files (and eventually workflow/MCP definitions) where the agent expects them.

Where these files go depends on whether the agent is configured at the user level or the project level (see sync --agent).

Extension locations

When installing skills, cargo agents prefers vendor-neutral paths where possible:

At the project level, Claude Code requires .claude/skills/, Kiro requires .kiro/skills/, while Antigravity, Copilot, Codex, OpenCode, and Goose all support .agents/skills/. cargo agents uses the vendor-neutral .agents/skills/ path whenever the agent supports it.

At the global level, each agent has its own path:

Claude Code

Hooks reference · Settings reference · Skills reference

Hook registration

Claude Code hooks live under the "hooks" key in settings JSON files. Each event maps to an array of matcher groups, each containing an array of hook commands.

Example hook registration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "cargo-agents hook claude pre-tool-use"
          }
        ]
      }
    ]
  }
}

Supported events

Claude Code supports many hook events. Symposium registers these:

Other events include Notification, SubagentStart, and more.

Hook payload/output

Claude Code wraps hook-specific fields in a nested hookSpecificOutput object:

{
  "continue": true,
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "additionalContext": "...",
    "updatedInput": "..."
  }
}

GitHub Copilot

Hooks reference · Using hooks (CLI) · Skills reference

Hook registration

Copilot hooks are defined in JSON files with a version field. Hook entries use platform-specific command keys (bash, powershell) rather than a single command field.

Example hook registration:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "cargo-agents hook copilot pre-tool-use",
        "timeoutSec": 10
      }
    ]
  }
}

Note: Copilot uses camelCase event names (preToolUse), unlike Claude Code’s PascalCase (PreToolUse).

Supported events

Hook payload/output

Copilot uses a flat output structure (no nested hookSpecificOutput). The input payload has toolName and toolArgs (where toolArgs is a JSON string that must be parsed separately):

{
  "permissionDecision": "allow",
  "permissionDecisionReason": "...",
  "modifiedArgs": { ... },
  "additionalContext": "..."
}

Valid permissionDecision values: "allow", "deny", "ask".

Antigravity CLI

Hooks reference

Hook registration

Antigravity hooks live in a dedicated hooks.json under the customization root — .agents/ in a workspace, ~/.gemini/config/ globally. Entries are keyed by a hook name, so symposium owns a single symposium key and leaves anything else in the file untouched.

{
  "symposium": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "cargo-agents hook antigravity pre-tool-use",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "type": "command",
        "command": "cargo-agents hook antigravity session-start",
        "timeout": 30
      }
    ]
  }
}

Note the two shapes: tool events (PreToolUse, PostToolUse) wrap their handlers in a matcher group, while lifecycle events (PreInvocation, SessionStart, Stop) take a flat list. Timeouts are in seconds, not milliseconds. An unrecognised shape or an unknown event name is accepted silently and simply never fires.

SessionStart is missing from Antigravity’s published documentation but present in its hook proto. It fires with the first turn of a new conversation (in the TUI, at the first prompt rather than at launch) and never on resume, so a resumed conversation skips the SessionStart refresh. There is no prompt event, so PreInvocation stands in for user-prompt-submit; because it fires before every model call, only invocationNum == 0 dispatches (AgentHookInput::should_dispatch).

Hook output

Exit codes are ignored entirely — only stdout matters. On PreToolUse, an object without a valid decision (including {}) is treated as a denial, so symposium always emits {"decision": "allow"} unless a plugin actually denied. Context is returned as an injected step rather than an additionalContext field:

{ "injectSteps": [{ "ephemeralMessage": "..." }] }

Kiro

Hooks reference

Hook registration

Kiro hooks live in agent JSON files under .kiro/agents/. Symposium creates a symposium.json agent file with its hooks. Kiro uses camelCase event names.

Example hook registration:

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "*",
        "command": "cargo-agents hook kiro pre-tool-use"
      }
    ],
    "agentSpawn": [
      {
        "command": "cargo-agents hook kiro session-start"
      }
    ]
  }
}

Kiro uses a flat entry format: each entry has command directly (and optional matcher), with no nested hooks array or type field.

Supported events

Hook payload/output

Kiro uses exit-code-based control flow:

• Exit 0: stdout captured as additional context
• Exit 2: block (preToolUse only), stderr as reason
• Other: warning, stderr shown

Input includes hook_event_name, cwd, tool_name, and tool_input on stdin as JSON.

Unregistration

Unregistration deletes the symposium.json file.

Codex CLI

Hooks reference

Hook registration

Codex CLI hooks live in hooks.json files. The structure is similar to Claude Code — nested matcher groups with hook command arrays. Codex uses PascalCase event names and timeout in seconds.

Example hook registration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "cargo-agents hook codex pre-tool-use",
          "timeout": 10
        }]
      }
    ]
  }
}

Note: An empty matcher string matches everything in Codex (equivalent to "*" in other agents).

Supported events

Hook payload/output

Codex uses a protocol similar to Claude Code, with two methods to block:

1. JSON output: { "decision": "block", "reason": "..." }
2. Exit code 2 with reason on stderr

Also supports hookSpecificOutput with additionalContext, and { "continue": false } to stop the session.

Input includes session_id, cwd, hook_event_name, model, turn_id, tool_name, tool_use_id, and tool_input.

OpenCode

Hooks reference

Hook registration

OpenCode does not support shell-command hooks. Its extensibility is based on TypeScript/JavaScript plugins. Symposium cannot register hooks for OpenCode.

Supported events

OpenCode’s plugin system supports these events, but Symposium does not currently bridge them:

Goose

Hooks reference

Hook registration

Goose does not implement lifecycle hooks. It uses MCP extensions for extensibility. symposium cannot register hooks for Goose.

Goose is supported as a skills-only agent — cargo agents sync will install skill files in the vendor-neutral .agents/skills/ path.

Cross-agent event mapping

The following table maps symposium’s internal event names to each agent’s wire-format event name. — means the agent does not support shell-command hooks; not registered means symposium does not hook that event there.

Tool names are each agent’s own, and symposium passes them to plugin hooks unchanged: the same shell tool is Bash in Claude Code and Codex, bash in Copilot, execute_bash in Kiro and run_command in Antigravity. A matcher that should fire on several agents has to name each of them.

Adding a new agent

To add support for a new agent:

1. Add a variant to the HookAgent enum in hook_schema.rs.
2. Create an agent module (e.g., hook_schema/newagent.rs) implementing the Agent trait and the event-specific payload/output types.
3. Implement the AgentHookPayload and AgentHookOutput traits to convert between the agent’s wire format and the internal HookPayload/HookOutput types.
4. Document the agent’s hook registration locations and extension file layout in this page.

State

Documents the kind of state maintained by the Symposium agent.

Telemetry

Telemetry is opt-in, per-user (not per-project), and local-first: events are gathered into ~/.symposium/, and uploading is a separate step the user takes deliberately. The goal is to learn whether Symposium is actually helping, while keeping the user in control of their data.

Design principles

• Opt-in, per-user. Nothing is recorded unless the user enables it; the preference lives in the user-wide config.toml.
• Local-first. Events are written to a local log under ~/.symposium/. Uploading is a separate, deliberate step.
• Anonymous by construction. Events record counts and coarse metadata only — no prompt text, command lines, or file paths.
• Extensible. Events are JSON lines, so new event kinds and fields can be added without breaking older readers.
• Never breaks a hook. Every recording path is best-effort — failures are logged and swallowed.

Event log format

When enabled, events are appended as JSON lines to per-day files under ~/.symposium/telemetry/:

~/.symposium/telemetry/events-2026-06-23.jsonl

Each line is one TelemetryEvent: an at timestamp plus a kind-tagged payload (EventKind), e.g.

{"at":"2026-06-23T17:58:13Z","kind":"session_start","session_id":"P1","agent":"claude","plugins":["tokio-plugin"]}
{"at":"2026-06-23T17:58:14Z","kind":"user_prompt","session_id":"P1"}
{"at":"2026-06-23T17:58:15Z","kind":"tool_use","session_id":"P1","tool":"Bash"}

Files older than RETENTION_DAYS (30) are rolled off — deleted on the next SessionStart.

Configuration

[telemetry]
enabled = true

The preference is collected during cargo agents init (“Enable anonymous usage telemetry?”) and can be toggled later with cargo agents telemetry enable / disable.

The telemetry subcommand

• cargo agents telemetry status — whether enabled, where data lives, and how much is stored.
• cargo agents telemetry enable / disable — toggle the opt-in.
• cargo agents telemetry show [--count N] — print recent events for inspection (the data the user would share).

What we deliberately do not record

No prompt text, no shell command lines, no file paths. “How many tries until the agent got it right” cannot be measured reliably from hook events; the trustworthy version is an explicit user rating, which a later workstream will add.

Hooks

Symposium’s hook system is guided by the project tenets: symposium is always the intermediary, it never dirties the user’s repo, and portability is the default.

Hook formats

A plugin hook declares which wire format its handler expects:

• format = "symposium" (default) — the handler receives symposium canonical JSON. This is portable across all agents.
• format = "antigravity" / "claude" / "copilot" / "codex" / "kiro" — the handler receives that agent’s native wire format.

Dispatch rule

When symposium’s global handler receives an event from agent A, it loads all plugins and finds hooks matching the event. For each plugin, it picks at most one hook to deliver:

1. If the plugin declares a hook with format matching agent A → deliver the input unmodified (the handler already expects this agent’s native format).
2. Otherwise, if the plugin declares a symposium-format hook → convert to symposium canonical and deliver.
3. Otherwise → nothing fires for this plugin.

Symposium never converts between agent-specific formats. A format = "claude" hook will only fire on Claude — it won’t be translated for Copilot or Antigravity. If you want cross-agent coverage, provide a symposium-format hook as a fallback.

Example

A plugin with hooks for claude, antigravity, and symposium:

• On Claude: the format = "claude" hook receives Claude’s native JSON.
• On Antigravity: the format = "antigravity" hook receives Antigravity’s native JSON.
• On Copilot: no native handler → the format = "symposium" hook receives symposium canonical JSON.

A plugin with only format = "symposium":

• Works on all agents. Symposium converts the agent’s wire format to canonical before delivering.

A plugin with only format = "claude":

• On Claude: receives Claude’s native JSON directly.
• On other agents: nothing fires (no symposium fallback declared).

Output handling

Symposium converts the hook’s output back to the current agent’s wire format before returning it to the agent:

• Native format matching the host agent → pass through directly.
• Symposium format → convert to host agent’s wire format.

Alternatives considered

Registering agent-specific hooks directly

An earlier design had symposium write plugin hook commands directly into agent configuration files (e.g., .claude/settings.json, .github/hooks/*.json) at sync time. The agent would invoke them natively, and symposium’s global handler would skip delivery for those plugins.

We rejected this because it violates the Unobtrusive tenet:

• Agent config files are often git-tracked. Writing plugin hooks into them creates unexpected diffs that pollute pull requests and cause merge conflicts.
• Users would need to .gitignore symposium-managed entries, or accept noise in their version history.
• It couples symposium’s state to files the user considers “theirs,” making it harder to adopt or remove symposium cleanly.

The current design avoids these problems by keeping symposium as the sole registered hook handler. Plugin hooks are dispatched internally — the agent’s config only ever contains one symposium entry, registered at init time.

Cross-agent format conversion

We also considered converting between agent-specific formats (e.g., delivering a format = "claude" hook on Copilot by translating Copilot’s input into Claude’s format). We rejected this because:

• The conversion is lossy — agents have different fields, semantics, and capabilities.
• It creates surprising behavior: a hook author declares format = "claude" expecting Claude’s schema, but receives a synthetic approximation on other agents.
• It’s simpler and more predictable to require a symposium-format fallback for cross-agent coverage.

Subcommands

A subcommand is a top-level cargo agents <name> command vended by a plugin. Subcommands are the fourth thing a plugin can contribute, alongside skills, hooks, and MCP servers. Where skills and MCP servers extend the agent’s surface, subcommands extend cargo agents itself, exposing crate-aware tooling that runs on the user’s machine.

The motivating use cases:

• A crate ships its own analysis binary alongside the library. The crate author wants cargo agents <name> … to be a discoverable entry point for agents working in projects that depend on that crate, rather than requiring users to install and remember a separate CLI.
• crate-info is moved out of the built-in CLI into a first-party plugin, shrinking the static command surface.
• A [subcommand.<name>] named after the crate is the expected convention, but is not enforced.

Relationship to [[installations]]

Subcommands reuse the installation framework introduced for hooks. An installation declares how to acquire a binary or script (cargo install with binstall fast-path, github clone, or a path on disk), where it caches, and which executable or script to run. Subcommands reference installations by name, or declare them inline, the same shape hooks use.

This means a plugin author writes installation logic once and shares it across hooks and subcommands. Symposium owns acquisition, caching, idempotency, and post-install setup; subcommands only own dispatch.

Manifest schema

name = "demo-plugin"
depends-on = ["example-crate"]

[[installations]]
name = "example-tool"
source = "cargo"
crate = "example-tool"
executable = "example-tool"
args = ["serve"]

[subcommand.demo]
description = "Run the demo tool"
audience = "agents"
command = "example-tool"

Reserved names that cannot be used as subcommand keys: every built-in command (init, sync, search, use, status, hook, plugin, self-update, crate-info, telemetry) and help. A plugin cannot shadow a built-in.

The TOML key is singular ([subcommand.<name>]), matching the natural read of a TOML table. The internal field on PluginManifest is plural (subcommands).

Inline form

For one-off subcommands the inline form avoids a separate [[installations]] block:

[subcommand.demo]
description = "..."
command = { source = "cargo", crate = "example-tool", executable = "example-tool", args = ["serve"] }

The inline table is promoted to a synthetic installation named after the subcommand and resolved through the same pipeline.

Pass-through contract

Symposium does not own the subcommand’s argument grammar. The plugin’s binary owns its own --help, validation, and exit codes. What symposium contributes is mechanical:

1. Name registration and lookup.
2. Workspace-aware filtering (the subcommand only appears for projects matching the plugin’s dependency predicates).
3. A short description shown in cargo agents --help.
4. Resolution of command through the installation pipeline to a concrete (executable, base_args).
5. Forwarding the user’s trailing CLI args verbatim, appended after the installation’s args.

This boundary keeps the manifest small, keeps plugins authoritative about their CLI, and avoids inventing a symposium-specific options DSL that would drift from each plugin’s real interface.

Dispatch

cargo-agents’s top-level CLI uses clap’s allow_external_subcommands: unknown subcommands are not errors but are routed to a catch-all variant. The binary then:

1. Loads the plugin registry and the active workspace’s crates.
2. Walks active plugins for one whose subcommands map contains the typed name and whose subcommand-level depends-on predicate (if any) also matches.
3. Resolves the subcommand’s command through the installation pipeline — acquiring the binary if it isn’t already cached, running any install_commands, processing requirements.
4. Execs the resolved (executable, base_args ++ user_args), inheriting stdio.
5. Returns the child’s exit code as the cargo agents exit code. A signal-killed child becomes a generic failure.

Argument forwarding uses a structured Vec, not sh -c. User-supplied argv is preserved exactly — spaces, quotes, and shell metacharacters in args are not re-tokenized. This matters more for subcommands than for hooks (whose input arrives over stdin as JSON).

Script-mode installations (script = "...") are still invoked through sh <path>, mirroring hook dispatch. That path is not cross-platform on Windows and is tracked as a follow-up for both hooks and subcommands; in the meantime, plugin authors who need Windows support should use executable = "..." instead.

If no plugin matches the typed name, dispatch fails with a clear error pointing to cargo agents --help. If a matching subcommand exists but installation fails, the installation layer’s error is propagated as-is.

Workspace filtering

Plugin filtering is workspace-aware in two places: help rendering and dispatch.

Inside a Cargo workspace. Symposium reads the workspace’s resolved dependencies. A subcommand appears in cargo agents --help and is dispatchable only if both the plugin-level and subcommand-level depends-on predicates match. Built-in subcommands always appear.

Outside a Cargo workspace (no discoverable Cargo.toml upward). Only built-ins and plugins with depends-on = ["*"] appear. Invoking a crate-specific subcommand from outside a workspace produces an error explaining which crate it needs.

This rule keeps cargo agents --help outside a workspace limited to globally-applicable commands, rather than listing every installed plugin.

Help text grouping

cargo agents --help is rendered in two sections:

• Commands for humans — operational commands a user runs themselves: init, plugin, search, self-update, status, sync, telemetry, use, plus any plugin-vended subcommand with audience = "humans".
• Commands for agents — discovery and analysis tools for the agent to invoke: crate-info and plugin-vended subcommands with audience = "agents" (the default).

The default of audience = "agents" reflects the expected shape of plugin-vended commands: most are analysis or context-fetching tools surfaced to agents, not workflows for humans. The exceptional case explicitly opts in.

For this grouping to be useful, crate-info is no longer hidden — it’s a discoverable agent tool. hook remains hidden; it’s an internal protocol entry point, not an end-user surface.

The renderer reads the active plugin registry filtered by workspace, so the help output adapts to the project the user is standing in.

--help, -h, the bare help keyword, and an empty invocation are intercepted after clap parses and routed to this renderer; help is never listed as its own command. A <built-in> --help instead shows that command’s own help (re-rendered from clap), and a plugin-vended <name> --help is forwarded to the plugin’s binary, which owns its --help.

Agent discovery

cargo agents --help is a pull surface — an agent only sees the crate-aware subcommands if it already knows to run it. To push that affordance, the built-in SessionStart hook injects a one-line hint suggesting cargo agents --help whenever the active workspace exposes at least one applicable plugin-vended subcommand. The trigger reuses the same workspace-filtered set as the help renderer (applicable_subcommands), so the hint stays silent in projects with nothing to discover.

The hint shares SessionStart’s additionalContext with the update nudge and the pending-consent hint; each fragment is computed independently, and only the nudge is gated behind the update-check throttle. Agents without hook registration (OpenCode, Goose) don’t receive it; for them cargo agents --help is the only discovery surface.

The consent hint is the same pattern applied to enablement. A hook runs on the agent’s behalf and must never block on stdin, so when dependency discovery finds plugins awaiting consent, SessionStart names them as context and points at cargo agents sync (which asks interactively) or cargo agents use <name> — explicitly telling the agent not to enable them itself. The interactive prompt lives only in the sync command’s own CLI arm, gated on Output::is_interactive().

Audience as metadata, not enforcement

audience controls help-text grouping only. It does not gate dispatch. A user can type cargo agents <agent-audience-subcommand> directly and it will run. The intent is to keep the discovery surface uncluttered for humans, not to lock anyone out.

Conflict resolution

Two plugins may declare the same subcommand name. Rather than silently picking one, dispatch fails with an error listing every plugin that defined the name, leaving the user to disambiguate (typically by tightening one of the plugin’s depends-on predicates or removing one of the plugin sources).

The strict-error stance trades silence for clarity: subcommand names tend to mirror crate names (which are unique on crates.io), so a collision usually signals a real configuration mistake rather than an intended override.

Namespacing (cargo agents <plugin>:<name>) is not implemented; it can be revisited if a real conflict pattern emerges.

What plugins own vs. what symposium owns

Structured report layer

Commands produce user-facing output by emitting tracing events with a report field. A custom tracing layer (ReportLayer) intercepts these events and renders them in one of three modes depending on CLI flags.

How it works

Command code                  Tracing infrastructure             User
─────────────                 ──────────────────────             ────
tracing::info!(           →   ReportLayer::on_event()      →   stdout/stderr/JSON
  report = %ReportEvent::SkillInstalled { ... }
)

1. Command code emits a tracing event at info (actions) or debug (decisions) level, carrying a single report field whose value is a ReportEvent formatted via Display (which serializes to JSON).
2. The ReportLayer checks: does this event have a report field? Is its level within max_level?
3. If yes, it deserializes the JSON string back into a ReportEvent and renders it based on mode.

Modes

The layer is always installed — commands don’t need to check whether reporting is active.

Adding a report event to a new command

Step 1: Add a variant to ReportEvent

In src/report.rs, add a new variant to the enum:

#![allow(unused)]
fn main() {
/// A frobnitz was reticulated.
FrobnitzReticulated {
    name: String,
    count: usize,
},
}

Rules for variants:

• Use #[serde(skip_serializing_if = "Option::is_none")] for optional fields
• Don’t use a field named kind (conflicts with #[serde(tag = "kind")])
• Keep fields simple (String, bool, usize, Option)

Step 2: Add a format_human arm

In the format_human() method, add a rendering arm:

#![allow(unused)]
fn main() {
Self::FrobnitzReticulated { name, count } => {
    format!("✅ reticulated {name} ({count} nodes)")
}
}

Use emoji prefixes to match the existing style:

• ✅ — success/action taken
• ➖ — removal
• ⚠️ — warning
• ℹ️ — informational
• 🟢 — already in place / no-op

Step 3: Emit from command code

#![allow(unused)]
fn main() {
tracing::info!(
    report = %crate::report::ReportEvent::FrobnitzReticulated {
        name: frobnitz.name.clone(),
        count: frobnitz.nodes.len(),
    },
);
}

Use tracing::info! for actions the user should always see, tracing::debug! for decision-trace detail that only appears with -v.

Level conventions

The Info and Warning variants

For messages that don’t map to a specific structured event, use the generic variants:

#![allow(unused)]
fn main() {
tracing::info!(
    report = %crate::report::ReportEvent::Info {
        message: format!("scanning {} workspace dependencies", count),
    },
);
}

Prefer specific variants over Info/Warning when the data is structured — they produce better JSON output.

Testing

The test harness (symposium-testlib) provides sync_with_report() which installs a scoped Json-mode layer and returns captured events. Tests assert on the JSON structure:

#![allow(unused)]
fn main() {
let events = ctx.sync_with_report(tracing::Level::DEBUG).await?;
let installed: Vec<&Value> = events
    .iter()
    .filter(|e| e["kind"] == "skill_installed")
    .collect();
assert!(!installed.is_empty());
}

Architecture notes

• The Display impl on ReportEvent serializes to JSON — this is how the value passes through tracing’s % formatter into the visitor
• The layer’s visitor checks record_debug (not record_str) because % goes through the debug path
• Per-layer EnvFilters ensure the report layer receives all events regardless of file log level
• The ReportHandle (returned alongside the layer) allows draining accumulated JSON after the command completes

Important flows

This section describes the logic of each cargo agents command.

Crate-sourced skill resolution

A plugin loads a crate as a plugin by naming that crate in a [[plugins]] chained reference (source.cargo = "..."); the user can also load one directly by enabling the dependency it lives in (see enablement below). When the owning plugin is active and the edge’s predicates hold, the crate is resolved into the active plugin set — the shared list every facet (skills, MCP servers, hooks, subcommands) resolves over, so a crate-sourced plugin’s extensions dispatch exactly like a registry plugin’s. A single path handles every crate — a crate is always a first-class plugin, whether it describes itself with a Symposium.toml, with [package.metadata.symposium], with both, or with neither:

1. skills::active_plugins seeds a worklist from the trust-root plugins the registry loaded: each active plugin’s plugin.chained edges whose predicates hold (evaluated against the owning plugin’s provenance) contribute a source.cargo crate id.
2. For each id the fixed-point calls pms.load_plugin(id) on the package-manager set active_plugins was handed (built once by package_managers(deps)). The id’s pm routes it to the cargo transport, which:
   • CargoPm::fetch resolves the source via RustCrateFetch (path overrides for local path deps, then the cargo registry cache, then crates.io) with UpdateLevel::None — cache-only, so this is safe on the per-event hook path. The fetched id carries the exact resolved version.
   • CargoPm::plugin_from_fetched returns the crate as an unvalidated plugin, with a manifest plugins::merge_crate_manifest builds by layering two sources (merge order: [package.metadata.symposium] from Cargo.toml → Symposium.toml file). Both use the ordinary plugin-manifest schema and are parsed leniently (a malformed layer is logged and dropped).
   • The cargo instance validates it (plugins::validate_plugin with PluginKind::Package), under ManifestOrigin::Crate (name defaults to the crate, depends-on is waived, [defaults] accepted, default skills/ group appended unless [defaults] skills = false). The result is a Plugin whose canonical id is the resolved crate. A crate with no manifest sources still yields one whose only content is that default skills/ group.
3. record_active honors the crate plugin’s own plugin-level predicates (applies, which stamps its provenance — never a workspace member), appends it to the active set, and enqueues its own [[plugins]] edges. This is how a [package.metadata.symposium] redirect (now a [[plugins]] source.cargo chained reference to the target crate) is followed. A visited set keyed on (pm, normalized name) — global across the whole active_plugins call — collapses diamonds (a crate reached through two plugins loads once, so its hooks don’t double-fire and its subcommands don’t read as a false conflict) and breaks cycles; the finite crate universe bounds termination.
4. Facet extraction then walks the active set. collect_skills runs each plugin’s skill groups through the ordinary load_skills_for_group pipeline — honoring named groups, group predicates, and source.path/source.git, with each discovered skill’s origin hashed from its on-disk SKILL.md path (this is where git skill sources are fetched, hence the update level). MCP-server filtering (sync), hook dispatch (hook::dispatch_plugin_hooks), and subcommand lookup (subcommand_dispatch) each iterate the same set. A crate plugin’s custom predicate definitions are the one facet still not wired in — they resolve only from configured registries, and warn_undispatched_crate_features notes when a crate declares one.

A skill’s install identity is the hash of its on-disk SKILL.md path, so a crate reached two ways dedupes to one install. The edge’s version requirement is recorded but not yet enforced — the crate resolves against the workspace (pin / path override).

The key code paths are in pm/cargo/mod.rs (CargoPm::load_plugin, plugin_from_fetched), pm/mod.rs (PmInstance, PluginKind), plugins.rs (merge_crate_manifest, validate_plugin, RawPluginManifest::merge, ManifestOrigin::Crate, Plugin::canonical), skills.rs (active_plugins, record_active, plugin_key, collect_skills, hash_origin_key), crate_metadata.rs (symposium_metadata), pm/cargo/workspace.rs (WorkspaceDeps, WorkspaceCrate), and crate_sources/mod.rs (RustCrateFetch).

Dependency enablement

A dependency’s own plugin content — a Symposium.toml, [package.metadata.symposium], or a skills/ directory — is reachable without any manifest pointing at it, but only with the user’s consent: dependencies are not a trust root.

1. discovery::discover asks the untrusted cargo transport for its active_plugins(dep_ids): the plugins embedded in the workspace’s dependencies. CargoPm::active_plugins fetches each dependency cache-only and inspects it — a workspace dep resolves into the source cargo metadata already extracted (WorkspaceCrate::source_dir), no probe/network — so registry-dep embedded plugins are discoverable too. The trusted registries (including the recommendations repo) are skipped, because their plugins are trust roots and never need consent. Each candidate is classified against [plugins] on its crate name — enabled by use, auto-enabled, declined, or an undecided candidate. Nothing is prompted or written.
2. At sync time, skills::active_plugins asks discovery::enabled_dependencies which crate names [plugins] auto-enable or an applicable use entry covers — workspace deps, plus used crates that aren’t deps at all — and seeds each as a cargo id on the same worklist a chained reference feeds, so pms.load_plugin honors the crate’s manifest sources, skill groups, and its own [[plugins]] edges. This reads config rather than the offer list, so cargo agents use <crate> loads a crate from crates.io whether or not the workspace depends on it, and even before its source has been fetched. (CargoPm::search is what lets use name such a crate; a name a configured registry already provides is skipped here so it isn’t double-loaded.)
3. Independently, a registry plugin with no dependency gate anywhere loads dormant (PluginManifest::requires_use) and activates only when a use entry names it. The gate rides the PredicateContext (with_used_names / is_used), so skill resolution, hook dispatch, subcommand lookup, help, and MCP filtering all agree.

Decisions are recorded by the consent prompt in an interactive cargo agents sync (discovery::prompt_for_consent, which writes auto-enable and disable) and by cargo agents use (use entries); cargo agents status reports what [plugins] currently decides. A hook never prompts: SessionStart names the pending candidates as context instead.

The key code paths are in discovery.rs, config.rs (PluginsConfig, UseEntry), pm/cargo/mod.rs (active_plugins, load_plugin), plugins.rs (PluginManifest::requires_use), predicate.rs (PredicateContext::is_used), and skills.rs (active_plugins, record_active).

Help rendering

cargo agents --help (and -h, the bare help keyword, or no subcommand) is rendered by help_render, not by clap’s default help.

1. The binary and the test harness parse argv with Cli::try_parse_from, then call help_render::help_text(parse, args, sym, cwd). Because the decision happens after parsing, argument order (--help --quiet) does not matter and there is no second argv parser to keep in sync.
2. For no subcommand, --help/-h, or the bare help keyword, help_text returns the top-level grouped help: render slices clap’s own rendered help (header + options block) and hand-renders “Commands for humans” / “Commands for agents” between them, mixing built-ins (cli::builtin_audience) with workspace-filtered plugin subcommands (subcommand_dispatch::applicable_subcommands).
3. For <built-in> --help, help_text re-renders clap’s per-command help by walking clap’s command tree to the named subcommand — so required-arg commands (crate-info), required-subcommand groups (plugin), and nested commands (plugin list) all work even though clap’s auto help flag is disabled.
4. A plugin-vended <name> --help is left alone: help_text returns None, and dispatch forwards --help to the child binary, which owns its own help.

clap’s auto help flag and help subcommand are disabled in cli::Cli; --help/-h is a manual global bool. The key code paths are in help_render.rs (help_text, render, subcommand_help), cli.rs (builtin_audience, the Cli flags), and bin/cargo-agents.rs plus symposium-testlib (the parse-then-help_text wiring).

Subcommand dispatch

When the user runs cargo agents <name> for a name not built into the binary, clap’s allow_external_subcommands routes it to Commands::External(argv).

1. The binary (or library cli::run) calls subcommand_dispatch::dispatch_external(sym, cwd, argv), which first resolves the active plugin set (skills::active_plugins — registry plugins plus crate-sourced ones) so a crate’s subcommands are dispatchable too.
2. find_subcommand walks that set. For each plugin it applies the plugin-level depends-on predicate against the workspace, then looks up argv[0] in plugin.subcommands. If the entry has its own depends-on predicate, that must also match. Two or more matches → error.
3. The matched subcommand’s command field names an Installation on the same plugin. installation::resolve_runnable acquires the source if any, runs install_commands, and picks the Runnable (Exec for binaries, Script for shell scripts).
4. The child is spawned with stdio inherited. Its exit code is collapsed to a u8 — the binary wraps it in ExitCode::from; the library treats non-zero as an error so the test harness can assert on success/failure.

The key code paths are in subcommand_dispatch.rs, cli.rs (the External arm), and bin/cargo-agents.rs (binary-side wrapping that surfaces the numeric exit code to the OS).

cargo agents init

Sets up the user-wide configuration.

Flow

1. Prompt for agents — ask which agents the user uses (e.g., Antigravity CLI, Claude Code, Copilot). Multiple agents can be selected.

2. Write user config — create ~/.symposium/config.toml with the [[agent]] entries populated:

   [[agent]]
   name = "claude"
   
   [[agent]]
   name = "antigravity"
   

3. Register hooks — register global hooks and MCP servers for each selected agent. Also unregisters hooks for any agents that were removed.

If --add-agent or --remove-agent flags are provided, the interactive prompt is skipped and the specified changes are applied to the existing agent list.

cargo agents sync

Scans workspace dependencies, installs applicable skills into agent directories, and cleans up stale skills.

Flow

0. Consent prompt (interactive cargo agents sync only) — ask about each dependency plugin awaiting consent and record the answers in [plugins] before resolution runs, so an approval installs in this same sync. Gated on Output::is_interactive(): the hook-triggered auto-sync calls sync::sync directly and never reaches this step. See dependency discovery.

1. Find workspace root — run cargo metadata to locate the workspace manifest directory.

2. Load registries — read the user config’s [[registry]] entries, ask each one’s package manager for the plugin-bearing entries it offers, and load their plugin manifests. For git registries, fetch/update as needed.

3. Scan dependencies — read the full dependency graph from the workspace.

4. Match skills to dependencies — for each plugin, parse SKILL.md YAML frontmatter, reject malformed or non-string metadata, warn about skipped invalid skills, then evaluate skill group dependency predicates and individual skill depends-on frontmatter against the workspace dependencies.

5. Install skills per agent — for each configured agent:

   • Copy applicable SKILL.md files into the agent’s expected skill directory.
   • Drop a .symposium marker file into each installed skill directory so future syncs (and other tools) can recognize it as symposium-managed.
   • For every skill directory symposium creates along the way (the skill directory itself or its skills/ parent), write a .gitignore containing a single * so symposium-managed files stay out of version control.

6. Workspace .agents/skills/ (agents-syncing) — not a separate step: when agents-syncing is enabled, each workspace plugin carries a workspace-member()-gated default group for .agents/skills/, so maintainer skills resolve and install through the same pipeline as everything else. Two marker guards make .agents/skills/ safe as both a source and (for vendor-neutral agents) a destination: discovery skips .symposium-marked directories (installed copies are never sources), and a skill whose source already sits at an agent’s install slot is skipped for that agent (no self-copy, no suffixed duplicate).

7. Reap stale skills — across every known agent’s skills parent directory, remove any subdirectory that contains the .symposium marker but wasn’t installed this sync. Directories without the marker (user-managed) are left untouched.

   While a registry cannot be read, this step is skipped and a warning names the registry: it offered nothing this time, so everything it installed would look stale.

8. Register hooks — ensure symposium’s global hook handler and MCP servers are registered for all configured agents. Unregister hooks for agents no longer in the config. Only symposium’s own handler is registered (e.g., cargo-agents hook claude pre-tool-use) — individual plugin hooks are never written into agent configs. See Hooks for the dispatch model.

Marker file

Each skill directory symposium installs contains an empty .symposium file. Cleanup walks every agent’s skills parent directory (.claude/skills/, .agents/skills/, .kiro/skills/) and reaps any subdirectory whose marker is present but which wasn’t installed this sync. This lets symposium reclaim stale skills (including those left behind by agents removed from the config) without touching user-managed skills, which are identified by the absence of the marker.

Gitignore

Each skill directory symposium creates (and its skills/ parent if new) receives a .gitignore containing just *. Pre-existing directories are left alone. The wildcard also hides the marker file and the gitignore itself, so git status stays clean.

Auto-sync

When auto-sync = true is set in the user config, the hook handler runs sync automatically during agent sessions. This keeps skills in sync as dependencies change.

On most hook events, auto-sync is gated on Cargo.lock (and battery-pack.toml) mtime via per-workspace state, so an unchanged workspace doesn’t pay for cargo metadata on every event. SessionStart is the exception: it runs once per session, ignores that gate, and passes UpdateLevel::Check down through skill resolution so source.git skill groups are re-fetched when their upstream moved. This is what makes upstream skill updates land even when the workspace’s own dependencies haven’t changed. sync takes the UpdateLevel as a parameter; the binary’s global --update flag threads through the same path for manual cargo agents sync.

cargo agents hook

Entry point invoked by the agent’s hook system on session events.

Flow

The payload is parsed first, and the agent’s parser can declare it not an occurrence of the symposium event (AgentHookInput::should_dispatch; false for an Antigravity PreInvocation after the first of a turn). Such a payload is answered with the agent’s neutral output and skips every step below.

1. Auto-sync (if enabled) — when auto-sync = true in the user config, runs cargo agents sync to ensure skills are current. The workspace root is resolved from the payload’s cwd field; if the payload does not include a working directory, the process’s current working directory is used as a fallback. Runs quietly and non-fatally — failures are logged but don’t block hook dispatch.

   SessionStart is the refresh point. Because it fires once per agent session, it does the expensive work that other events skip: it bypasses the Cargo.lock freshness gate (so skills re-sync even when the workspace’s dependencies are unchanged) and passes UpdateLevel::Check so git registries and source.git skill groups are re-fetched if their upstream moved. Every other event keeps the cheap, Cargo.lock-gated path with UpdateLevel::None (debounced) to avoid per-event network and cargo metadata cost. The registry refresh on SessionStart (ensure_registries with Check, decided in the binary entry point from the event) still honors each registry’s auto-update toggle. SessionStart also runs prewarm_hook_sources, which refreshes already-installed hook binaries/scripts (the cargo/github sources backing plugin hooks) — refresh-only, so it never eagerly installs a tool a hook may never use; first install still happens lazily at dispatch.

2. Built-in dispatch — symposium’s own handling, before plugin hooks. PreToolUse produces nothing. On SessionStart three fragments are computed independently and, when present, joined into one additionalContext:

   • Discovery hint — when the active workspace exposes plugin-vended subcommands (the same workspace-filtered set listed by cargo agents --help), a line suggesting the agent run cargo agents --help to find them. Computed independently of the update-check throttle, so it fires whenever there is something to discover.
   • Consent hint: the dependency plugins awaiting consent, telling the agent to point the user at cargo agents sync or cargo agents use.
   • Update nudge — when auto-update = "warn", the 24-hour check throttle has elapsed, and the registry reports a newer version: a line suggesting cargo agents self-update.

   On PostToolUse and UserPromptSubmit, when auto-sync just re-synced because Cargo.lock changed, a generic notice says there may be new plugins and points at cargo agents sync. That is right after a tool call that changed the dependencies, or the user’s next prompt when they changed them. run_auto_sync returns that as a bool, so an event with an unchanged Cargo.lock does no extra work. The notice is lost when the agent ignores context on that event (Antigravity after a tool call), or when the change is first seen on PreToolUse or Stop, which sync but carry no notice.

   Agents without hook registration (OpenCode, Goose) never receive this; for them the only discovery surface is cargo agents --help itself.

3. Dispatch to plugin hooks — for each enabled plugin that defines a hook handler for the incoming event:

   • Select format: for each plugin, pick the best hook to deliver (see Hooks for priority rules). If the plugin has a hook matching the current agent’s format, deliver the input unmodified. Otherwise deliver in symposium canonical format (or convert to the declared format if only one non-symposium hook exists).
   • Acquire and run:
     • Ensure any requirements for the hook are acquired (on-demand, best-effort).
     • Resolve the hook’s command (a named installation reference or inline declaration) into a runnable form:
       • If the installation declares a source, acquire it (install / cache / clone) and resolve the executable / script against the cached location. Dispatch acquires with UpdateLevel::None — it serves the cache (git checks debounced) rather than hitting the network on every event. Freshness comes from the SessionStart prewarm (step 1), which re-acquires every applicable hook’s source with Check once per session.
       • If no source, the executable / script is taken as a path on disk (relative paths resolve against the plugin directory, so a refreshed plugin-source repo updates these for free).
       • Run the installation’s install_commands (post-source) before invoking the runnable.
       • Spawn path args… directly for Exec, or sh path args… for Script.
     • Pass the event JSON (in the selected format) on stdin to the plugin’s hook.
     • Collect output from each handler.
     • Convert output back to the agent’s wire format.
     • Merge results (e.g., allow/block decisions, output text) across all handlers. merge lets a later value replace an earlier one, so on SessionStart, UserPromptSubmit and PostToolUse a JoinedContext keeps every source’s context (the builtin fragments first, then each hook) and writes the joined text back after each merge. PreToolUse and Stop are left out: there some agents keep context in the field that holds the decision.
     • Return the merged result to the agent.
   • A hook that exits 2 blocks: dispatch stops, and blocked_response turns its stderr into the reason. On PreToolUse that is a canonical deny, translated like any other so each agent receives it in the form it honors (Antigravity ignores exit codes, Copilot drops the reason of a failing hook). On other events the process exits 2 with the reason on stderr.

4. Respond: the agent’s handler renders the final output as a HookResponse (stdout, stderr, exit code). Most agents read everything from stdout; Kiro, whose stdout is plain context, is told to deny a tool through exit 2.

Plugin hooks can respond to agent-specific events (e.g., pre-tool-use, post-tool-use, user-prompt-submit for Claude Code). The available events depend on which agent is in use.

Running tests

Quick start

cargo test              # simulation + configured agents

By default, cargo test runs simulation tests and then re-runs agent-mode tests against each agent listed in test-agents.toml. On a fresh clone (no file), the defaults are claude-sdk and kiro-cli-acp.

Configuring test agents

Create test-agents.toml in the repo root (gitignored):

# Run against these agents. Use `acpr --list` to see ACP registry agents.
test-agents = ["claude-sdk"]

Set to [] to skip agent tests entirely (used in CI):

test-agents = []

Available agent names:

Filtering to a single agent

Override with the SYMPOSIUM_TEST_AGENT env var:

SYMPOSIUM_TEST_AGENT=kiro-cli-acp cargo test --test hook_agent

This ignores test-agents.toml and runs only the specified agent.

Running specific test files

cargo test --test hook_agent       # just the agent integration tests
cargo test --test init_sync        # just the init/sync tests
cargo test --test dispatch         # just the CLI dispatch tests

Debugging test failures

Add --nocapture to see test output (agent messages, hook traces):

cargo test --test hook_agent -- --nocapture

On failure, the test’s temporary directory is preserved and its path is printed to stderr so you can inspect the fixture state.

Windows

CI runs the full test suite on windows-latest as part of the test matrix (see .github/workflows/ci.yml). To run the tests locally on Windows:

• Install Git for Windows and make sure sh is on PATH. Git ships it at C:\Program Files\Git\usr\bin. Several tests spawn sh to run script-based hooks and predicates, so a missing sh shows up as unrelated-looking hook failures.
• The repo’s .gitattributes normalizes checked-out text files to LF. This keeps shebang’d fixtures and shell scripts runnable regardless of core.autocrlf.

The self-update tests run on Windows: set_mock_cargo runs the #!/bin/sh mock through sh via a one-line .cmd shim (production spawns the cargo override directly, so no production code changes). The two auto_update_re_execs_* tests are #[ignore]d on Windows (#[cfg_attr(windows, ignore)]): they overwrite the running binary with a shebang stand-in and re-exec into it, which needs Windows-native process replacement. They still compile on Windows, so they are skipped (not compiled out) and their helpers need no #[cfg]. Porting them to run on Windows is a tracked follow-up.

Writing tests

Symposium tests run in two modes:

• Simulation mode — hooks and CLI calls are invoked directly by the harness. No real agent needed.
• Agent mode — a real agent session processes prompts and we verify it triggers the expected hooks.

Tests declare which mode they need via TestMode:

• TestMode::SimulationOnly — runs once in simulation.
• TestMode::AgentOnly — runs once per configured test agent.
• TestMode::Any — runs once in simulation + once per configured agent.

1. Create your setup by composing fixtures

Wrap your test in with_fixture, specifying the mode and fixtures:

#![allow(unused)]
fn main() {
use symposium_testlib::{TestMode, with_fixture};

#[tokio::test]
async fn my_test() {
    with_fixture(TestMode::SimulationOnly, &["plugins0"], async |mut ctx| {
        // test body
        Ok(())
    }).await.unwrap();
}
}

Fixtures are directories under tests/fixtures/. They are overlaid into a tempdir:

#![allow(unused)]
fn main() {
with_fixture(TestMode::SimulationOnly, &["plugins0", "workspace0"], async |mut ctx| { ... })
}