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
symposium 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 symposium 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, you also want to install it into your project. When you run cargo agents init in a project directory, it will scan your dependencies and create customized skills, tools, and other improvements. These extensions are source either from our central recommendations repository. In the future, we plan to enable crate authors to embed extensions within their crates themselves and skip the central repo altogether.

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!

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

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 (Claude Code, Copilot, Gemini, etc.) — you can pick more than one:

Which agents do you use? (space to select, enter to confirm):
> [ ] Claude Code
  [x] Codex CLI
  [ ] GitHub Copilot
  [ ] Gemini CLI
  [ ] 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.

Currently all the plugins installed by Symposium can be found in the central recommendations repository. We expect eventually to allow crates to define their own plugins without any central repository, but not yet. 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.

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.

Git repository

Add a remote Git repository as a plugin source:

# In ~/.symposium/config.toml
[[plugin-source]]
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 plugin source:

[[plugin-source]]
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 operatons on the installed plugin sources, like synchronizing their contents or validating their structure.

Supporting your crate

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.

Just want to add a skill?

If all you need is to publish guidance for your crate, you don’t need to set up a plugin. Just write a SKILL.md with a few lines of frontmatter (name, description, which crate it’s for) and a markdown body, then open a PR to the symposium-dev/recommendations repository.

See Publishing skills for the details.

Moar power!

There are three kinds of extensions you can publish:

• Skills — guidance documents that AI assistants receive automatically when a user’s project depends on your crate.
• 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.

See Creating a plugin for how to set one up.

Publishing skills

Skills are guidance documents that teach AI assistants how to use your crate. When a user’s project depends on your crate, Symposium loads your skills automatically.

Background: what is a skill

As defined on agentskills.io, a skill is a directory that contains a SKILL.md file, along with potentially other content. The SKILL.md file defines metadata to help the agent decide when the skill should be activated; activating the skill reads the rest of the file into context.

Define the target crates for a skill with crates frontmatter

Symposium extends the Skill frontmatter with one additional field, crates. This field specifies a predicate indicating the crates that the skill applies to; this predicate can also specify versions of the create, if that is relevant:

---
name: widgetlib-basics
description: Basic guidance for widgetlib usage
crates: widgetlib
---

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

The crates: widgetlib in this example says that this skill should be installed in any project that depends on any version of widgetlib.

If you wanted to limit your skill to v2.x of widgetlib, you could write this:

crates: widgetlib=2.0

You can read more about crate predicates in the plugin documentation.

Publishing skills

You can publish skills for your crate in two ways:

• You can upload standalone skill directories directly into the symposium-dev/recommendations, as described below (you can also publish them to a custom plugin source in the same fashion).
• Or, you can create a plugin, which is a TOML file that defines where to find skills, MCP servers, etc. In this case, the skills can be hosted either on the central recommendations repository or on your own repositorys. See the creating a plugin chapter for more details.

Example: publishing 3 standalone skills for widgetlib

As an example, consider a hypothetical crate widgetlib that wishes to post 3 standalone skills into the central repository. These skills support using widgetlib 1.x, widgetlib 2.x (which is quite different), and how to upgrade from 1.x to 2.x (which is nontrivial).

To do this, you would add the following directories to the recommendations repo or your own custom plugin source:

widgetlib/
    1x-basics/
        SKILL.md, containing:
           ---
           name: widgetlib-1x-basics
           description: How to use widgetlib 1.x
           crates: widgetlib=1.0
           ---
    2x-basics/
        SKILL.md, containing:
           ---
           name: widgetlib-2x-basics
           description: How to use widgetlib 2.x
           crates: widgetlib=2.0
           ---
    upgrade-1x-to-2x/
        SKILL.md, containing:
           ---
           name: widgetlib-upgrade-1x-to-2x
           description: How to upgrade from widgetlib 1.x to 2.x
           crates: widgetlib=1.0
           ---

Each skill uses crates to limit itself to specific versions.

Reference: common skill frontmatter fields

See the Skill definition reference for the full format, the Crate predicates reference for version constraint syntax, and the agentskills.io quickstart for general guidance on writing effective skills.

Creating a plugin

A symposium plugin collects together all the extensions offered for a particular crate. Plugins can references skills, hooks, MCP servers, and other things that are relevant to your crate. These extensions can be packaged up as part of the plugin or the plugin can contain pointers to external repositories; the latter is often easier to update in a centralized fashion.

Plugins are needed when you want to add mechanisms beyond skills, like hooks or MCP servers. If all you want to do is upload a skill, you can publish a standalone skill instead.

Plugin structure

A plugin is structured as a directory that contains a SYMPOSIUM.toml manifest file:

my-crate-plugin/
    SYMPOSIUM.toml
    ... // potentially other stuff here

The SYMPOSIUM.toml plugin manifest has these main sections:

name = "my-crate-plugin"

# The `crates` field defines when the plugin applies. Use the special `crates = ["*"]` form to write a plugin that ALWAYS applies.
crates = ["my-crate"]

# Skills grouped by crate and version.  Skills can be located as a reference to another git repository.
[[skills]]
crates = ["my-crate=2.0"]
source.git = "https://github.com/org/my-crate/tree/main/skills/v2"

# Skills can also be located by a path within the plugin itself.
[[skills]]
crates = ["my-crate=1.0"]
source.path = "skills/v1"

# Hooks for agent event callbacks
[[hooks]]
name = "validate-usage"
event = "PreToolUse"
command = "./scripts/validate.sh"

# MCP servers for tool integration
[[mcp-servers]]
name = "my-crate-tools"
command = ["my-crate-mcp-server"]

Publishing plugins

The most common way to publish a plugin is to upload the plugin directory to our central recommendations repository. If you do this, we recommend keeping your skills and other resources in your own github repo, so that you can update them without updating the central repository.

We expect in the future to make it possible to add plugins directly into your crate definition, but that is not currently possible.

Plugins can also be added to a custom plugin source. This is useful when you are defining rules for crates specific to your company or customized plugins that are tailored to the way that your project uses a crate. In this case, it’s often convenient to package up the skills, MCP servers, etc together with the plugin.

Example: plugin for widgetlib with remote skills

Consider a widgetlib crate that wants to keep skills in its own repository but still be discoverable through Symposium.

This would be done by first uploading a plugin to the symposium-dev/recommendations repository:

widgetlib/
    SYMPOSIUM.toml

This SYMPOSIUM.toml file would list out the skills as pointers to a remote repository. In this case, let’s say there are two groups of skills, one for v1.x and one for v2.x, and those skills are hosted on the repo widgetlib/skills:

name = "widgetlib"

[[skills]]
crates = ["widgetlib=1.0"]
source.git = "https://github.com/widgetlib/skills/tree/main/symposium/skills/v1"

[[skills]]
crates = ["widgetlib=2.0"]
source.git = "https://github.com/widgetlib/skills/tree/main/symposium/skills/v2"

In this example, the crates criteria is placed on the skill groups. This is because the skill groups have distinct versions. If there were a crates declaraton at the top-level, then both the plugin crates definition and the skills definition must match (in addition to any crates: defined in the skill metadata!).

The widgetlib/skills repo then would look like this:

v1/
    basics/
        SKILL.md
v2/
    basics/
        SKILL.md
    migration/
        SKILL.md

Given this setup, each time a new commit is pushed to widgetlib/skills, users’ skills will automatically be updated to match.

Details on how to define a plugin

See the reference for the precise specification of what is allowed in a plugin definition. This includes the details of how to define other plugin content beyond skills, such as hooks and MCP servers.

Validation and testing

You can test that a plugin directory has the correct structure using the cargo agents CLI:

# Validate your plugin manifest
cargo agents plugin validate path/to/SYMPOSIUM.toml

# Check that crate names exist on crates.io
cargo agents plugin validate path/to/SYMPOSIUM.toml --check-crates

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

cargo agents init

Set up Symposium for the current user.

Usage

cargo agents init [OPTIONS]

Behavior

Prompts for which agents you use (e.g., Claude Code, Copilot, Gemini) 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 gemini

Adding an agent to an existing config:

cargo agents init --add-agent copilot

Removing an agent:

cargo agents init --remove-agent gemini

cargo agents sync

Synchronize skills with workspace dependencies.

Usage

cargo agents sync

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 Copilot/Gemini/Codex).

5. Clean up stale skills — removes skills that were previously installed by symposium but are no longer applicable (e.g., because a dependency was removed). Tracks installed skills in a per-agent manifest (.symposium.toml in the agent’s skill directory). Skills not in the manifest (user-managed) are left untouched.

6. Register hooks — ensures hooks and MCP servers are registered for all configured agents. Registers both global hooks (for all projects) and project-specific hooks (for the current project). Unregisters hooks for agents no longer in the config.

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 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 details for a specific plugin, including its TOML configuration and source file path.

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.

Unstable agent commands

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

cargo agents crate-info

Find crate sources and guidance.

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 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.

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.

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 (PascalCase).

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

MCP servers

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 global config.

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).

MCP servers

Gemini CLI

Config name: gemini

Skills

Hooks

Symposium merges hook entries into Gemini’s settings.json.

Events registered: BeforeTool, AfterTool, BeforeAgent, SessionStart (Gemini’s own naming).

Output format: JSON with nested matcher groups. Timeouts in milliseconds.

MCP servers

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 hooks are experimental and disabled by default. To enable, add to ~/.codex/config.toml:

[features]
codex_hooks = true

MCP servers

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/Gemini/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

Configuration

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

Full example

auto-sync = true
hook-scope = "global"

[[agent]]
name = "claude"

[[agent]]
name = "gemini"

[logging]
level = "info"

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

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

[[plugin-source]]
name = "local-dev"
path = "my-plugins"

Top-level keys

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]

[defaults]

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

[[plugin-source]]

Defines additional plugin sources. Each entry must have exactly one of git or path.

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 is a directory or repository containing plugins and standalone skills that Symposium discovers automatically. Plugin sources can be local directories or remote Git repositories, and Symposium searches them recursively to find all available extensions.

Discovery rules

Symposium scans a plugin source recursively to find plugins and standalone skills:

• A plugin is a directory that contains a SYMPOSIUM.toml file;
• A standalone skill is a directory that contains a SKILL.md and does not contain a SYMPOSIUM.toml file. Standalone skills must have crates metadata in their frontmatter.

We do not allow plugins or standalone skills 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.

Example structure

plugin-source/
  my-plugin/
    SYMPOSIUM.toml        # ✓ Plugin
    skills/               # ✗ Not searched (parent claimed)
      basic/
        SKILL.md
  serde-skill/
    SKILL.md              # ✓ Standalone skill
  nested/
    deep/
      tokio-skill/
        SKILL.md          # ✓ Standalone skill (found recursively)
  mixed/
    SYMPOSIUM.toml        # ✓ Treated as plugin
    SKILL.md              # ✗ Ignored (plugin takes precedence)

Configuration

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

Validation

You can validate a plugin source directory:

# Validate all plugins and skills in a directory
cargo agents plugin validate path/to/plugin-source/

# Also verify that crate names exist on crates.io (on by default; use --no-check-crates to skip)
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 standalone skills 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"
crates = ["*"]

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

Top-level fields

Note: Every plugin must specify crates somewhere — either at the plugin level, in [[skills]] groups, or in [[mcp_servers]] entries. Plugins without any crate targeting will fail validation.

Plugin-level filtering

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

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

# OR use wildcard to always apply
crates = ["*"]

If omitted, the plugin applies to all projects. 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.

[[hooks]]

Each [[hooks]] entry declares a hook that responds to agent events.

Supported hook events

Agent → hook name mapping

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) — treated as a failure: dispatch stops immediately and the hook’s stderr is returned to the caller.
  • 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.

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

Testing hooks

Use the CLI to test a hook with sample input:

echo '{"tool": "Bash", "input": "cargo test"}' | cargo agents hook claude pre-tool-use

You can also use copilot, gemini, codex, or kiro as the agent name.

[[mcp_servers]]

Each [[mcp_servers]] entry declares an MCP server that Symposium registers into the agent’s configuration during sync --agent.

There are multiple MCP transports:

Stdio

[[mcp_servers]]
name = "my-server"
command = "/usr/local/bin/my-server"
args = ["--stdio"]
env = []

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 --agent, each MCP server entry is written into the 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.

Example: full manifest

name = "widgetlib"

[[skills]]
crates = ["widgetlib=1.0"]
source.path = "skills/general"

[[skills]]
crates = ["widgetlib=1.0"]
source.git = "https://github.com/org/widgetlib/tree/main/symposium/serde-skills"

[[hooks]]
name = "check-widget-usage"
event = "PreToolUse"
matcher = "Bash"
command = "./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. Crate name checking against crates.io is on by default; use --no-check-crates to skip it.

Skill definitions

A skill is a SKILL.md file inside a skill directory. Skills follow the agentskills.io format.

Directory layout

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

SKILL.md format

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

---
name: serde-basics
description: Basic guidance for serde usage
crates: serde
---

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

Frontmatter fields

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

See Crate predicates for the full syntax.

Scope composition

crates 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 crates narrows the group’s scope — it does not widen it.

Crate predicates

Crate predicates control when plugins, skill groups, and individual skills are active. A predicate matches against a workspace’s direct dependency set — not against individual crates in isolation.

Predicate syntax

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

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

Usage in different contexts

Plugin manifests (TOML)

The crates field accepts an array of predicate strings:

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

Skill frontmatter (YAML)

The crates field uses comma-separated values:

• crates: serde
• crates: serde, tokio>=1.40

Matching behavior

A crates list matches if at least one predicate in the list matches the workspace. The wildcard * always matches — even a workspace with zero dependencies.

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

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

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 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

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. Crate authors submit skills and plugin manifests here. Symposium fetches this as a plugin source 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.

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.

Defines the user-wide Config (stored at ~/.symposium/config.toml) with [[agent]] entries, logging, plugin sources, and defaults. Provides plugin_sources() to resolve the effective list of plugin source directories.

agents.rs — agent abstraction

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

init.rs — initialization command

Implements cargo agents init. Prompts for agents (or accepts --add-agent/--remove-agent flags), writes user config, and registers global hooks.

sync.rs — synchronization command

Implements cargo agents sync. Scans workspace dependencies, finds applicable skills from plugin sources, installs them into each configured agent’s skill directory, manages a per-agent .symposium.toml manifest to track installed skills, and cleans up stale skills. Also provides register_hooks() for use by init.

plugins.rs — plugin registry

Scans configured plugin source directories for TOML manifests and parses them into Plugin structs. Each plugin contains SkillGroups (which crates, where to find the skills) and Hooks (event handlers). Also discovers standalone SKILL.md files not wrapped in a plugin. Returns a PluginRegistry — a table of contents that doesn’t load skill content.

skills.rs — skill resolution and matching

Given a PluginRegistry and workspace dependencies, this module resolves skill group sources (fetching from git if needed), discovers SKILL.md files, and evaluates crate predicates at each level (plugin, group, skill) to determine which skills apply.

hook.rs — hook handling

Handles the hook pipeline: parse agent wire-format input → auto-sync → builtin dispatch → plugin hook dispatch → serialize output. When auto-sync is enabled, runs sync as a side effect during hook invocations. Plugin hooks are spawned as shell commands with format routing between agent wire formats and the symposium canonical format.

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.

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. 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 Copilot, Gemini, 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. The ones relevant to Symposium are:

Other events include SessionStart, Stop, 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".

Gemini CLI

Hooks reference · Configuration reference · Skills reference · Extensions reference

Hook registration

Gemini CLI hooks live under the "hooks" key in settings.json. Hook groups use regex matchers for tool events and exact-string matchers for lifecycle events.

Example hook registration:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "name": "symposium",
            "type": "command",
            "command": "cargo-agents hook gemini pre-tool-use",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Note: Gemini uses BeforeTool (not PreToolUse), and timeouts are in milliseconds (default: 60000).

Supported events

Hook payload/output

Gemini uses a structure similar to Claude Code, with a nested hookSpecificOutput:

{
  "decision": "allow",
  "reason": "...",
  "hookSpecificOutput": {
    "hookEventName": "BeforeTool",
    "additionalContext": "...",
    "tool_input": { ... }
  }
}

The input payload includes tool_name, tool_input, mcp_context, session_id, and transcript_path.

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.

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.

Session state

Session state (activations, nudge history, prompt count) is persisted as JSON files at ~/.symposium/sessions/<session-id>.json, so state survives across hook invocations within a single coding session.

Hooks

Important flows

This section describes the logic of each cargo agents command.

cargo agents init

Sets up the user-wide configuration.

Flow

1. Prompt for agents — ask which agents the user uses (e.g., Claude Code, Copilot, Gemini). Multiple agents can be selected.

2. Write user config — create ~/.symposium/config.toml with the [[agent]] entries populated:

   [[agent]]
   name = "claude"
   
   [[agent]]
   name = "gemini"
   

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

1. Find workspace root — run cargo metadata to locate the workspace manifest directory.

2. Load plugin sources — read the user config’s [[plugin-source]] entries and load their plugin manifests. For git sources, fetch/update as needed.

3. Scan dependencies — read the full dependency graph from the workspace.

4. Match skills to dependencies — for each plugin, evaluate skill group crate predicates and individual skill crates 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.
   • Write a .symposium.toml manifest in the agent’s skill directory tracking which skills were installed by symposium.
   • Remove skills that are in the old manifest but no longer applicable.
   • Leave skills not in the manifest (user-managed) untouched.

6. Register hooks — ensure global hooks and MCP servers are registered for all configured agents. Unregister hooks for agents no longer in the config.

Skill manifest

Each agent’s skill directory contains a .symposium.toml file tracking what symposium installed:

installed = [
    "serde-guidance",
    "tokio-guidance",
]

This allows symposium to clean up stale skills without touching user-managed skill files.

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.

cargo agents hook

Entry point invoked by the agent’s hook system on session events.

Flow

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.

2. Dispatch to plugin hooks — for each enabled plugin that defines a hook handler for the incoming event:

   • Pass the event JSON on stdin to the plugin’s hook command.
   • Collect output from each handler.
   • Merge results (e.g., allow/block decisions, output text) across all handlers.
   • Return the merged result to the agent.

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.

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| { ... })
}

with_fixture scans fixtures for config.toml (user config dir) and Cargo.toml (workspace root). In agent mode it automatically runs init --add-agent and sync.

For TestMode::Any and TestMode::AgentOnly, the test closure runs once per configured agent.

Variable expansion in fixtures

Text files have variables expanded when copied:

