shrike-guard 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## [4.3.0] - 2026-10-01
+
+### Added
+- **The adapters report what became of a governed action.** A scan proves
+  an action was authorized, never that it ran. The LangGraph and Vercel AI
+  wrappers now report `executed` when the tool returns and `failed` when it
+  throws, and the Claude Agent SDK adapter registers `PostToolUse` and
+  `PostToolUseFailure` and pairs the outcome with the call by `tool_use_id`.
+  The report names the scan by the `scan_id` the verdict carries and
+  carries a status only, never the tool's result or error text. A refusal
+  never runs the handler and reports nothing. An unreported action reads as
+  unconfirmed on the Shrike Agents screen, which is what it is.
+- `ScanClient.reportOutcome(scanId, outcome, { exitStatus, source })` and
+  `ScanClient.reportHostOutcome({ host, outcome, tool, callId, contentHash,
+  reason, scanId })` for integrations that hold the outcome themselves.
+  Both are best effort and never throw. `Governance.reportOutcome(out,
+  outcome)` reports once per recorded decision. `ScanResult.scan_id` and
+  `Decision.scanId` are new fields.
+- `SessionLockedNotice` is exported as the third member of the
+  `ClientSessionRotation` union, so a locked session has a type of its own
+  instead of a rotation record with its rotation fields left unset.
+
+### Fixed
+- **A locked session is no longer offered a new session id.** A lock means the
+  session is finished, so the record returned on a `session_locked` verdict now
+  carries no id to adopt. The two rotating records narrow `reason` to
+  `'risk_threshold_exceeded'`, the only value either can still carry, so a lock
+  and a rotation are distinguishable by type rather than by reading a string.
+  Recovery from a lock is self-release under a live declared scope, or an
+  operator.
+
+## [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
@@ -126,11 +216,11 @@ Cross-language SDK parity. The Python SDK ships `CircuitBreaker` + `retry_with_b
 
 ### Added
 - **Client-side PII redaction.** `redactPII()`, `rehydratePII()`, `getRedactionSummary()`, `updatePIIPatterns()`, and `getPIIPatternCount()` exported from the root entry point. Detects and tokenizes 20+ PII types (SSN, credit card, email, phone, address, medical record, wallet, etc.) BEFORE the prompt leaves customer environment — Shrike backend never sees the raw PII.
-- **`syncPIIPatterns({ endpoint, apiKey })`** — one-shot startup call fetches the canonical Presidio-derived pattern set from the Shrike backend so client-side detection stays uniform with the server-side scan. Fails safe: on any error (network / timeout / malformed) the bootstrap patterns stay in place; sync never blocks scans.
+- **`syncPIIPatterns({ endpoint, apiKey })`** — one-shot startup call fetches the canonical pattern set from the Shrike backend so client-side detection stays uniform with the server-side scan. Fails safe: on any error (network / timeout / malformed) the bootstrap patterns stay in place; sync never blocks scans.
 - **Backend-owned prefix contract.** The recognizer ships its client-side redaction tag (e.g. `[IP_1]`) as part of the pattern payload; the client uses it verbatim. When the backend omits the field (pre-2026-07-02 releases), the SDK derives the prefix from the threat_type. No pattern is ever silently dropped for an unmapped prefix. Adding a new backend pattern requires zero SDK changes.
 
 ### Why
-Client-side redaction removes PII before it crosses the network to Shrike's backend — defense-in-depth for HIPAA / PCI / GLBA / CMMC workloads on top of the BAA/DPA that already covers transmission. The `syncPIIPatterns` step keeps client patterns in step with backend patterns without shipping SDK updates every time Presidio adds a recognizer.
+Client-side redaction removes PII before it crosses the network to Shrike's backend — defense-in-depth for HIPAA / PCI / GLBA / CMMC workloads on top of the BAA/DPA that already covers transmission. The `syncPIIPatterns` step keeps client patterns in step with backend patterns without shipping SDK updates every time the backend adds a recognizer.
 
 ### Fixed
 - gemini-client test mock import matches the runtime `@google/genai` package (upstream renamed from `@google/generative-ai`).

package/README.md

@@ -347,6 +347,72 @@ for (const tool of tools) {
 
 Screening happens once per tool at registration, not on every call.
 
+## Governing an agent: framework starters
+
+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

package/dist/ai/index.d.mts

@@ -0,0 +1,59 @@
+import { ToolSet, Tool, LanguageModelMiddleware } from 'ai';
+import { G as Governance$1, a as Guard, S as ScanClient, b as GovernanceOptions } from '../govern-olQtsipX.mjs';
+export { D as Decision, O as Outcome, T as ToolMapping } from '../govern-olQtsipX.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,59 @@
+import { ToolSet, Tool, LanguageModelMiddleware } from 'ai';
+import { G as Governance$1, a as Guard, S as ScanClient, b as GovernanceOptions } from '../govern-olQtsipX.js';
+export { D as Decision, O as Outcome, T as ToolMapping } from '../govern-olQtsipX.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 };