/sponsio

name: sponsio
description: Install, observe, tune, and enforce Sponsio: a runtime contract layer for LLM agents that blocks unsafe tool calls and scores output quality against declared rules. Use when the user wants to set up / add / install Sponsio, add guardrails or runtime safety to an LLM agent, generate or refine a sponsio.yaml, audit tool configurations for risks (data leaks, unguarded writes, missing confirmations), explain or review existing contracts, check what Sponsio would have blocked (`sponsio report`), move from observe to enforce mode, or debug why a contract is (or isn't) firing. Triggers on phrases like "set up sponsio", "add sponsio", "install sponsio", "add guardrails", "monitor my agent", "harden my agent", "audit my agent", "generate contracts", "explain my sponsio.yaml", "sponsio report", "flip to enforce", "false positive", "why is this rule firing".

Sponsio — Agent Safety Lifecycle Companion

Sponsio is a Python/TypeScript runtime safety layer for LLM agents: it evaluates deterministic contracts against each tool call and can block (enforce) or just log (observe) violations. The engine is deterministic-only. This skill covers the full lifecycle — first-time setup, contract authoring/review, observe-mode tuning, and flipping to enforce — by orchestrating Sponsio's CLI and explaining its output in plain language.

This skill does NOT reimplement Sponsio's logic; it calls the CLI and interprets results.

When to use this skill

Dispatch by what the user is trying to do. Pick ONE workflow and follow it; do not run multiple workflows in one turn.

| User is… | → Workflow | |---|---| | Setting up Sponsio for the first time in a project ("add sponsio", "install sponsio", "add guardrails") | **W1 — Initial setup** (just dispatch ``sponsio init``) | | Handing you a codebase and asking "what could go wrong?" / wants a fresh contract file from scratch / has a policy doc to encode | **W2 — Audit & refine** | | Authoring contracts for a Claude Code / OpenClaw plugin or a bare MCP server (input is a plugin manifest, not source code) | **W2b — Plugin / MCP contracts** | | Tightening rules that apply to Task-spawned subagents (Cursor / Claude Code) — they lack user context and need stricter privileges than the main agent | **W2c — Subagent privilege boundary** | | Tuning the IDE's OWN host-plugin library (Claude Code's Bash / Read / Write / MCP gating; Cursor likewise) — different from the user's project sponsio.yaml | hand off to the ``sponsio-claude-code:configure`` skill (or the cursor analog). Don't reimplement here. | | Has Sponsio running in observe mode and wants to review violations, tune thresholds, silence false positives | **W3 — Tune in observe** | | Ready to ship — wants to move from observe to enforce, needs regression confidence | **W4 — Flip to enforce** | | Sponsio errored, a rule isn't firing when it should, a rule is firing when it shouldn't | **W5 — Troubleshoot** | | Just ran their agent and asks "did anything slip through?" / wants NEW contracts proposed from a run's traces ("check my last run", self-evolving rulebook) | **W6 — Discover missing contracts from traces** |

Do NOT trigger for: general LLM-safety discussions not tied to a specific codebase; non-agent code review (linting, correctness).

Prerequisites (run silently before any workflow)

sponsio --version

• Not found → install: `pip install sponsio` (or `pip install -e ".[all]"` from a local clone).
• For `--llm` inference, check: `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Absent → still proceed; AST-based extraction and all of W3/W4/W5 work with zero keys.

---

Editing contract YAML — write rules by file

Sponsio contract YAMLs split into **two trust zones** with different write rules. Pick the right zone before any edit; the runtime's self-modify pack enforces the host-zone rules, but cross-zone slips are still a config-correctness bug we'd rather avoid up-front.

Zone A — project YAML (you may add additively)

Path: `<project>/sponsio.yaml` — the file `sponsio onboard` writes into the user's repo. This evolves through every onboard / scan cycle. **Adding** new contracts via `Edit` (extending `old_string`) is the supported workflow.

Three legal write modes:

1. **Add a new contract** — `Edit` with `new_string` extending `old_string` (the invariant: `old_string ⊆ new_string`):

   old_string  = the verbatim tail of the existing file ending at
                 the last contract entry (or the last `contracts:`
                 line if the list is empty)
   new_string  = old_string + "\n      - <new contract YAML block>"

2. **Tune an existing pack-shipped rule** — never edit the rule directly; append a `customized:` entry:

   customized:
     - match: { desc: "<the shipped rule's desc, exact>" }
       A: "<extra assumption that narrows when it fires>"   # to relax
       # or args: [...]                                     # to retune thresholds
       # or disabled: true                                  # to silence (last resort)

3. **Run `sponsio scan`** for bulk additions from code / policy, merges additively and writes atomically:

   sponsio scan <paths> -o ./sponsio.yaml --append

Zone B — host bucket + plugin bundle YAMLs (user-only — never write directly)

Paths:

• `~/.sponsio/plugins/{{HOST_BUCKET}}/sponsio.yaml` (this host's runtime library)
• `~/.sponsio/plugins/{{HOST_BUCKET_SUBAGENT}}/sponsio.yaml` (this host's subagent library)
• `~/.sponsio/plugins/<plugin-id>/sponsio.yaml` (per-plugin / per-MCP-server bundle — github, filesystem, my-plugin, …)

These files govern *your own future tool calls*. The runtime self-modify pack blocks every Edit / Write / MultiEdit you'd attempt against them — for the host bucket because rewriting your own rules is privilege escalation, and for the per-plugin bundles for the same re