• $TEST_DIR — the tempdir root.
• $BINARY — path to the cargo-agents binary.

Fixture requirements

All fixture config.toml files must include hook-scope = "project" so that hooks are installed into the project directory rather than globally.

2. Write the test body

Bimodal tests (TestMode::Any)

Use ctx.prompt_or_hook which dispatches based on mode:

#![allow(unused)]
fn main() {
with_fixture(TestMode::Any, &["plugins0", "project-plugins0"], async |mut ctx| {
    let result = ctx
        .prompt_or_hook("Say hello", &[HookStep::session_start()], HookAgent::Claude)
        .await?;

    assert!(!result.hooks.is_empty());
    assert!(result.has_context_containing("symposium start"));
    Ok(())
}).await.unwrap();
}

In agent mode, prompt_or_hook also asserts that the expected hook events appear in the trace.

Agent-only tests (TestMode::AgentOnly)

Use ctx.prompt to send prompts to the real agent:

#![allow(unused)]
fn main() {
with_fixture(TestMode::AgentOnly, &["plugin-tokio-weather0", "workspace-empty0"], async |mut ctx| {
    ctx.prompt("Run `cargo add tokio` please!").await?;
    let result = ctx.prompt("Use the tokio-weather skill to answer: ...").await?;
    assert!(result.response.unwrap().contains("MAGIC SENTENCE"));
    Ok(())
}).await.unwrap();
}

Simulation-only tests (TestMode::SimulationOnly)

Use ctx.symposium to invoke the CLI directly:

#![allow(unused)]
fn main() {
with_fixture(TestMode::SimulationOnly, &["plugins0"], async |mut ctx| {
    ctx.symposium(&["init", "--add-agent", "claude"]).await?;
    ctx.symposium(&["sync"]).await?;
    // assert on files...
    Ok(())
}).await.unwrap();
}

Governance

Symposium operates under the Rust Code of Conduct.

Teams

When a contributor has shown enduring interest in the codebase and made multiple non-trivial changes over time, they are invited to join the Symposium maintainers team:

• Maintainers team —
  • Members of this team can review and merge other PRs.
  • Members are expected to attend the regular sync meeting.

Overall project leadership is provided by the core team:

• Core team —
  • Final decision makers
  • Approve releases
  • All members of the core team are also members of the maintainers team

Decisions proceed by consensus at each level; if needed, @nikomatsakis acts as BDFL to resolve contentious questions.

PR disclosure policy

We request PRs answer the questions in our PR template regarding AI use, confidence level, and questions.

PR merge policy

We want to keep moving quickly, especially in this early phase, therefore we have established the following review policy:

Sync meeting

We hold a regular sync meeting to discuss recent changes, plans, and direction. The meeting is open to all maintainers and contributors. If you’re interested in attending, reach out to a core team member on Zulip.

Releases

Merging a release PR is coordinated among core team members.

Getting involved

The best way to get started is to pick up an issue, open a PR, and join the conversation on Zulip. Landing non-trivial contributions and attending the sync meeting is the path to joining the devs team.

Common issues

Known hook implementation gaps

The following issues were identified by auditing our hook implementations against the agent reference docs (md/design/agent-details/). They don’t cause crashes (the fallback path handles events without agent-specific handlers) but mean some features are incomplete.

updatedInput type mismatch (Claude Code)

HookSpecificOutput.updated_input and Claude’s ClaudeHookSpecificOutput.updated_input are typed as Option<String>, but per the Claude Code reference, updatedInput is a JSON object (e.g., {"command": "safe-cmd"}). Should be Option<serde_json::Value>.

toolArgs not parsed (Copilot)

Copilot sends toolArgs as a JSON string (not an object). Our CopilotPreToolUsePayload declares it as serde_json::Value and passes it through as-is in to_hook_payload(). Downstream code expecting structured tool args will get a raw string. Should parse the JSON string into a Value during conversion.

permissionDecision dropped (Copilot)

CopilotPreToolUseOutput::from_hook_output() never maps permissionDecision or permissionDecisionReason from the builtin hook output. If a builtin handler wants to deny a tool call, the decision is silently lost in Copilot output.

Gemini SessionStart matcher

ensure_gemini_hook_entry uses "matcher": ".*" for all events including SessionStart. Per the Gemini reference, lifecycle events use exact-string matchers, not regex. Likely harmless in practice since ".*" matches anything.

Agent details

Disclaimer: These documents reflect our current understanding of each agent’s hook system and extensibility surface. They are maintained as working references for symposium development, not as a substitute for each project’s official documentation. Details may be outdated or incomplete — always consult the primary sources linked in each agent’s page.

For each agent it supports, symposium needs to know:

1. Hook registration — where and how to write config so the agent calls cargo-agents hook
2. Hook I/O protocol — event names, input/output field names, exit code semantics
3. Extension installation — where skill files go (project and global)
4. Custom instructions — where the agent reads project-level instructions

The tables below summarize the answers for each agent. Individual agent pages contain the full reference. A ? indicates information we have not yet documented.

Hook registration

Command field

Timeout defaults

Event names

Symposium registers hooks for four events. Each agent uses different names and casing conventions.

Blocking support

Not all events can block the action in all agents.

Hook I/O protocol

Input fields (pre-tool-use)

Output structure (pre-tool-use)

Exit codes

All shell-based agents use the same convention (where applicable):

Exceptions: Copilot uses exit 0 = allow, non-zero = deny (no special meaning for exit 2). OpenCode uses JS exceptions, not exit codes.

Extension installation

Skill file paths

Symposium uses the vendor-neutral .agents/skills/ path whenever the agent supports it, falling back to agent-specific paths (e.g., .claude/skills/, .kiro/skills/) when required. Codex CLI and OpenCode also support .agents/skills/ natively.

Custom instructions

MCP server configuration

Relevant if symposium exposes functionality via MCP.

Claude Code Hooks Reference

Disclaimer: This document reflects our current understanding of Claude Code’s hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: Hooks reference · Hooks guide · Extending Claude Code

Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute at specific points in the agent lifecycle. They provide deterministic control — actions always happen rather than relying on the model.

Hook Types

Events

Configuration

Settings merge with precedence (highest first): Managed → Command line → Local → Project → User.

