feat: Add Sensitivity Ratchet hook for irreversible permission narrowing

[mattyopon]

---

Description

This is a proposal to add documentation for a community-maintained hook integration that uses CrewAI's existing register_before_tool_call_hook API to implement a session-scoped permission-narrowing pattern for LLM agents.

It is explicitly not a novel research contribution — the underlying idea has ~50 years of formal security precedent (Denning 1976, Biba 1977) and several recent AI-agent-specific implementations published in 2025–2026 (see Related work below). The value proposition is that it gives a CrewAI user a 10-line-install of this pattern without having to wire up Fides, AIP, or the Agent Governance Toolkit themselves.

The threat model

Two recent real-world CVEs illustrate the class of attack this pattern addresses:

• EchoLeak (CVE-2025-32711, M365 Copilot, zero-click prompt injection via email; disclosed June 2025). A compromised prompt causes the agent to read confidential user data and then write it to an attacker-controlled channel.
• ForcedLeak (CVSS 9.4, Salesforce Agentforce, indirect prompt injection via Web-to-Lead form; disclosed September 2025). Same structural pattern: indirect injection → read sensitive CRM data → write to attacker-controlled URL.

In both cases the attacker exploits sensitivity mixing: the agent has legitimate read access to high-sensitivity data and legitimate write access to a lower-sensitivity channel. Neither capability is dangerous in isolation; the danger is in their composition at the wrong moment.

The pattern (not the novel idea — the practical hook)

The pattern is monotonic capability narrowing: once an agent touches data at a given sensitivity level within a session, its write/delete/execute scopes are permanently reduced for the rest of that session. This is the Biba integrity model (1977) applied to LLM tool calls.

The agent-iam-ratchet package (PyPI, GitHub, MIT) already includes a CrewAI integration using register_before_tool_call_hook:

from agent_iam_ratchet import RatchetSession, Sensitivity
from agent_iam_ratchet.crewai import install_ratchet_hooks

session = RatchetSession(scopes=["read:*", "write:*", "delete:*"])

cleanup = install_ratchet_hooks(
    session=session,
    sensitivity_map={"search_confidential_db": Sensitivity.CONFIDENTIAL},
    on_blocked=lambda tool, s: print(f"BLOCKED: {tool}"),
)

crew.kickoff()
cleanup()

It uses only public CrewAI hook APIs and has no dependency on private CrewAI internals.

Related work (honest prior art)

The ratchet/attenuation idea in this space already has substantial coverage. agent-iam-ratchet is not positioned as novel against any of these; it's a smaller, more opinionated CrewAI-specific alternative.

The pattern builds on ~50 years of formal security precedent (Denning 1976 lattice model, Biba 1977 integrity model, object-capability attenuation, Biscuit tokens). In the AI-agent space specifically:

Work	Level	agent-iam-ratchet positioning
Microsoft Fides (May 2025)	Planner-level IFC, formal model, AgentDojo eval	Fides has formal guarantees; we offer a simpler hook-level alternative
AIP / IBCTs (March 2026, IETF draft)	Token-level scope attenuation, multi-hop delegation	AIP handles cross-agent chains; we handle single-session
MS Agent Governance Toolkit (April 2026)	Full-stack governance, 10/10 OWASP, <0.1ms p99	AGT is the full stack; we're one pattern at hook level
OWASP Agentic AI Top 10 (Dec 2025)	ASI02 "capability sandboxing"	We implement one instance of this mitigation

What I'm actually proposing for CrewAI

Given the above, not a code contribution to core. The concrete proposal is:

1. A new page under docs/en/learn/ — for example, sensitivity-ratchet.mdx or more honestly capability-narrowing-patterns.mdx — that:

   • Explains the monotonic-narrowing pattern from Denning/Biba at a practitioner level
   • Shows how to implement it in CrewAI using the existing register_before_tool_call_hook API
   • Lists agent-iam-ratchet, Fides, AIP, and AGT as community / external options a CrewAI user can choose from, with honest strengths and weaknesses of each
   • Is explicitly tagged as community content, not built-in

2. No changes to CrewAI core code. The existing hook API is already sufficient.

3. No dependency addition. agent-iam-ratchet stays external.

I can open this as a docs-only PR whenever a maintainer says the framing is acceptable.

Edit note (2026-04-10)

The original version of this issue (filed 2026-04-03) framed agent-iam-ratchet as a novel approach to defend against EchoLeak/ForcedLeak. After @aeoess's comment and a subsequent prior-art sweep I realized I had not adequately searched for existing AI-agent IFC work. This revised body removes the novelty framing and repositions the proposal as a docs-only community integration alongside Fides, AIP, AGT, Biscuit, and Pidlisnyi's work. The original text is preserved in the issue history.

[aeoess]

The ratchet is the right primitive. Once an agent touches sensitive data, allowing it to write to a lower-sensitivity channel is an information flow violation that no amount of post-hoc auditing can undo.

This is a specific instance of a general principle: monotonic authority narrowing. The formal model (product lattice over authority facets) is in this paper — the key insight is that sensitivity level is just one facet. Spend limits, scope boundaries, temporal windows, and reputation thresholds all follow the same ratchet pattern: they can tighten but never loosen during a session.

The before_tool_call hook integration is clean. A few things worth considering as this matures:

Sensitivity inheritance across delegation. When agent A delegates to agent B, B should inherit A's current sensitivity floor, not start fresh. Otherwise a compromised agent can launder sensitive data through a sub-agent. The ratchet needs to propagate through delegation chains, not just within a single session.

Cryptographic evidence. The ratchet state should be signed. If an agent claims "I haven't read any CONFIDENTIAL data," there should be a tamper-evident record proving that claim. Otherwise the ratchet is enforced on the honor system — the agent's runtime says it's clean, but there's no external verification.

Recovery. A permanent ratchet within a session is correct. But across sessions, the agent needs a way to start clean — otherwise one accidental touch of sensitive data permanently disables the agent. Session boundaries with signed attestation of the ratchet state at session end would solve this.

The CVEs you cited (EchoLeak, ForcedLeak) are exactly the attack class that motivated the APS DataEnforcementGate — runtime access control that checks data sensitivity, agent scope, and delegation ceiling before every data operation. The ratchet pattern is complementary: the gate prevents unauthorized access, the ratchet prevents authorized-but-leaked exfiltration.

[pshkv]

The EchoLeak/ForcedLeak pattern maps directly to the formal "capability escalation" problem in object-capability security: an agent with read access to high-sensitivity data and write access to a low-sensitivity channel can construct an implicit exfiltration path even when neither individual capability is flagged as dangerous.

Your sensitivity ratchet approach is the right direction. A few notes from building SINT Protocol that handles a similar constraint in physical AI systems:

Why ratcheting works better than taint tracking:

Taint tracking requires following data through every possible copy/transform path — computationally expensive and prone to laundering attacks (encode sensitive data in a format the taint checker doesn't recognize). The ratchet approach avoids this by operating on the capability level, not the data level: once you've used a high-sensitivity read capability, your write capability scope irreversibly narrows. You never need to follow the data.

The formal invariant:

// SINT's attenuation-only delegation captures this:
// scope(token_after_sensitive_read) ⊆ scope(token_before_sensitive_read)
// 
// Concretely: presenting a token that was used to access "confidential" data
// automatically narrows the "write" action set available in the current session

// Pre-read token:
{ actions: ["read", "write"], constraints: { dataClassification: "public" } }

// Post-read (confidential resource accessed):
{ actions: ["read"],  // write capability removed
  constraints: { dataClassification: "confidential" }  // tighter classification
}
// The narrowing is cryptographic — you can't un-narrow it without a new issuance

One addition for physical AI: The sensitivity ratchet needs a safe default for the physical case. When an agent touches sensitive data, you don't just want to narrow write capabilities — you want to escalate the approval tier for any subsequent physical actuation. A robot that reads confidential sensor data and then attempts to publish to /cmd_vel should require T3 approval (explicit human + M-of-N quorum) before actuation. The data sensitivity and the physical consequence are independent ratchet dimensions.

The SINT capability token's constraints field is the enforcement point for this. The packages/policy-gateway module in https://github.com/pshkv/sint-protocol implements the tier-escalation logic. Happy to discuss how the ratchet semantics could be integrated with CrewAI's hook system.

[mattyopon]

Thanks. Your comment pushed me to do a proper prior-art sweep before committing to any of the three improvements. I want to be honest about what I found, because it reframes what agent-iam-ratchet should position itself as.

What I found in the last 11 months

The core idea — once an agent touches high-sensitivity data, its write/delete/execute capabilities narrow irreversibly for the session — has substantial and very recent prior art:

1. Microsoft Fides (arXiv:2505.23643, Costa et al., May 2025, microsoft/fides) implements information-flow control for AI agents with confidentiality and integrity labels, a formal model of dynamic taint-tracking, and an evaluation on AgentDojo. This is the closest academic precedent to what I proposed.

2. Agent Identity Protocol / IBCTs (arXiv:2603.24775, Prakash, March 2026, IETF draft-prakash-aip-00) formalizes scope attenuation across four dimensions (tools, budget, domains, time) with Biscuit+Datalog tokens. Your Point 1 (delegation inheritance) is essentially what IBCTs already provide, with a public-key verifiable chain I had not designed.

3. Microsoft Agent Governance Toolkit (microsoft/agent-governance-toolkit, released 2026-04-02 — one day before I opened this issue, which I did not know at the time) ships deterministic sub-millisecond policy enforcement, Agent Mesh with Ed25519 identity, and execution rings modeled on CPU privilege levels. It claims to cover all 10 OWASP agentic risks.

4. Biscuit tokens (eclipse-biscuit) have provided cryptographic append-only attenuation via Datalog for several years. Your Point 2 (cryptographic evidence) is essentially what Biscuit already does, and AIP adopts it as its chained-mode wire format.

5. Pidlisnyi, "Faceted Authority Attenuation" (zenodo 19260073, 2026-03-27) — the paper you linked — presents a product lattice over seven facets (scope, spend, depth, time, reputation, values, reversibility) with an Agent Passport System implementation in TypeScript. Sensitivity, as I'm using it, is just one of those facets; the general framework already subsumes the specific case.

6. The core mathematical idea is 50 years old: Denning's lattice model of secure information flow (CACM 19(5), 1976; ~2,000 citations) and the Biba integrity model (1977). "Touch high, lose write" is the Biba star-property.

7. OWASP Agentic AI Top 10 (December 2025) lists "capability sandboxing" as the standard mitigation for Tool Misuse (ASI02).

What this means for agent-iam-ratchet

The core concept is well-established. What agent-iam-ratchet can honestly offer is the practical 10-line integration of this pattern into CrewAI, LangChain, and OpenAI Agents SDK — a smaller, more opinionated alternative for practitioners who want session-scoped enforcement without wiring up Fides or AGT.

With that reframing, your three points change shape:

1. Delegation inheritance. You're right that the current hook-based enforcement doesn't propagate across sub-agent delegation. But the right response is not for me to reinvent IBCTs in Python; it's either (a) to use IBCTs / Biscuit tokens as the underlying primitive and document the mapping, or (b) to be explicit that agent-iam-ratchet is a single-session primitive and direct users to AIP or FIDES for multi-agent delegation. I'm leaning toward (b) for v0.x and (a) as a longer-term design option.

2. Cryptographic evidence. Biscuit already provides exactly this. The honest move is to optionally emit Biscuit-compatible tokens from RatchetSession.events rather than invent a parallel signed log. I'll scope that as a [biscuit] extra dependency so the base package stays lean.

3. Recovery across sessions. I still think session-boundary = clean start is the right default, but I now see that the operator policy layer (who can create a new session, under what attestation) is exactly what AGT and AIP are building. The library should not re-implement that; it should document how to plug in.

Concrete next steps (revised)

• Rewrite the README to cite Fides, AIP, AGT, Biscuit, Pidlisnyi, and the Denning/Biba lineage as the actual prior art. Remove any "novel" framing. Position as "practical community integration of existing research."
• Revise the body of this issue to reflect the reframing (I'll edit it shortly).
• Docs-only PR against docs/en/learn/ describing how to use agent-iam-ratchet with CrewAI's existing register_before_tool_call_hook, framed alongside Fides and the Agent Governance Toolkit as related options — not as a novel contribution.
• Draft a comparative evaluation of Fides vs AIP vs AGT vs agent-iam-ratchet on AgentDojo + EchoLeak/ForcedLeak reproductions. If it turns into a short systems-style paper, so be it; if not, it's at minimum a useful blog post for anyone choosing between these options.

After surveying IBCTs and Biscuit, I'm narrowing scope: agent-iam-ratchet will focus on session-scoped hook enforcement and point users to AIP / Biscuit for cross-agent delegation chains, rather than reimplementing what they've already built.

Two genuine questions for you:

1. Is the Pidlisnyi paper your work? The framing of your first comment reads like it might be. I'd like to engage with it substantively and cite it correctly.
2. Given the existence of AGT (released last week), do you still see value in a CrewAI-specific hook integration, or would you recommend I instead contribute to AGT's CrewAI adapter?

Thanks again for the push. This was more useful to me than a positive "lgtm".

[aeoess]

@mattyopon — the prior-art sweep is the right move and the convergence you're seeing is real. One formal connection worth drawing in before you pin down the final shape of agent-iam-ratchet:

The ratchet pattern you proposed is a special case of a more general property: monotonic authority attenuation over a product lattice of authority facets. Sensitivity level is one facet. Spend limits, scope boundaries, temporal windows, trust thresholds, reversibility ceilings, and derivation rights are all facets of the same lattice. Each can only tighten during a session, never loosen. The ratchet rule applies to any facet individually, and the composition rule (intersection, not union) applies across facets.

The formal model is written up here: https://doi.org/10.5281/zenodo.19260073 ("Faceted Authority Attenuation: A Product Lattice Model for Agent Delegation Chains"). Section 3 is the lattice construction, Section 4 is the attenuation proof, Section 5 is the composition theorem. Fides and AIP each formalize one facet (Fides on information flow, AIP on scope/time/budget) — the lattice model is the generalization where you can plug in new facets without redoing the enforcement reasoning.

What this gives agent-iam-ratchet that a single-facet ratchet doesn't:

1. Composition by construction. When you eventually add a spend ratchet or a temporal ratchet alongside the sensitivity ratchet, the enforcement semantics are already defined — intersection of current authority across all active facets, recomputed on every tool call. No per-facet reasoning, no cross-facet exception handling.

2. Delegation inheritance without re-derivation. When agent A delegates to agent B, B's starting authority on every facet is A's current authority, not A's declared authority. The lattice makes this a structural property, not a runtime check.

3. Formal basis for the taint-alternative argument. Your intuition that capability-level ratcheting beats data-level taint tracking is correct, and the paper formalizes why: lattice attenuation is O(1) per tool call (intersect current authority with requested authority) while data taint is O(data lineage depth). The computational argument is secondary to the laundering-resistance argument, but it's useful to have both.

On the three positioning choices for agent-iam-ratchet:

If the goal is the reference implementation of the sensitivity facet, the paper gives you a formal framing that distinguishes "we implement a ratchet" from "we implement the sensitivity projection of the attenuation lattice" — the second framing is more generalizable and makes the relationship to Fides / AIP / APS complementary rather than overlapping.

If the goal is a general ratchet framework, the lattice construction is the right backbone and the sensitivity ratchet becomes the first instantiation, with spend/temporal/scope ratchets as obvious next facets.

If the goal is the CrewAI-specific hook integration, the before_tool_call hook is already the right surface — what matters is making sure the hook consumes a facet-generic authority check, not a sensitivity-specific one, so future facets compose without rewriting the integration.

Happy to contribute facet definitions, test vectors for the lattice intersection, or a composition example with APS delegation chains if any of the three directions are useful. The crewAI integration surface is clean enough that a shared ratchet-facet interface could become a cross-framework primitive without much friction.

One more thing on the ghost-agent edge case from the Microsoft thread: ratcheting also handles ungraceful handoff naturally. A ghost agent's authority doesn't need explicit revocation — the facets it holds are frozen at the moment of termination, and any attempted sub-delegation from a stale chain starts from that frozen floor. The ratchet ensures the floor can only fall, never rise, so a stale chain attenuates itself over time without requiring active maintenance.