Security: capability sandboxing for ingested P2P skills

[VGIL77]

Companion to the prompt-injection scanning issue. Even if a skill's content passes injection screening, the skill itself defines the agent's behavior surface when invoked, and current code grants ambient capabilities to whatever's in the active skills directory. A trusted-peer-turned-malicious could publish a skill that does exactly what its frontmatter says, where the description happens to be "exfiltrate .env to attacker.example.com" or "send wallet balance to known-bad address."

Threat model

A trusted publisher pushes a skill whose stated purpose is hostile but technically truthful. Without per-skill capability declarations enforced at runtime, ambient trust on the skill becomes ambient trust on every tool it can reach: shell, network, wallet, filesystem outside the skill's workspace.

Proposed defense

• SKILL.md frontmatter declares required capabilities, e.g. capabilities: [shell, wallet.send, network.fetch]
• Default profile for ingested-from-mesh skills is least-privilege: read-only filesystem, no network, no wallet, no shell
• High-risk capabilities (wallet writes, shell, file writes outside the skill's workspace, arbitrary outbound network) require explicit operator approval per-skill, prompted at first invocation rather than at ingestion
• Enforcement at the runtime level, not just the prompt level. The skill literally cannot call those tools, vs. trusting the LLM not to use them after being told not to in the system prompt

Open questions

• How this interacts with the existing allowed-tools frontmatter convention. Probably consolidate into one capability schema rather than maintain both.
• Per-skill vs. per-publisher capability profile. A skill from a verified publisher might inherit elevated defaults; an untrusted publisher's skill stays locked down regardless of frontmatter claims.
• Sandbox boundary: worker thread, separate process, or capability-token model. Worker thread is cheapest and good enough for "no shell, no wallet, restricted fs." Separate process is needed for hard isolation against memory-corruption skills (lower priority).

Why now

Same trigger as the injection-scanning issue. Belt-and-braces: scan the content, then constrain what the content can do even if the scan misses something.

[VGIL77]

Phase A foundation landed in cb09419 on main. Phase B (this issue) is up next.

While Phase A doesn't directly add capability sandboxing, it materially reduces the threat envelope this issue is trying to close: most paths to capability abuse start with prompt-injected content from an inbound skill. With the scanner now force-quarantining critical injection patterns regardless of policy or trust, the realistic attack on capability sandboxing narrows from "any signed peer can ship a worm that calls wallet.send_usdc" to "the LLM has to be coaxed into a tool call that the skill's frontmatter never declared, where the skill content itself is benign-looking." That's the case Phase B is designed to close.

What Phase A bought us toward this issue

• Skills with adversarial <tool_call> blocks force-quarantine; the LLM never sees them.
• Skills declaring wallet.send_usdc(...) invocations in their body trip the tool-impersonation flag.
• A peer who tries an attack that gets caught accumulates injection flags; 3+ critical hits in 24h auto-ban.
• Operators get a notification on every quarantined skill with the reason inline.

What Phase B still needs to add

• Frontmatter capabilities field with explicit network / fs / wallet / shell axes.
• skill_capability_grants SQLite table keyed on content hash, with operator-consent UX at first invocation for high-risk capabilities (Claude Skills allowed-tools + permissionMode: "dontAsk" is the model).
• SkillCapabilityEnforcer at the tool dispatch layer that refuses tool calls falling outside the resolved capability profile, even if the LLM was coaxed into emitting them.
• Trust-tier defaults for ingested skills: verified honors frontmatter; provisional strict-profile + operator-confirmed adds; untrusted always strict.

The plan in research/plans/PLAN-13-skill-ingestion-security.md (internal) carries the full architecture; the public scope is unchanged from this issue.

Estimated 3-4 weeks of work. Tracking on this issue.

Community ask

If you've shipped capability-based security for an agent runtime (Deno-style permission grants, WASM/wasmtime capabilities, gVisor for skill execution, Permiso SandyClaw, anything in the same neighborhood) and have lessons on operator-consent fatigue or the granularity sweet spot for the capability axes, please drop a comment. Most of the literature converges on network / fs / process / env as the four corners; we're proposing a fifth (wallet) because we have an integrated USDC wallet on Base and want explicit per-skill control over it. Curious if anyone with a similar threat model has converged on a different shape.

[VGIL77]

Phase B (load-time gate) landed in 1f2e6b5 on main. The runtime dispatch enforcer is intentionally deferred to follow-up; reasoning below.

What shipped

Layer	File	Role
Schema	src/agents/skills/types.ts	SkillCapabilitiesDeclaration with network / fs / wallet / shell / process axes. Declarations live under bitterbot.capabilities alongside the existing requires / install / origin.
Parser	src/agents/skills/frontmatter.ts	parseCapabilities reads the new block. Permissive on missing fields; never expands missing to allow.
Storage	src/memory/migrations.ts v10 + src/agents/skills/capability-grants.ts	skill_capability_grants table, keyed on (content_hash, capability) so a swap-out of malicious content under the same skill name forces fresh consent rather than inheriting a previous decision. UPSERT semantics on set.
Resolver	src/agents/skills/capability-profile.ts	resolveCapabilityProfile combines tier baselines (banned, untrusted, provisional, trusted, verified, local) with declarations and grants into an EffectiveCapabilityProfile. Tier baselines clip declarations downward; declarations clip the tier; allow grants widen up to the declaration but never beyond; deny grants are absolute.
Gate	src/agents/skills/capability-gate.ts	evaluateSkillCapabilities admits or blocks each skill based on whether the resolved profile honors every axis the declaration claimed. applyCapabilityGate partitions a batch with structured block reasons. loadSkillProvenance reads .provenance.json to bind a skill to its publisher.
Workspace	src/agents/skills/workspace.ts	filterSkillEntries now accepts an optional capabilityGate. Blocked skills are excluded from the prompt with a warn-level log line. Wired through buildWorkspaceSkillSnapshot, buildWorkspaceSkillsPrompt, and buildWorkspaceSkillCommandSpecs.

How a SKILL.md declares capabilities

---
name: weather
description: Fetch weather forecasts.
metadata:
  {
    "bitterbot": {
      "capabilities": {
        "network": { "outbound": ["api.openweathermap.org", "wttr.in"] },
        "fs": false,
        "wallet": false,
        "shell": false
      }
    }
  }
---

Trust-tier baselines define the upper bound on each axis regardless of declaration:

Tier	network	fs	wallet	shell	process
verified	declared list	declared paths	yes	yes	yes
trusted	declared list	declared paths	grant required	grant required	grant required
provisional	denied	workspace only	denied	denied	denied
untrusted	denied	workspace only	denied	denied	denied
banned	denied	denied	denied	denied	denied
local (no provenance)	full trust	full trust	yes	yes	yes

A provisional-tier publisher whose SKILL.md claims wallet: true is excluded from the active prompt (the LLM never sees it). A verified publisher whose SKILL.md voluntarily declares wallet: false is honored even though the tier would permit it.

Tests

54 unit tests passing across:

• capability-profile.test.ts (16) — tier baselines, declaration clipping, grant interaction (allow / deny), profileAllows semantics, "attacker tiers cannot get wallet via any path" aggregate.
• capability-gate.test.ts (12) — provenance loader, evaluator per tier, grant rescue + override, batch partitioning.
• frontmatter.capabilities.test.ts (7) — full block parse, false deny axes, missing-block undefined, malformed values ignored.

Typecheck and lint both clean.

What's deferred and why

B.5 — Runtime dispatch enforcer. The wrapper composition site at src/agents/pi-tools.ts:454-462 is the right hook (alongside the existing wrapToolWithBeforeToolCallHook and wrapToolWithAbortSignal). The unsolved problem is attribution: when the LLM emits wallet.send_usdc(...), we cannot reliably tell whether the call was motivated by skill A (legitimate, declares wallet) or skill B (subtle injection, declares no wallet). Without attribution the choice is between (a) a permissive union profile across all loaded skills, which weakens the defense, and (b) a restrictive intersection, which breaks legitimate use. Either decision deserves a design RFC rather than getting buried in an implementation commit.

B.6 — Wire reputation manager into agent runner. The gate is opt-in at the call site for this release. filterSkillEntries accepts the gate context but the runner doesn't yet thread one through, because the runner currently doesn't carry a PeerReputationManager reference; threading that down is a non-trivial signature change that we'll do in the follow-up that wires real reputation data in. The gate is fully testable today and activates the moment a caller supplies the context.

B.7 — Operator-consent UX. When a provisional-tier skill is blocked but would be permitted with a wallet/shell grant, the operator should see a "this skill needs your approval" prompt rather than a silent block. Surface via the same enqueueSystemEvent channel as Phase A's quarantine notifications.

Together these three follow-ups are the difference between "the load-time gate works in isolation" and "the runtime path is end-to-end enforced." This commit lands the foundation cleanly; the activation work is honest about the attribution problem rather than papering over it.

Community ask

For anyone with an opinion on how to attribute an LLM-emitted tool call back to the skill that motivated it: this is the unsolved problem in B.5. Approaches we've considered:

1. Prepend an <active-skill> marker the model is asked to set before tool calls. Soft enforcement, easy to skip.
2. Parse the most-recent skill reference in the system message before each tool call. Stronger but brittle if the LLM ranges across skills mid-task.
3. Conservative union: any tool call permitted by any active skill is allowed. Defensive, but a provisional skill with a wallet:true allow grant would widen the surface across the whole prompt.
4. Conservative intersection: only tool calls permitted by every active skill. Breaks legitimate use the moment more than one skill is loaded.

If you've shipped agent-OS or skill-framework work that solves attribution at the prompt boundary, we'd love to learn from your approach. Drop a comment.

[VGIL77]

Phase B.5 + B.6 closed. B.7 partial (notification surface exists; load-time-gate notification wiring remains).

The runtime dispatch enforcer is live. With this commit Phase B's defense-in-depth is end-to-end:

Layer	When	What	Code
Phase A scanner	Ingest time	Force-quarantine adversarial content	src/agents/skills/ingest.ts:118-132, skill-network-bridge.ts:286-306
Phase B load gate	Skill load	Strip skills whose declared capabilities exceed publisher tier	src/agents/skills/capability-gate.ts
Phase B.5 enforcer	Tool dispatch	Refuse sensitive calls outside the active union profile	src/agents/skills/capability-enforcer.ts
Phase A reputation	Always	3+ critical hits in 24h auto-bans publisher	src/memory/peer-reputation.ts:132-173

What B.5 ships

src/agents/skills/capability-enforcer.ts (303 LOC):

• evaluateToolCall(toolName, params, ctx) — pure check returning null on allow, or a CapabilityDenied describing the refusal. Tool name → capability axis is mapped via a small set of rules; tools not in the map bypass the enforcer entirely (read, search, computation, memory, etc).
• wrapToolWithCapabilityEnforcer(tool, ctx) — execute-wrapper mirroring wrapToolWithBeforeToolCallHook so it composes alongside abort/cache.
• Conservative union semantics. If any active P2P skill's resolved profile permits the capability, the call goes through. Empty active set is a no-op; the agent's baseline behavior is unaffected by the enforcer when no P2P content is loaded. The attribution problem from the original B.5 design RFC is resolved by depending on the load-time gate (B) and the injection scanner (A) to strip the most-likely problematic skills before they reach the active set. Residual risk: a verified skill with wallet:true loaded alongside a benign-looking-but-subtly-injected skill that declared no wallet — the union allows wallet, the malicious skill could piggyback. That's narrower than the unguarded baseline by orders of magnitude.

What B.6 ships

src/agents/skills/capability-runtime.ts (209 LOC):

• createCapabilityRuntime({ peerReputation, grantsStore, notify }) — returns a CapabilityRuntime with both the load-time gateContext and a per-turn buildEnforcerContext(activeEntries) factory.
• Per-turn pre-resolution. buildEnforcerContext resolves each active P2P skill's profile once when the turn starts; per-tool-call dispatch is then a single array deref.
• Default reputation feedback. Without skill-level attribution, a denial applies a small negative trust edge (0.3) to every active publisher. One false positive doesn't sink a legitimate peer; repeated denials biases the system away from problematic skill combinations.
• createCapabilityRuntimeFromMemory({ config, agentId }) — convenience factory that pulls peer reputation + DB out of MemoryIndexManager, using the same dynamic-access pattern that resolveEndocrineState uses for the hormonal manager. Doesn't widen the manager's public surface.

src/agents/pi-embedded-runner/run/attempt.ts — wires the runtime into every embedded run. createCapabilityRuntimeFromMemory is called once per attempt; the resulting enforcer context is passed to createBitterbotCodingTools so every tool gets wrapped.

src/agents/pi-tools.ts — accepts a new capabilityEnforcer opt; wraps each tool between the before-call and abort wrappers. No-op when absent.

Tests (18 passing)

src/agents/skills/capability-enforcer.test.ts:

• non-sensitive tool always passes
• empty active set is a no-op even for sensitive tools (baseline preservation)
• wallet denied with provisional-only active set
• wallet allowed when at least one active skill grants wallet (union)
• network denied for off-list host even when on-list host is permitted
• malformed url params don't crash the scope extractor (graceful)
• recordDenial / notifyDenial throwing does not block the deny path
• wrapToolsWithCapabilityEnforcer is a no-op when ctx is undefined
• classification + union helpers verified directly

Full skills test surface: 72/72 passing.

Phase B.7 — what remains

The runtime accepts a notify callback that fires on tool denials with a one-line operator message. What's not yet wired:

1. Load-time gate notifications. When a skill is blocked from the prompt by the capability gate, the operator should see "Skill X from peer Y blocked: tier=provisional clips wallet" via enqueueSystemEvent. Today the gate just logs a warning. Wiring is small, just hadn't picked the right session-event surface yet.
2. Operator-consent UX. When a skill is blocked but would be permitted with a wallet/shell grant, surface "this skill needs your approval" inline so the operator can grant on the spot. Same channel.

Both are small follow-up PRs. Filing as B.7-1 and B.7-2 if anyone wants to take them.

Where the defense stands now

Attack	Defense
Forged skill from random peer	Ed25519 transport (Phase 0)
Bytes tampered after signing	SHA-256 content hash (Phase 0)
NL injection in trusted skill	A scanner force-quarantines on critical (both ingest paths)
Worm via signed-but-malicious peer	A reputation feedback + 24h auto-ban after 3 critical hits
Provisional publisher claiming wallet/shell	B load-time gate strips skill from active prompt
LLM coaxed into wallet call via subtle injection from a wallet:false-declared skill	B.5 runtime enforcer denies at dispatch (when no other active skill grants wallet)
Verified skill grants wallet, malicious sibling piggybacks via subtle injection	Residual risk — load-time gate + scanner narrow the surface but don't close it. Filed as design RFC for hard skill-call attribution.

Phase B is functionally closed. C scope (classifier pass, quarantine TTL, bulk-action UX, peer decay) remains in the original plan.

Commits

• A scanner: cb09419
• A.5 + B foundation: 1f2e6b5
• B.5 + B.6 modules: bundled into bff62f2 (the modules in src/agents/skills/capability-{enforcer,runtime}.ts and the test, plus the attempt.ts runner integration, all landed there alongside that commit's observability work)
• B.6 wiring into createBitterbotCodingTools: 0932372

[VGIL77]

Phase B.7 (gate-block notifications) + Phase C foundation shipped in d4bfaa9.

Three of the four Phase C items landed alongside the B.7 notification wire-up. The remaining C tail (ONNX classifier, desktop UI quarantine panel, per-skill marker injection) is deferred to dedicated follow-ups because each warrants its own design pass rather than getting buried in a bundle commit.

What shipped

B.7 — gate-block notifications (src/agents/skills/capability-gate.ts, workspace.ts, capability-runtime.ts, pi-embedded-runner/run/attempt.ts)

The load-time gate now fires notifyBlocked for every skill it excludes from the active prompt, with the reason inline ("tier=provisional clips capabilities [wallet]"). createCapabilityRuntime threads the same callback into both the gate (load-time) and the enforcer (dispatch-time), so a single sink covers both denial paths. The runner wires it to enqueueSystemEvent on the main session — same pattern Phase A's quarantine notifications use.

What's still deferred under B.7-2 is the operator-consent prompt round-trip (a blocked skill prompts "approve wallet for this skill?" inline). The notification channel exists; that follow-up needs a UI surface and is filed.

C — quarantine TTL sweeper (src/agents/skills/quarantine-sweeper.ts)

Walks skills-incoming/, auto-rejects entries older than skills.p2p.quarantineTtlDays (default 30; set 0 to disable). Falls back to file mtime when an envelope is missing or unparseable. Wired into the memory consolidation tick at manager.ts:1394 so it runs on the same cadence as anomaly detection and EigenTrust refresh. 6 unit tests cover empty dir, within-TTL preservation, expired auto-reject + notification, mtime fallback, default 30-day TTL, and notification-throw graceful degradation.

C — bulk-reject by peer (rejectIncomingSkillsByPeer + skills.incoming.rejectByPeer RPC)

The natural use case: an operator just learned a peer is compromised and wants to drop everything that peer has staged for review without clicking through individual entries. Built on top of the existing rejectIncomingSkill so per-skill behavior stays single-sourced. 3 unit tests cover the match/no-match/empty paths. RPC surface ready for the desktop UI quarantine panel (C.2 follow-up).

C — peer reputation decay (PeerReputationManager.decayInactivePeers)

Conservative Ebbinghaus on inactive peers: 14-day grace window, λ=0.007/day past grace (half-life ≈99 days), floor at 0.1. Banned peers and genesis-trust-list members are skipped — banning is absolute and the trust list is the operator's explicit floor. Caps the "publish nothing for a year, then a worm" attack pattern. Same consolidation tick as the sweeper. 6 unit tests cover grace, decay curve, banned skip, genesis skip, score floor, and sub-threshold no-op.

Validation

• 15/15 new tests passing
• typecheck clean (tsc --noEmit)
• lint clean (oxlint --type-aware, 0 warnings, 0 errors)
• CI green on d4bfaa9

Deferred to follow-ups

• C.1 — ONNX classifier pass. Architecture is in place via skills.p2p.injectionScanner: "regex" | "off" with "classifier" reserved in the enum. The model itself isn't bundled because picking the right base — StackOne Defender vs. fine-tuned Llama 3.2 1B vs. PromptArmor reference impl — and shipping the binary in the bundle each warrant a dedicated RFC. The existing regex pass at weight: 5+ thresholds catches ≥80% of canonical attacks today (per the Phase A ship gate); the classifier is incremental coverage on borderline cases, not a blocker.
• C.2 — Desktop UI quarantine panel. RPCs all exist (skills.incoming.list / accept / reject / rejectByPeer); the renderer just needs a panel that calls them and surfaces injection-scan severity + capability-block reasons inline. Coordinate with Tauri Phase 2.
• C.3 — Per-skill EXTERNAL_UNTRUSTED_CONTENT marker injection. Today the Spotlighting notice is global (one notice if any active skill is from P2P). Per-skill markers require forking pi-coding-agent's formatSkillsForPrompt. Worth doing alongside any other formatter changes; not worth doing alone.
• B.7-2 — Operator-consent prompt UX. When a provisional-tier skill is blocked but would be admitted with a wallet/shell grant, the operator should see "this skill needs your approval" inline so they can grant on the spot. The notification path is already wired; the consent round-trip (notify → grant → re-evaluate) needs the same UI surface as C.2.

Defense posture (final)

Attack	Layer
Forged peer	Ed25519 (Phase 0)
Tampered bytes	SHA-256 hash (Phase 0)
NL injection in trusted skill	Phase A scanner force-quarantines (both ingest paths)
Worm via compromised key	Phase A reputation feedback + 24h auto-ban + C peer decay for long-dormant keys
Provisional publisher over-claiming	Phase B load-time gate strips skill from active prompt + B.7 inline notification
LLM coaxed into wallet call from no-wallet skill	Phase B.5 runtime enforcer denies at dispatch
Operator forgets stale quarantined skills accumulate	C TTL sweeper auto-rejects after 30d
Compromised peer needs immediate cleanup	C bulk-reject by peer in one RPC call

Phase A through C foundation is shipped end-to-end. Tail items above are filed; happy to take PRs against any of them.

[OhhJJ]

This is a good call, and honestly feels like a missing layer in the current model.

Right now, passing prompt-injection scanning effectively grants a skill ambient authority, which is a much bigger trust leap than it looks. Even a “truthful but malicious” skill becomes dangerous if the runtime doesn’t constrain what it can actually do.

The capability-based approach makes sense here. Declaring required capabilities in frontmatter is useful, but the key point is enforcement at runtime — otherwise it’s just documentation, not a control boundary.

The default least-privilege profile for mesh-ingested skills also feels like the right baseline. Gating high-risk capabilities (wallet, shell, arbitrary network, broader filesystem access) behind explicit approval at first invocation strikes a good balance between safety and usability.

On the open questions:

• Consolidating with allowed-tools into a single capability model seems preferable to avoid drift and confusion.
• Per-skill vs per-publisher trust is tricky — inheriting elevated defaults from verified publishers could help UX, but it weakens the security model unless verification is very strong. Leaning per-skill by default feels safer.
• For sandboxing, a worker-thread model is probably sufficient for most cases, but having a path to process-level isolation for stronger guarantees is worth planning early, even if not implemented immediately.

Overall, this complements injection scanning well: don’t just try to detect bad intent — make it materially harder for any skill to act on it.