Configuration structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./validate.sh",
            "if": "Bash(rm *)",
            "timeout": 60,
            "statusMessage": "Validating...",
            "async": false,
            "shell": "bash"
          }
        ]
      }
    ]
  }
}

• matcher: regex matched against event-specific values (tool name, session source, notification type).
• if: permission-rule syntax for additional filtering on tool events (e.g., Bash(git *), Edit(*.ts)).

Input Schema (stdin)

Base fields (all events)

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "default|plan|auto|bypassPermissions|...",
  "hook_event_name": "string"
}

PreToolUse additions

• tool_name: string
• tool_input: object with tool-specific fields (command for Bash, file_path/content for Write, etc.)
• tool_use_id: string

PostToolUse additions

• tool_name, tool_input, tool_use_id (same as PreToolUse)
• tool_response: string (tool output)

Stop additions

• stop_hook_active: boolean
• last_assistant_message: string

Output Schema (stdout)

Output is capped at 10,000 characters.

Universal fields

PreToolUse decision output

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask|defer",
    "permissionDecisionReason": "string",
    "updatedInput": { "command": "safe-cmd" },
    "additionalContext": "string"
  }
}

Decision precedence across parallel hooks: deny > defer > ask > allow. The allow decision does not override deny rules from settings. updatedInput replaces the entire tool input; if multiple hooks return it, the last to finish wins (non-deterministic).

Exit Codes

Execution Behavior

• All matching hooks run in parallel.
• Identical handlers deduplicated by command string or URL.
• Default timeouts: 600s (command), 30s (prompt), 60s (agent), 1.5s (SessionEnd, overridable via CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS).

Environment Variables

Enterprise Controls

• allowManagedHooksOnly: true — blocks user/project/plugin hooks.
• allowedHttpHookUrls — restricts HTTP hook destinations.
• disableAllHooks: true — disables everything.
• PreToolUse deny blocks even in bypassPermissions mode.

MCP Server Registration

In addition to hooks, symposium registers itself as an MCP server in the agent’s settings file. This provides an alternative integration path alongside the hook-based approach.

Configuration structure

The MCP server entry is added under mcpServers in the same settings file used for hooks:

{
  "mcpServers": {
    "symposium": {
      "command": "/path/to/cargo-agents",
      "args": ["mcp"]
    }
  }
}

• Project-level: .claude/settings.json
• User-level: ~/.claude/settings.json

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.

GitHub Copilot Hooks Reference

Disclaimer: This document reflects our current understanding of GitHub Copilot’s hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: About hooks · Using hooks · Hooks configuration

GitHub Copilot hooks are available for the Cloud Agent (coding agent), Copilot CLI (GA February 2026), and VS Code (8-event preview). The system is command-only and repository-native.

Hook Types

Only type: "command" is supported.

Events

Cloud Agent and CLI (6 events, lowerCamelCase)

VS Code (8 events, PascalCase, preview)

SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop.

Only preToolUse/PreToolUse can make access-control decisions. All other events are observational.

Configuration

Cloud Agent and CLI

