Skip to content

Plugins

TOVIO plugins are sandboxed lifecycle extensions: structured, capability-scoped, auditable code that runs at defined moments in a repository's life — before a snapshot, before a land, when a conflict needs resolving, or when a proposal is created.

They exist for the outcomes Git hooks are used for — required checks, formatters, license and policy gates, custom analyzers, AI conflict resolvers — but without the unsafe parts of Git hooks: arbitrary local shell, ambient secrets, per-machine drift, and no audit trail.

One plugin is already on: 🔒 secret scanning

Every repo scans for secrets on every commit, out of the box — see Secret scanning (on by default). It's the flagship example of the model: default-on, sandboxed, and human-confirmed.

Plugin runtime is implemented

The contracts, the tovio plugin CLI, the WASM/WASI sandbox, local lifecycle bindings, and secret scanning are built. So are Ed25519 publisher signatures with a repository-local trust and revocation store, bounded HTTPS installation (ADR-0080), and the conflict-created firing site. The Forge has a native server-side runner that executes and self-attests bound plugins, though it is an opt-in build — the default Forge ships the attestation gate without an executor. What remains is a repo/org binding-management surface — every binding a client writes today is a local one — plus production key-rotation and revocation evidence.

What plugins are — and are not

  • Plugins are

    • Packaged with a manifest, a runtime artifact, and declared capabilities.
    • Executed inside a WASM/WASI sandbox (or an equivalent). No arbitrary shell.
    • Called with structured, schema-versioned JSON input and expected to return structured JSON output.
    • Bound to specific lifecycle events in specific modes (advisory, enforcing, transform, resolver).
    • Deny-by-default: no filesystem, no network, no protected plaintext, no key material.
    • Auditable: every enforcing execution produces tamper-evident audit metadata.

  • Plugins are not

    • Not Git hooks. Not shell scripts. Not .git/hooks/*.
    • Not a way to read protected file contents. Protected paths are metadata-only by default.
    • Not a way to reach key material. Ever.
    • Not trusted by Forge until backed by a policy-approved attestation or server-side execution.
    • Not a replacement for Forge webhooks as the canonical server-side event fan-out.

Choose your path

  • Concepts

    The three-layer model, the lifecycle events, the four modes, and why TOVIO rejected shell hooks.

    Understand plugins

  • Workflows & diagrams

    Every plugin workflow — install, bind, run, block, override, audit — as a Mermaid diagram. Best entry point for visual learners.

    Workflows

  • Use a plugin

    Install, verify, bind, and run a plugin in your repository. What blockers look like and how to override.

    Use a plugin

  • Write a plugin

    Build a check plugin end-to-end: manifest, input/output, testing with tovio plugin test, packaging for distribution.

    Author guide

  • Manifest reference

    Every field of plugin.toml, with types, defaults, and examples.

    Manifest

  • Bindings

    How plugins get attached to events. Local vs. repo vs. org vs. Forge scope, advisory vs. enforcing, version pinning.

    Bindings

  • Capabilities & security

    The deny-by-default capability set, protected content rules, sandbox guarantees, and the intersection with agent tokens.

    Capabilities

  • Lifecycle events

    Every lifecycle event TOVIO defines, its payload, and which subsystem fires it.

    Events

  • CLI reference

    The full tovio plugin and tovio policy hook command surface.

    CLI

  • Errors

    The TVO-PLUGIN-* error catalog and how to recover from each.

    Errors

Why TOVIO ships its own plugin system

Every other extension surface in TOVIO — capability tokens, lane protection, policy expressions, the MCP agent API — already assumes structured, auditable, capability-scoped integration points. Shell hooks would be the odd one out. They cannot be capability-scoped, they leak ambient secrets, they vary by machine, and they can silently touch protected content. The plugin system generalizes the safe seams TOVIO already has (starting with tovio resolve --ai) into one uniform, sandboxed extension model that works the same locally, in CI, and on the Forge.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure