shrike-guard 4.0.5 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## [4.2.0] - 2026-09-17
+
+### Added
+- **An unmapped tool can still be judged by its name.** A tool with no
+  mapping has no readable surface, so the content plane has nothing to say
+  about it. The authorization plane still does: the operator's declared scope
+  judges a tool by NAME, which is the one thing every tool call has.
+  `onUnmapped: 'authorize'` sends the tool's name (and nothing else) to the
+  backend, so a tool outside the allowlist is refused even though nothing
+  read what it was carrying, and an expired or exhausted scope holds it. The
+  permit is narrower than a mapped tool's and the record says so: the
+  decision's surface is `authorization`, never a scanned surface. A client
+  too old to ask fails according to `failMode` rather than assuming.
+  `ShrikeGuard.authorizeTool` is the call underneath.
+- **Observe-plane scans say so.** `ShrikeGuard.scan` takes an options argument
+  carrying `plane`, and `observePrompt` sends `plane: 'observe'`. A verdict on a prompt nobody is
+  gated on is advice: it is recorded and returned, and the model still reads
+  the note, but it is no longer filed as an action that was stopped.
+
+- **Framework starters over one core.** `govern.ts` is the framework-free
+  core of a governed agent: a tool mapping table (`mapTool`, `exempt`),
+  `evaluate` (every scan a tool call needs, stopping at the first refusal,
+  into one `Outcome`: allow, warn, hold or deny, with the message written
+  for the model), `observePrompt` (never blocks), `requestScope` (the
+  backend decides; a widening is refused unless an operator grants it), and
+  the record (`decisions`, `onDecision`). Each starter is a subpath and a
+  thin translation of one framework's hooks:
+  - `shrike-guard/claude-agent` (Claude Agent SDK): `PreToolUse` and
+    `UserPromptSubmit` hooks, an in-process MCP tool. Ships mappings for the
+    SDK's built-in tools. ESM, as the SDK is.
+  - `shrike-guard/openai-agents` (OpenAI Agents SDK): a tool input guardrail
+    attached to every function tool (a refused call is answered with
+    `rejectContent`, so the model reads the reason as the tool's output), a
+    non-tripping input guardrail for the observe plane, and `request_scope`
+    as a function tool.
+  - `shrike-guard/ai` (Vercel AI SDK): `governTools` wraps each tool's
+    `execute` so a refused call returns the reason as the tool's result, a
+    language-model middleware whose `transformParams` scans a new user
+    message and prepends a note, and `request_scope` as an AI SDK tool.
+  - `shrike-guard/langchain` (LangChain `createAgent` and LangGraph): an
+    agent middleware whose `wrapToolCall` answers a refused call with a
+    `ToolMessage`, or `governTools` for a hand-built `ToolNode`, and
+    `request_scope` as a LangChain tool.
+- **Tool mappings.** A tool is a surface (`command`, `file`, `file_path`,
+  `sql`, `web_search`, `rag_context`, `a2a_message`, `agent_card`, or
+  `none`) and the argument that carries its payload. A tool with no mapping
+  is refused with a message that says how to map it (`onUnmapped: 'deny'`),
+  or allowed and recorded (`'allow'`), or has its arguments scanned as text
+  (`'scan'`), or judged by name alone (`'authorize'`, see below). The Claude
+  Agent SDK starter defaults to `'authorize'`, and its hook now sees every
+  tool the agent can call rather than only the mapped ones, because a tool
+  with no reader is exactly the one whose authorization nobody has checked.
+  Pass an explicit tool list to `hooksFor` to narrow the matcher.
+- **A conformance suite.** `tests/unit/frameworks.test.ts` drives every
+  starter through the same table (allow, warn, block, hold, backend down,
+  unmapped, a refused widening); each starter must answer it the same way.
+  The frameworks are optional peer dependencies; the base install is
+  unchanged.
+
+## [4.1.0] - 2026-09-09
+
+### Added
+- **Act-plane scanning: every channel the backend scans is now reachable from
+  the SDK.** The backend has scanned eight specialized content types since the
+  act plane shipped; this SDK exposed four. `scanCommand` — the highest-volume
+  surface, the one an agent hits before every shell-out — had no method at all,
+  so the only way to reach it was to hand-roll an HTTP call or route through the
+  MCP server. New on `ScanClient`:
+  - `scanCommand(command, cwd?)` — shell commands, screened before `exec`.
+    Commands are decomposed, so SQL passed to `psql -c`, `mysql -e`, or a
+    heredoc is scanned as SQL rather than as opaque shell text.
+  - `scanWebSearch(query)` — search queries that acquire attack tooling,
+    credentials, or evasion tradecraft.
+  - `scanRagContext(chunks, query?)` — retrieved context, the standard carrier
+    for indirect prompt injection. Accepts a string or a list of strings.
+  - `scanMcpSchema(name, description, inputSchema?)` — a single MCP tool
+    definition, for tool poisoning in a `tools/list` response. Screened once at
+    registration, not per call.
+- **`content_origin` on `ScanResult`.** Every verdict now says where the scanned
+  content came from: `human_prompt`, `agent_output`, `agent_action`, or
+  `third_party`. This answers the question a verdict alone cannot — was that my
+  prompt, or the agent acting on its own — which decides who a refusal message
+  is addressed to. Exported alongside it: the `ContentOrigin` type and
+  `attributableToOperator(origin)`, true only for `human_prompt`. Unknown content
+  types resolve to `agent_action`, never to `human_prompt`.
+- **Act-plane parity test** (`tests/unit/actplane-parity.test.ts`). Iterates the
+  canonical channel list and fails when a channel has no SDK method. The gap
+  above went unnoticed because "the backend supports it" and "a customer can
+  call it" were two facts with nothing comparing them. This is the comparison.
+
+- **Per-request session identity — `sessionId`/`agentId` on `ScanClientOptions`,
+  and `forSession()`.** Session identity is the key the backend accumulates
+  multi-turn risk against, so it has to mean one unit of work: one agent run,
+  one conversation, one user's request. It defaults to a process-wide id, which
+  suits a CLI or a worker but not a server serving many end users, where every
+  user would share one risk score and one user's refusal would count against
+  the next user's action. `forSession()` returns a view that shares the parent's
+  rate limiter, so deriving one per request is cheap and cannot multiply your
+  rate budget:
+
+  ```ts
+  const guard = new ScanClient({ apiKey: KEY });   // once, at startup
+
+  app.post('/act', async (req, res) => {           // per request
+    const scoped = guard.forSession(req.session.id);
+    const verdict = await scoped.scanCommand(req.body.command);
+  });
+  ```
+
+  The process-wide default is unchanged when nothing is supplied, so
+  single-agent callers keep multi-turn correlation; the SDK now warns once when
+  it is in force. Silence that with `SHRIKE_SUPPRESS_SESSION_WARNING=1`.
+
+  `evaluateRotation`'s caller-owned branch now applies: a caller that supplies
+  its own session id receives a rotation recommendation rather than a
+  module-owned rotation.
+
+### Fixed
+- **`content_origin` was computed by the backend and dropped before the caller.**
+  The response sanitizer is an allow-list, and the field was never added to
+  `PRESERVED_GOVERNANCE_FIELDS`, so it was serialized by the server and stripped
+  one layer before the application. It now survives sanitization.
+- **Session identity could not be configured.** Every scan in a process used one
+  generated session id, so a server scanning on behalf of more than one person
+  placed all of them in one session. See `sessionId` / `forSession()` above.
+
 ## [4.0.5] - 2026-08-31
 
 ### Added

package/README.md

@@ -6,6 +6,8 @@
 
 **Shrike Guard** is a TypeScript SDK for the [Shrike](https://shrikesecurity.com) platform — AI governance for every AI interaction. It wraps OpenAI, Anthropic (Claude), and Google Gemini clients to automatically evaluate all prompts against policy before they reach the LLM. Whether you're governing a customer-facing chatbot, securing developer AI tools, or managing autonomous agent actions — the same 9-layer cognitive pipeline evaluates every interaction.
 
+It scans two different things. **Prompts and responses**, which is what a guardrail library normally means. And **agent actions** — the shell command, the SQL query, the web search, the retrieved document, the MCP tool definition — screened before they run, which is where an autonomous agent actually causes harm. See [Scanning agent actions](#scanning-agent-actions-shell-commands-sql-web-search-rag-mcp-tools).
+
 ## Features
 
 - **Drop-in replacement** for OpenAI, Anthropic, and Gemini clients
@@ -15,6 +17,8 @@
   - Jailbreak attempts
   - SQL injection
   - Path traversal
+- **Pre-execution scanning for agent actions**: shell commands, SQL, file writes, web searches, RAG context, agent-to-agent messages, agent cards, and MCP tool schemas
+- **Content provenance** (`content_origin`): every verdict says whether a human typed it, the model wrote it, the agent is about to do it, or it arrived from outside
 - **Fail-safe modes**: Defaults to fail-closed (Zero Trust posture); opt into fail-open explicitly when availability outranks enforcement
 - **CJS + ESM**: Dual build via tsup, works everywhere
 - **Subpath imports**: `shrike-guard/openai`, `shrike-guard/anthropic`, `shrike-guard/gemini`
@@ -167,6 +171,50 @@ const client = new ShrikeOpenAI({
 });
 ```
 
+### Sessions: one per unit of work, not one per process
+
+Shrike correlates risk across a session. After a refusal, later actions in the
+same session are held until the session recovers. That is the multi-turn
+defence, and it means the session id has to mean one unit of work: one agent
+run, one conversation, one user's request.
+
+By default the SDK scans under one id for the whole process. That suits a CLI,
+a worker, or a single agent. It does not suit a server that scans on behalf of
+many end users, because every user then shares one risk score, and one user's
+refusal counts against the next user's action.
+
+Build one client at startup and derive a per-request view from it. The view
+shares the rate limiter, so it costs nothing to make one per request and it
+cannot multiply your rate budget:
+
+```typescript
+import { ScanClient } from 'shrike-guard';
+
+const guard = new ScanClient({ apiKey: 'shrike-...' });   // once, at startup
+
+app.post('/act', async (req, res) => {                     // per request
+  const scoped = guard.forSession(req.session.id);
+  const verdict = await scoped.scanCommand(req.body.command);
+  if (verdict.refuse_tier !== 'allow') {
+    ...
+  }
+});
+```
+
+Or pin the identity at construction when one client serves one unit of work:
+
+```typescript
+const client = new ScanClient({ apiKey: 'shrike-...', sessionId: 'job-42', agentId: 'ingest' });
+```
+
+`agentId` is separate on purpose: it names *which agent* a scope is enforced
+against and who an incident is attributed to. Set it when one process drives
+several distinct agents.
+
+The SDK warns once per process when it is scanning under the shared default.
+Set `SHRIKE_SUPPRESS_SESSION_WARNING=1` to silence it once you have decided
+the default is what you want.
+
 ### Local and self-hosted LLMs
 
 Shrike governs the model you point it at — it does not have to be a hosted
@@ -208,31 +256,197 @@ const client = new ShrikeGemini({
 The prompt still leaves your process to reach the Shrike backend for scanning;
 the *model call* stays on your local/self-hosted endpoint.
 
-## SQL and File Scanning
+## Scanning agent actions (shell commands, SQL, web search, RAG, MCP tools)
+
+Scanning the prompt protects the model. It does not protect the shell. An agent
+that was never told anything malicious can still be talked into running
+`curl … | sh` by a poisoned README, and the prompt scan has no view of that.
 
-The OpenAI client also provides standalone scanning for SQL queries and file paths:
+`ScanClient` exposes a method per action channel. Call the one that matches
+what the agent is about to do, before it does it:
+
+| Channel | Method | Screens for |
+|---|---|---|
+| Shell command | `scanCommand(command, cwd?)` | destructive commands, data exfiltration, credential dumps, embedded SQL injection |
+| SQL query | `scanSql(query, database?, allowDestructive?)` | SQL injection, unauthorized destructive statements |
+| File path | `scanFile(path)` | path traversal, writes outside the working tree |
+| File content | `scanFile(path, content)` | secrets, credentials, PII before they land on disk |
+| Web search | `scanWebSearch(query)` | searches that acquire attack tooling, credentials, or evasion tradecraft |
+| RAG context | `scanRagContext(chunks, query?)` | indirect prompt injection in retrieved documents |
+| Agent message | `scanA2AMessage(message, options?)` | instructions smuggled between agents |
+| Agent card | `scanAgentCard(card, verifySignature?)` | capability misrepresentation in A2A discovery |
+| MCP tool schema | `scanMcpSchema(name, description, inputSchema?)` | tool poisoning in `tools/list` responses |
 
 ```typescript
-import { ShrikeOpenAI } from 'shrike-guard/openai';
+import { ScanClient } from 'shrike-guard';
 
-const client = new ShrikeOpenAI({
-  apiKey: 'sk-...',
-  shrikeApiKey: 'shrike-...',
-});
+const scanner = new ScanClient({ apiKey: 'shrike-...' });
+
+// Before shelling out
+const cmd = await scanner.scanCommand('psql -c "SELECT * FROM users"', '/srv/app');
+if (!cmd.safe) throw new Error(`Refused: ${cmd.reason}`);
+
+// Before querying
+const sql = await scanner.scanSql('SELECT * FROM users WHERE id = $1', 'postgres');
+
+// Before writing
+const write = await scanner.scanFile('/tmp/config.py', 'api_key = "sk-..."');
+
+// Before searching the web
+const search = await scanner.scanWebSearch('sql injection prevention owasp');
+```
+
+A shell command is not one thing. `scanCommand` decomposes it, so SQL passed to
+`psql -c`, `mysql -e`, or a heredoc is scanned as SQL rather than as an opaque
+string of shell text.
+
+### Indirect prompt injection in RAG pipelines
+
+Retrieved chunks are text somebody else wrote. They are the standard carrier for
+indirect prompt injection: the user asks nothing unusual, the document tells the
+model what to do, and the model complies. Scan on the way in, not after the
+model has acted:
+
+```typescript
+const chunks = await vectorStore.similaritySearch(userQuery, 5);
+
+const verdict = await scanner.scanRagContext(
+  chunks.map((c) => c.pageContent),
+  userQuery,
+);
+
+if (!verdict.safe) {
+  // The retrieved context is hostile, not the user's question.
+  console.warn(`Poisoned context: ${verdict.reason}`);
+}
+```
+
+### MCP tool poisoning
+
+An MCP tool description is read by the model as guidance. A hostile server can
+put instructions in the `description` field of a tool that never executes, and
+the agent will act on them at registration time. Screen every entry of a
+`tools/list` response from a server you do not control:
 
-// Scan SQL queries for injection attacks
-const sqlResult = await client.scanSql('SELECT * FROM users WHERE id = 1');
-if (!sqlResult.safe) {
-  console.log(`SQL threat: ${sqlResult.reason}`);
+```typescript
+const { tools } = await mcpClient.listTools();
+
+for (const tool of tools) {
+  const verdict = await scanner.scanMcpSchema(
+    tool.name,
+    tool.description ?? '',
+    tool.inputSchema,
+  );
+  if (!verdict.safe) {
+    console.warn(`Not registering ${tool.name}: ${verdict.reason}`);
+    continue;
+  }
+  register(tool);
 }
+```
+
+Screening happens once per tool at registration, not on every call.
 
-// Scan file paths for path traversal
-const fileResult = await client.scanFile('/app/data/output.csv');
+## Governing an agent: framework starters
 
-// Scan file content for secrets
-const contentResult = await client.scanFile('/tmp/config.py', 'api_key = "sk-..."');
+Shrike governs an agent from inside its tool loop: every tool call is judged
+before it executes, the person's prompt is scanned on the way in and never
+blocked, and the agent gets one tool, `request_scope`, to ask for more than
+it holds. One framework-free core carries that behaviour; each starter is a
+thin translation of one framework's hooks. Every starter is a subpath of this
+package, and each framework is an optional peer dependency (`zod` too).
+
+| Framework | Import | What it wires |
+|---|---|---|
+| Claude Agent SDK | `shrike-guard/claude-agent` | `PreToolUse` and `UserPromptSubmit` hooks, an in-process MCP tool |
+| OpenAI Agents SDK | `shrike-guard/openai-agents` | a tool input guardrail on every function tool, a non-tripping input guardrail, a function tool |
+| Vercel AI SDK | `shrike-guard/ai` | wrapped `execute` on every tool, a language-model middleware for the observe plane, an AI SDK tool |
+| LangChain `createAgent` / LangGraph | `shrike-guard/langchain` | an agent middleware (`wrapToolCall`, `beforeAgent`) or wrapped tools for a `ToolNode` |
+
+Every starter has the same shape. Build it, map your tools to Shrike's
+surfaces, hand it to the framework:
+
+```ts
+import { Agent } from '@openai/agents';
+import { ScanClient } from 'shrike-guard';
+import { govern } from 'shrike-guard/openai-agents'; // or claude-agent, ai, langchain
+
+const guard = new ScanClient({ apiKey: 'shrike-...' });
+const gov = govern(guard, { agentId: 'invoice-agent' });
+await gov.declare(['file_path', 'file_content', 'sql'], 'Reconcile Q3 vendor invoices');
+
+gov.mapTool('run_query', { surface: 'sql', arg: 'query' });
+gov.mapTool('save_report', { surface: 'file', pathArg: 'path', contentArg: 'text' });
+gov.exempt('get_time');
+
+const agent = gov.governAgent(new Agent({ name: 'invoices', tools: [runQuery, saveReport, getTime] }));
+```
+
+A tool mapping says which surface a tool is and which argument carries the
+payload: `command` (with an optional `cwdArg`), `file` (a path and the
+content written to it), `file_path`, `sql`, `web_search`, `rag_context`,
+`a2a_message`, `agent_card`, or `none` for a tool allowed without a scan.
+The Claude Agent SDK starter ships mappings for the SDK's built-in tools;
+the others govern the tools you write, so they need your mappings.
+
+A tool with no mapping is refused, with a message that says how to map it,
+until you map it or choose what an unmapped tool gets. `onUnmapped: 'authorize'` asks the
+backend whether the agent may call it at all: the arguments stay put, and the
+tool's NAME goes up, where the operator's declared scope answers. A tool
+outside the allowlist is refused by name even though nothing read what it was
+carrying, and an expired or exhausted scope holds it. That permit is narrower
+than a mapped tool's and the record says so, with the decision's surface
+recorded as `authorization`. `'allow'` records the call and moves on without
+asking; `'scan'` sends the arguments to be read as text.
+
+What the model sees is the same everywhere: an allowed call runs; a warned
+call runs with the advisory; a blocked call does not run and the model gets
+the reason; a held call (an action outside the declared scope) does not run
+and the model gets the reason, the recovery, and the instruction to ask with
+`request_scope` and then stop. An action Shrike could not check is refused
+(`failMode: 'closed'`). Every decision lands on `gov.decisions` and on your
+`onDecision` callback, with the axis that objected.
+
+Where a framework can route a hold to a person, `onHold: 'ask'` does that
+(the Claude Agent SDK's `canUseTool`). Where it cannot, a hold is answered
+like a refusal and the model is told an operator can grant it on the Shrike
+Agents screen. The `claude-agent` subpath is ESM, because the Claude Agent
+SDK is.
+
+## Who is answerable: `content_origin`
+
+Every verdict carries `content_origin`, which says where the scanned content
+came from. It answers the question a verdict alone cannot: *was that my prompt,
+or the agent acting on its own?*
+
+| Value | Meaning |
+|---|---|
+| `human_prompt` | the operator typed it |
+| `agent_output` | the model generated it |
+| `agent_action` | the agent is about to do it (every act-plane channel) |
+| `third_party` | it arrived from outside: a tool result, a retrieved document, a peer agent |
+
+```typescript
+import { attributableToOperator } from 'shrike-guard';
+
+const verdict = await scanner.scanRagContext(chunks);
+
+if (!verdict.safe) {
+  if (attributableToOperator(verdict.content_origin)) {
+    showUser(`Your request was blocked: ${verdict.reason}`);
+  } else {
+    // The agent poisoned its own context. Telling the user "your request
+    // was blocked" would be both wrong and unhelpful.
+    log.warn('agent-side refusal', verdict.reason);
+    retryWithCleanContext();
+  }
+}
 ```
 
+Unknown content types resolve to `agent_action`, never to `human_prompt`:
+attributing an unattributable action to the operator is the one error that is
+never safe to make by default.
+
 ## Error Handling
 
 ```typescript
@@ -298,6 +512,8 @@ export OPENAI_API_KEY="sk-..."
 export ANTHROPIC_API_KEY="sk-ant-..."
 export SHRIKE_API_KEY="shrike-..."
 export SHRIKE_ENDPOINT="https://your-shrike-instance.com"
+export SHRIKE_AGENT_ID="ingest"                 # names this process's agent; see Sessions
+export SHRIKE_SUPPRESS_SESSION_WARNING=1        # once you have decided the shared session is right
 ```
 
 ## Scope and Limitations
@@ -308,13 +524,23 @@ export SHRIKE_ENDPOINT="https://your-shrike-instance.com"
 | Multi-modal text content | Image/audio content |
 | SQL queries | Non-chat API calls |
 | File paths and content | |
+| Shell commands | |
+| Web search queries | |
+| Retrieved RAG context | |
+| Agent-to-agent messages and agent cards | |
+| MCP tool schemas | |
 
-### Why Input-Only Scanning?
+### Why Pre-Execution Scanning?
 
-Shrike Guard focuses on **pre-flight protection** — blocking malicious prompts BEFORE they reach the LLM. This:
+Shrike Guard focuses on **pre-flight protection** — evaluating a prompt before it
+reaches the LLM, and an action before it runs. This:
 - Prevents prompt injection attacks at the source
 - Has zero latency impact on LLM responses
-- Catches the vast majority of threats at the input layer
+- Puts the decision point before the side effect, where refusing still costs nothing
+
+An action already taken cannot be un-taken by detecting it afterwards. That is the
+distinction between this and after-the-fact monitoring: the verdict arrives while
+refusing is still free.
 
 ## Other Integration Surfaces
 
@@ -332,22 +558,39 @@ Shrike Guard is one of several ways to integrate with the Shrike platform:
 | Scenario | How Shrike Guard Helps |
 |---|---|
 | **Customer chatbot** | Wrap your OpenAI/Anthropic client. Every user message scanned for injection before it reaches the model. |
-| **Internal RAG pipeline** | Scan retrieved context + user queries for PII leakage and injection attempts. |
-| **AI coding assistant** | Scan prompts for proprietary code patterns before they leave your environment. |
-| **Agent orchestration** | Scan every tool call and LLM request in your LangChain/CrewAI/AutoGen pipeline. |
-
-## Alternatives
-
-Looking for an AI security SDK? Here's how Shrike Guard compares:
-
-| Feature | Shrike Guard | Lakera | Prompt Armor |
-|---|---|---|---|
-| Drop-in OpenAI/Anthropic/Gemini wrapper | Yes | No | No |
-| 9-layer cognitive pipeline | Yes | Limited | Limited |
-| PII detection + redaction | Yes | Partial | No |
-| Session correlation | Yes (Pro+) | No | No |
-| Free tier (no API key) | Yes | No | No |
-| Open source client | Yes (Apache 2.0) | No | No |
+| **Coding agents that shell out** | `scanCommand` before every `exec`. Destructive commands, exfiltration, and SQL smuggled through `psql -c` are caught before the process starts. |
+| **Internal RAG pipeline** | `scanRagContext` on retrieved chunks for indirect prompt injection, plus PII leakage on the query. |
+| **MCP clients** | `scanMcpSchema` on every `tools/list` entry from a server you do not control, to catch tool poisoning at registration. |
+| **Multi-agent systems** | `scanA2AMessage` and `scanAgentCard` for instructions smuggled between agents. |
+| **Agent orchestration** | Scan every tool call and LLM request in your LangChain/LangGraph/CrewAI/AutoGen pipeline. |
+
+## How This Differs From a Prompt Scanner
+
+If you are evaluating TypeScript or JavaScript AI security SDKs, this is the
+distinction worth testing against your own workload.
+
+Most guardrail libraries answer one question: **is this text hostile?** They read
+the prompt, and sometimes the response. That is necessary, and Shrike Guard does
+it through a 9-layer cascade with PII redaction and multi-turn session
+correlation.
+
+But an autonomous agent does not cause harm by saying something. It causes harm
+by *doing* something: running a command, writing a file, querying a database,
+calling a tool. Shrike Guard scans those too, before they execute:
+
+- **A verdict per action channel** — shell commands, SQL, file writes, web
+  searches, RAG context, agent-to-agent messages, agent cards, MCP tool schemas.
+  See [Scanning agent actions](#scanning-agent-actions-shell-commands-sql-web-search-rag-mcp-tools).
+- **Pre-execution, not after the fact.** The verdict arrives while refusing is
+  still free. An action already taken cannot be un-taken by detecting it.
+- **Provenance on every verdict** (`content_origin`) — whether a human typed it,
+  the model wrote it, the agent is about to do it, or it arrived from outside.
+- **A governance contract, not just a boolean** — `refuse_tier`
+  (allow / warn / require_approval / block), a `recovery` block telling the agent
+  how to proceed legitimately, and `session_state`. Present on safe verdicts too.
+- **Drop-in wrappers** for OpenAI, Anthropic, and Gemini, so the prompt-scanning
+  half needs no code changes.
+- **Free tier with no API key**, and an Apache 2.0 client you can read.
 
 ## License
 

package/dist/ai/index.d.mts

@@ -0,0 +1,60 @@
+import { ToolSet, Tool, LanguageModelMiddleware } from 'ai';
+import { G as Governance$1, a as Guard, b as GovernanceOptions } from '../govern-rW3QdqsQ.mjs';
+export { D as Decision, O as Outcome, T as ToolMapping } from '../govern-rW3QdqsQ.mjs';
+import { S as ScanClient } from '../scanner-U1SygSM2.mjs';
+
+/**
+ * Govern an agent built with the Vercel AI SDK (`ai`).
+ *
+ * ```ts
+ * import { generateText, wrapLanguageModel } from 'ai';
+ * import { ScanClient } from 'shrike-guard';
+ * import { govern } from 'shrike-guard/ai';
+ *
+ * const guard = new ScanClient({ apiKey: KEY });
+ * const gov = govern(guard, { agentId: 'invoice-agent' }).mapTool('runQuery', { surface: 'sql', arg: 'query' });
+ * const result = await generateText({
+ *   model: wrapLanguageModel({ model, middleware: gov.middleware }),
+ *   tools: gov.governTools({ runQuery, saveReport, request_scope: gov.tool }),
+ *   prompt,
+ * });
+ * ```
+ *
+ * A thin adapter over `shrike-guard`'s framework-free core (`govern.ts`).
+ *
+ * The act plane wraps each tool's `execute`: Shrike judges the call through
+ * the tool's mapping before the inner `execute` runs. A refused or held call
+ * never runs; the wrapper returns Shrike's reason and the recovery as the
+ * tool's result, so the model reads why and what to do next. Tools with no
+ * mapping are refused by default (`onUnmapped: 'deny'`).
+ *
+ * The observe plane is a language-model middleware whose `transformParams`
+ * scans the latest user message on the way in, once per message, and never
+ * blocks. A finding is prepended to the prompt as a system message.
+ *
+ * `request_scope` is available as `gov.tool`; add it to the tool set. A held
+ * action is answered like a refusal whatever `onHold` says; use the SDK's
+ * `needsApproval` if the run itself should pause.
+ *
+ * Requires `ai` and `zod`.
+ */
+
+/** The latest user message's text in a language-model prompt. */
+declare function lastUserText(prompt: unknown): string;
+declare class Governance extends Governance$1 {
+    private toolCache?;
+    private middlewareCache?;
+    private lastObserved?;
+    /** Wrap each tool's `execute` so Shrike judges its calls. Returns a new tool set. */
+    governTools<T extends ToolSet>(tools: T): T;
+    /** `request_scope` as an AI SDK tool; add it to your tool set under that name. */
+    get tool(): Tool;
+    /** Scan a new user message in a prompt, once. Returns the note to prepend, or empty. */
+    observePromptMessages(prompt: unknown): Promise<string>;
+    /** The observe-plane middleware for `wrapLanguageModel({ model, middleware })`. */
+    get middleware(): LanguageModelMiddleware;
+}
+/** Build the governance for one agent. */
+declare function govern(guard: Guard | ScanClient, options: GovernanceOptions): Governance;
+
+export { Governance, GovernanceOptions, govern, lastUserText };

package/dist/ai/index.d.ts

@@ -0,0 +1,60 @@
+import { ToolSet, Tool, LanguageModelMiddleware } from 'ai';
+import { G as Governance$1, a as Guard, b as GovernanceOptions } from '../govern-R_Lx6i1l.js';
+export { D as Decision, O as Outcome, T as ToolMapping } from '../govern-R_Lx6i1l.js';
+import { S as ScanClient } from '../scanner-U1SygSM2.js';
+
+/**
+ * Govern an agent built with the Vercel AI SDK (`ai`).
+ *
+ * ```ts
+ * import { generateText, wrapLanguageModel } from 'ai';
+ * import { ScanClient } from 'shrike-guard';
+ * import { govern } from 'shrike-guard/ai';
+ *
+ * const guard = new ScanClient({ apiKey: KEY });
+ * const gov = govern(guard, { agentId: 'invoice-agent' }).mapTool('runQuery', { surface: 'sql', arg: 'query' });
+ * const result = await generateText({
+ *   model: wrapLanguageModel({ model, middleware: gov.middleware }),
+ *   tools: gov.governTools({ runQuery, saveReport, request_scope: gov.tool }),
+ *   prompt,
+ * });
+ * ```
+ *
+ * A thin adapter over `shrike-guard`'s framework-free core (`govern.ts`).
+ *
+ * The act plane wraps each tool's `execute`: Shrike judges the call through
+ * the tool's mapping before the inner `execute` runs. A refused or held call
+ * never runs; the wrapper returns Shrike's reason and the recovery as the
+ * tool's result, so the model reads why and what to do next. Tools with no
+ * mapping are refused by default (`onUnmapped: 'deny'`).
+ *
+ * The observe plane is a language-model middleware whose `transformParams`
+ * scans the latest user message on the way in, once per message, and never
+ * blocks. A finding is prepended to the prompt as a system message.
+ *
+ * `request_scope` is available as `gov.tool`; add it to the tool set. A held
+ * action is answered like a refusal whatever `onHold` says; use the SDK's
+ * `needsApproval` if the run itself should pause.
+ *
+ * Requires `ai` and `zod`.
+ */
+
+/** The latest user message's text in a language-model prompt. */
+declare function lastUserText(prompt: unknown): string;
+declare class Governance extends Governance$1 {
+    private toolCache?;
+    private middlewareCache?;
+    private lastObserved?;
+    /** Wrap each tool's `execute` so Shrike judges its calls. Returns a new tool set. */
+    governTools<T extends ToolSet>(tools: T): T;
+    /** `request_scope` as an AI SDK tool; add it to your tool set under that name. */
+    get tool(): Tool;
+    /** Scan a new user message in a prompt, once. Returns the note to prepend, or empty. */
+    observePromptMessages(prompt: unknown): Promise<string>;
+    /** The observe-plane middleware for `wrapLanguageModel({ model, middleware })`. */
+    get middleware(): LanguageModelMiddleware;
+}
+/** Build the governance for one agent. */
+declare function govern(guard: Guard | ScanClient, options: GovernanceOptions): Governance;
+
+export { Governance, GovernanceOptions, govern, lastUserText };