Hooks defined in .github/hooks/*.json. For the Cloud Agent, files must be on the repository’s default branch.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "env": { "LOG_LEVEL": "INFO" },
        "timeoutSec": 15,
        "comment": "Documentation string, ignored at runtime"
      }
    ]
  }
}

There is no matcher field — hooks fire on all invocations of their event type. Tool-level filtering must be done inside the script by inspecting toolName from stdin.

VS Code

Also reads hooks from .claude/settings.json, .claude/settings.local.json, and ~/.claude/settings.json (Claude Code format compatibility). Converts lowerCamelCase to PascalCase and maps bash→osx/linux, powershell→windows.

Input Schema (stdin)

preToolUse

{
  "timestamp": 1704614600000,
  "cwd": "/path/to/project",
  "toolName": "bash",
  "toolArgs": "{\"command\":\"rm -rf dist\",\"description\":\"Clean build\"}"
}

Note: toolArgs is a JSON string, not an object. Scripts must parse it (e.g., with jq).

sessionStart

• source: "new" | "resume"
• initialPrompt: string

sessionEnd

• reason: string

Output Schema (stdout)

preToolUse output (Cloud Agent / CLI)

{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Destructive operations blocked"
}

Exit code 0 = allow (if no JSON output), non-zero = deny.

VS Code output (preview, extended fields)

Execution Behavior

• Hooks run synchronously and sequentially (array order).
• If the first hook returns deny, subsequent hooks are skipped.
• Recommended execution time: under 5 seconds.
• Default timeout: 30 seconds. On timeout, hook is terminated and agent continues.
• Scripts read JSON from stdin (INPUT=$(cat)) and write to stdout; debug output goes to stderr.

Environment Variables

No built-in variables beyond those specified in the hook’s env field. The cwd field controls the working directory.

Additional Extension Surfaces (not hooks, but related)

Custom instructions (soft/probabilistic)

Priority: Personal (user) > Repository (workspace) > Organization.

MCP server configuration

Note: VS Code uses "servers" as root key while the CLI uses "mcpServers". MCP tools only work in Copilot’s Agent mode. Supported transports: local/stdio, http/sse.

MCP Server Registration

Symposium registers MCP servers in the Copilot config as top-level keys (matching the CLI’s mcpServers format, not VS Code’s servers format):

{
  "symposium": {
    "command": "/path/to/cargo-agents",
    "args": ["mcp"]
  }
}

• Project-level: .vscode/mcp.json
• User-level: ~/.copilot/mcp-config.json

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.

Copilot SDK (programmatic hooks)

The @github/copilot-sdk (Node.js, Python, Go, .NET, Java) provides callback-style hooks for applications embedding the Copilot runtime:

• onPreToolUse — can return modifiedArgs
• onPostToolUse — can return modifiedResult
• onSessionStart, onSessionEnd, etc.

Agent firewall (Cloud Agent)

Network-layer control with deny-by-default domain allowlist, configured at org/repo level. Not a hook — controls outbound network access.

Gemini CLI Hooks Reference

Disclaimer: This document reflects our current understanding of Gemini CLI’s hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: Hooks reference · Extensions reference · GitHub repo

Gemini CLI’s hook system (v0.26.0, January 2026) mirrors Claude Code’s JSON-over-stdin contract and exit-code semantics. It adds model-level and tool-selection interception events unique to Gemini.

Hook Types

Only type: "command" is currently supported.

Events

Model-level events (unique to Gemini)

• BeforeModel: can swap models, modify temperature, or return a synthetic response to skip the LLM call entirely.
• BeforeToolSelection: can filter the candidate tool list using toolConfig.mode (AUTO/ANY/NONE) and allowedFunctionNames whitelists. Multiple hooks use union aggregation across allowed function lists.
• AfterModel: can redact or modify the LLM response per-chunk during streaming.

Configuration

Four-tier precedence: Project → User → System → Extensions.

Configuration structure

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "sequential": false,
        "hooks": [
          {
            "name": "secret-scanner",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh",
            "timeout": 5000,
            "description": "Prevent committing secrets"
          }
        ]
      }
    ]
  }
}

• matcher: regex for tool events, exact string for lifecycle events.
• sequential: boolean (default false). When true, hooks run in order with output chaining.
• timeout: milliseconds (default 60,000).

Input Schema (stdin)

Base fields (all events)

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "hook_event_name": "string",
  "timestamp": "2026-03-03T10:30:00Z"
}

BeforeTool additions

• tool_name: string
• tool_input: object (raw model arguments)
• mcp_context: object (optional)
• original_request_name: string (optional)

AfterTool additions

• tool_name, tool_input (same as BeforeTool)
• tool_response: object containing llmContent, returnDisplay, and optional error

BeforeModel additions

• llm_request: object with model, messages, config, toolConfig

BeforeAgent additions

• prompt: string (the user’s original prompt text)

AfterAgent additions

• stop_hook_active: boolean (loop detection)

Output Schema (stdout)

Universal fields

Event-specific output via hookSpecificOutput

BeforeTool: tool_input — merges with and overrides model arguments.

AfterTool:

• additionalContext: string appended to tool result
• tailToolCallRequest: object triggering a follow-up tool call

AfterAgent: when denied, reason is sent as a new prompt for retry.

BeforeAgent: additionalContext — string appended to the prompt for that turn. decision: "deny" discards the user’s message from history; continue: false preserves it.

BeforeModel:

• llm_request: overrides outgoing request (swap model, modify temperature, etc.)
• llm_response: provides synthetic response that skips the LLM call

Exit Codes

Execution Behavior

• Hooks run in parallel by default; set sequential: true for ordered execution with output chaining.
• Default timeout: 60,000ms.

Environment Variables

Environment redaction for sensitive variables (KEY, TOKEN patterns) is available but disabled by default.

Migration from Claude Code

gemini hooks migrate --from-claude

Converts .claude configurations to .gemini format. Tool name mappings:

Custom Instructions

Gemini CLI reads GEMINI.md files at multiple levels:

The filename is configurable via context.fileName in settings.json (e.g., ["AGENTS.md", "GEMINI.md"]). Supports @file.md import syntax for including content from other files.

Skills

Skills use SKILL.md with YAML frontmatter (name, description). Metadata is injected at session startup; full content loads on demand via activate_skill.

MCP Server Configuration

Configured under mcpServers in .gemini/settings.json or ~/.gemini/settings.json:

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/executable",
      "args": ["--arg1"],
      "env": { "API_KEY": "$MY_TOKEN" },
      "timeout": 30000
    }
  }
}

Transport is auto-selected by key: command+args (stdio), url (SSE), httpUrl (streamable HTTP).

MCP Server Registration

In addition to hooks, symposium registers itself as an MCP server in the agent’s settings file. This provides an alternative integration path alongside the hook-based approach.

Configuration structure

The MCP server entry is added under mcpServers in the same settings file used for hooks:

{
  "mcpServers": {
    "symposium": {
      "command": "/path/to/cargo-agents",
      "args": ["mcp"]
    }
  }
}

• Project-level: .gemini/settings.json
• User-level: ~/.gemini/settings.json

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.

Codex CLI Hooks Reference

Disclaimer: This document reflects our current understanding of Codex CLI’s hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: Hooks · GitHub repo

OpenAI’s Codex CLI implements a shell-command hook system configured in hooks.json. It is experimental (disabled by default, not available on Windows) and first shipped in v0.114 (March 2026).

Enabling

Add to ~/.codex/config.toml:

[features]
codex_hooks = true

Configuration

Both are additive — all matching hooks from all files run. Project hooks follow the untrusted-project trust model.

Configuration structure

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.codex/hooks/check_bash.py",
        "statusMessage": "Checking command safety",
        "timeout": 30
      }]
    }]
  }
}

Only handler type is "command". matcher is a regex string; omit or use "" / "*" to match everything. Default timeout: 600 seconds, configurable via timeout or timeoutSec.

Events

Input Schema (stdin)

Base fields (all events)

{
  "session_id": "string",
  "transcript_path": "string|null",
  "cwd": "string",
  "hook_event_name": "string",
  "model": "string"
}

Turn-scoped events (PreToolUse, PostToolUse, UserPromptSubmit, Stop) add turn_id.

PreToolUse additions

• tool_name: string
• tool_use_id: string
• tool_input: object with command field

PostToolUse additions

• tool_name, tool_use_id, tool_input (same as PreToolUse)
• tool_response: string

UserPromptSubmit additions

• prompt: string

Stop additions

• stop_hook_active: boolean
• last_assistant_message: string

Output Schema (stdout)

Deny/block (two equivalent methods)

Method 1 — JSON output:

{ "decision": "block", "reason": "Destructive command blocked" }

or:

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked"
  }
}

Method 2 — Exit code 2 with reason on stderr.

Inject context

{
  "hookSpecificOutput": {
    "additionalContext": "Extra info for the agent"
  }
}

Plain text on stdout also works for SessionStart and UserPromptSubmit (ignored for PreToolUse, PostToolUse, Stop).

Stop session

{ "continue": false, "stopReason": "Session terminated by hook" }

Supported on SessionStart, UserPromptSubmit, PostToolUse, Stop.

System message (UI warning)

{ "systemMessage": "Warning text shown to user" }

Stop event special behavior

For the Stop event, { "decision": "block", "reason": "Run tests again" } tells Codex to create a continuation prompt — it does not reject the turn.

Exit Codes

Execution Behavior

• Multiple matching hooks run concurrently — no ordering guarantees.
• Commands run with session cwd as working directory.
• Shell expansion works.

Parsed but Not Yet Implemented

These fields are accepted but fail open (no effect): suppressOutput, updatedInput, updatedMCPToolOutput, permissionDecision: "allow", permissionDecision: "ask".

Current Limitations

• Only Bash tool events fire PreToolUse/PostToolUse — no file-write or MCP tool hooks.
• PreToolUse can only deny, not modify tool input.
• No async hook mode.
• Stop event requires JSON output (plain text is invalid).

Environment Variables

No dedicated environment variables are set during hook execution (unlike Claude Code’s CLAUDE_PROJECT_DIR). All context is passed via stdin JSON. The cwd field serves as the project directory equivalent. CODEX_HOME (defaults to ~/.codex) controls where Codex stores config and state.

Custom Instructions

The project_doc_fallback_filenames config option in ~/.codex/config.toml allows alternative filenames. Max combined size: 32 KiB (project_doc_max_bytes).

Skills

Skills use SKILL.md with YAML frontmatter (name, description) and may include scripts/, references/, assets/, and agents/openai.yaml.

MCP Server Configuration

Configured in ~/.codex/config.toml or .codex/config.toml under [mcp_servers.<name>]:

[mcp_servers.my-server]
command = "path/to/executable"
args = ["--arg1"]
env = { API_KEY = "value" }
startup_timeout_sec = 10
tool_timeout_sec = 60

Supports stdio (command/args) and streamable HTTP (url/bearer_token_env_var). CLI management: codex mcp add <name> ....

MCP Server Registration

In addition to hooks, symposium registers itself as an MCP server in the agent’s config file. This provides an alternative integration path alongside the hook-based approach.

Configuration structure

The MCP server entry is added under [mcp_servers] in the TOML config:

[mcp_servers.symposium]
command = "/path/to/cargo-agents"
args = ["mcp"]

• Project-level: .codex/config.toml
• User-level: ~/.codex/config.toml

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.

Other Extensibility

• notify in config.toml (fire-and-forget on agent-turn-complete)
• Execpolicy command-level rules
• Subagents
• Slash commands

Goose Hooks Reference

Disclaimer: This document reflects our current understanding of Goose’s extensibility surface. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: Extensions · Configuration · GitHub repo

Goose does not implement lifecycle hooks. There are no shell-command or programmatic interception points for tool execution, session start/stop, or prompt submission. No hooks.json equivalent. No JSON stdin/stdout protocol.

What Goose Offers Instead

MCP Extensions

The primary extensibility mechanism. Extensions are MCP servers (stdio or HTTP) that expose new tools, resources, and prompts. Configured in ~/.config/goose/config.yaml under extensions:. Built-in extensions include Developer (shell, file editing), Computer Controller, Memory, and Todo. Custom extensions are standard MCP servers built in Python, TypeScript, or Kotlin. Extensions add capabilities but cannot intercept or modify existing tool behavior.

Permission Modes

The closest analog to hook-based control flow. Static configuration, not programmable logic.

Per-tool permissions can be set to Always Allow, Ask Before, or Never Allow.

Goosehints / AGENTS.md

Instruction files injected into the system prompt. Influence LLM behavior through prompting, not deterministic interception.

GOOSE_TERMINAL Environment Variable

Shell scripts can detect whether they’re running under Goose and alter behavior (e.g., wrapping git to block git commit). This is a shell-level workaround, not a Goose-native mechanism.

Other Mechanisms

• .gooseignore — gitignore-style file access restriction
• Recipes — YAML workflow packages
• Custom slash commands
• Subagents
• ACP integration
• Tool Router — internal optimization for tool selection

MCP Server Registration

Since Goose has no lifecycle hooks, symposium integrates exclusively via MCP server registration. Symposium registers itself as an extension in the Goose config file.

Configuration structure

The MCP server entry is added under extensions in the YAML config:

extensions:
  symposium:
    provider: mcp
    config:
      command: /path/to/cargo-agents
      args: [mcp]

• Project-level: .goose/config.yaml
• User-level: ~/.config/goose/config.yaml

Registration is idempotent — if the entry already exists with the correct values, no changes are made. Stale entries are updated in place.

Kiro Hooks Reference

Disclaimer: This document reflects our current understanding of Kiro’s hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: CLI hooks · Agent configuration reference · IDE hooks

Kiro is Amazon’s AI coding agent available as an IDE (VS Code fork) and CLI. Both have hook systems but they differ in configuration format, trigger types, and capabilities.

Kiro CLI Agent Definition

Each .kiro/agents/*.json file defines a complete agent. All fields are optional; omitting a field has specific defaults.

Agent Definition Fields

Critical: Omitting tools means the agent has zero tools. Use "tools": ["*"] for all tools, "@builtin" for built-ins only, or list specific tools.

Tools Field Values

• "*" — all available tools
• "@builtin" — all built-in tools
• "read", "write", "shell" — specific built-in tools
• "@server_name" — all tools from an MCP server
• "@server_name/tool_name" — specific MCP tool

AllowedTools Field

Specifies tools that execute without user confirmation. Supports exact matches and glob patterns ("@server/read_*", "@git-*/status"). Does not support "*" wildcard for all tools.

