shrike-guard 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # 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

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,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 };