Resources Field

• "file://README.md" — load file into context at startup
• "skill://.kiro/skills/**/SKILL.md" — skill metadata loaded at startup, full content on-demand

Custom agents do not auto-discover skills. They require explicit skill:// URIs in resources.

Kiro CLI Hooks

Configured inside agent configuration JSON files. Shell commands receive JSON on stdin and use exit codes for control flow.

Events

Input Schema (stdin)

All events include hook_event_name and cwd.

userPromptSubmit adds:

• prompt: string

preToolUse adds:

• tool_name: string
• tool_input: object (full tool arguments)

postToolUse adds:

• tool_name: string
• tool_input: object
• tool_response: string

MCP tools use @server/tool naming (e.g., @postgres/query).

Exit Codes

Matcher Patterns

• Tool name strings: execute_bash, fs_write, read
• Aliases: shell, write
• MCP server globs: @git, @git/status
• Wildcards: *
• Built-in group: @builtin
• No matcher = applies to all tools

Execution Behavior

• Hooks execute in array order within each trigger type.
• Default timeout: 30 seconds (30,000ms), configurable via timeout_ms.
• cache_ttl_seconds: default 0 (no caching). agentSpawn hooks are never cached.

Configuration Example

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "./scripts/validate.sh"
      }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ],
    "agentSpawn": [
      {
        "command": "git status"
      }
    ]
  }
}

Each entry is a flat object with command (required) and optional matcher. There is no nested hooks array or type field.

Kiro IDE Hooks

Stored as individual .kiro.hook files in .kiro/hooks/. Created via the Kiro panel UI or command palette.

Hook File Format

name: Format on save
description: Run formatter after file saves
when:
  type: fileEdit
  patterns: **/*.ts
then:
  type: shellCommand
  command: npx prettier --write {file}

Trigger Types (10)

The IDE adds file-event and spec-task triggers not available in the CLI.

Action Types (2)

IDE Tool Matching Categories

read, write, shell, web, spec, *, @mcp, @powers, @builtin, plus regex patterns with @ prefix.

IDE Execution Behavior

• Default timeout: 60 seconds.
• USER_PROMPT env var is available for promptSubmit shell commands.

Environment Variables

No dedicated environment variables are documented for CLI hook execution. Context is passed via stdin JSON. The IDE provides USER_PROMPT for promptSubmit shell command hooks.

Custom Instructions (Steering)

Kiro uses “steering files” instead of a single instructions file:

Steering files support YAML frontmatter with four inclusion modes: Always, FileMatch (glob pattern), Manual (referenced via #name in chat), and Auto (description-based matching). Kiro also auto-generates product.md, tech.md, and structure.md.

Skills

Workspace skills take precedence over global skills with the same name. The default agent auto-discovers skills from both locations. Custom agents require explicit skill:// URIs in their resources field. Skills use SKILL.md with YAML frontmatter (name, description).

MCP Server Configuration

Priority: Agent config > Workspace > Global. Format is JSON with mcpServers key, supporting command/args/env for stdio and url/headers for remote servers.

MCP Server Registration

In addition to hooks, symposium registers itself as an MCP server in the agent’s MCP config file. This provides an alternative integration path alongside the hook-based approach.

Configuration structure

The MCP server entry is added under mcpServers:

{
  "mcpServers": {
    "symposium": {
      "command": "/path/to/cargo-agents",
      "args": ["mcp"]
    }
  }
}

• Project-level: .kiro/settings/mcp.json
• User-level: ~/.kiro/settings/mcp.json

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.

OpenCode Plugin System Reference

Disclaimer: This document reflects our current understanding of OpenCode’s plugin/hook system. It is a working reference for symposium development, not a substitute for the official docs. Details may be outdated or incomplete — always consult the primary sources.

Primary sources: Plugins · GitHub repo

OpenCode’s extensibility centers on TypeScript/JavaScript plugins, not shell commands. Plugins are async functions that receive a context object and return a hooks object. A secondary experimental system supports shell-command hooks in opencode.json.

Symposium does not currently integrate with OpenCode’s hook system. OpenCode is supported as a skills-only agent.

Plugin Locations and Load Order

Hooks run sequentially in this order:

1. Global config plugins (~/.config/opencode/opencode.json → "plugin": [...])
2. Project config plugins (opencode.json)
3. Global plugin directory (~/.config/opencode/plugins/)
4. Project plugin directory (.opencode/plugins/)

npm packages are auto-installed via Bun and cached in ~/.cache/opencode/node_modules/.

Plugin Context Object

All plugins receive: { project, client, $, directory, worktree }.

Core Plugin Hooks

Experimental Hooks (prefix experimental.)

tool.execute.before Schema

Input

{
  "tool": "string",
  "sessionID": "string",
  "callID": "string"
}

Output (mutable)

{
  "args": { "key": "value" }
}

Mutate output.args to change tool arguments before execution.

chat.params Schema

Input

{
  "model": "string",
  "provider": "string",
  "message": "object"
}

Output (mutable)

{
  "temperature": 0.7,
  "topP": 0.9,
  "options": {}
}

Limitations

• MCP tool calls do NOT trigger tool.execute.before or tool.execute.after.
• Plugin-level syntax errors prevent loading entirely.
• tool.execute.before errors block the tool.
• No explicit timeout documentation for plugin hooks.
• No hook ordering guarantees beyond load order.

Experimental Config-Based Shell Hooks (opencode.json)

A simpler shell-command system under "experimental.hook":

{
  "experimental": {
    "hook": {
      "file_edited": {
        "*.ts": [{ "command": ["prettier", "--write"], "environment": {"NODE_ENV": "development"} }]
      },
      "session_completed": [{ "command": ["notify-send", "Done!"], "environment": {} }]
    }
  }
}

Only two events: file_edited (glob-matched) and session_completed. No session_start (requested in issue #12110).

Environment Variables

Core OpenCode sets these on child processes:

• OPENCODE_SESSION_ID — current session identifier
• OPENCODE_SESSION_TITLE — human-readable session name

The shell.env plugin hook allows injecting custom environment variables into all shell execution.

Configuration-related env vars (not hook-specific): OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_MODEL.

Custom Instructions

Priority: local AGENTS.md > local CLAUDE.md > global ~/.config/opencode/AGENTS.md > global ~/.claude/CLAUDE.md.

Skills

OpenCode walks up from CWD to the git worktree root, loading matching skill definitions. Skills use SKILL.md with YAML frontmatter (name, description) and are loaded on-demand via the native skill tool.

Additional Events (Plugin System)

The full event list includes: session.created, session.idle, session.compacted, message.updated, file.edited, file.watcher.updated, permission.asked, permission.replied, tool.execute.before, tool.execute.after, shell.env, tui.prompt.append, tui.command.execute, and others (~30 total). The message.updated event (filtered by role === "user") is the closest equivalent to a user-prompt-submit hook. The session.created event is the session-start equivalent.

MCP Server Registration

In addition to hooks, symposium registers itself as an MCP server in the agent’s config file. This provides an alternative integration path alongside the hook-based approach.

Configuration structure

The MCP server entry is added under mcp in the JSON config:

{
  "mcp": {
    "symposium": {
      "command": "/path/to/cargo-agents",
      "args": ["mcp"]
    }
  }
}

• Project-level: opencode.json
• User-level: ~/.config/opencode/opencode.json

Registration is idempotent — if the entry already exists with the correct values, no changes are made. If the entry exists but has stale values (e.g. the binary moved), it is updated in place.