Agent Guard 1.1.0

Agent Guard 1.1.0

A minor release of @shieldaai/agent-guard, -mcp, -scenarios, -executor and the
experimental @shieldaai/agent-map. It adds one feature, asked for by a reader of the 1.0
announcement (issue 57): reviewers can
see what changed in a tool definition before they approve it again. The 1.0 API is
unchanged. The full list is in the changelog.

What is new

In 1.0 a changed tool was refused until its new fingerprint was approved, but the guard
could not say what had changed. Now it keeps the approved definition and compares.

const fingerprint = guard.registerTool(changedDefinition);
const review = guard.toolChanges('files.read');
// review.status === 'changed'
// review.changes:
//   { path: '/description', kind: 'changed', before: '…', after: '…', hints: ['INSTRUCTION_TEXT'] }
//   { path: '/inputSchema/properties/upload_to', kind: 'added', after: { type: 'string' }, hints: ['SCHEMA_FIELD_ADDED'] }
guard.approveTool('files.read', fingerprint, { reviewedAgainst: review.approvedFingerprint ?? null });

• Core. toolChanges(name) lists each changed JSON path of the definition with the
  approved and the new value. diffToolDefinitions() does the same for any two
  definitions. approveTool() takes an optional reviewedAgainst, so an approval made
  against a comparison that is no longer current is refused.
• Hints. Changes that often matter are marked: new instruction-like text, invisible
  characters, a new or loosened schema field, a weakened guard flag. They are heuristics
  for a person. They block nothing.
• MCP. connection.operationChanges(name) shows what the server changed since the
  operation was last approved, after a refresh or a reconnect, with both descriptor digests.
• Executor. Approved definitions are stored in the ledger with who approved them and
  what they replaced, so the comparison works after a restart.
• Scenarios. Catalog 1.4.0 adds the diff to S06.
• Agent Ops. Maintenance shows the comparison for the service's own tool, until the
  next restart.

API contract has the exact types.

Known limits

• The comparison covers a tool's definition: name, description, input schema, metadata and
  flags. It never shows a change in what the tool's code does.
• Hints are heuristics. They miss hostile text and flag harmless text. An unmarked change
  is not a safe change.
• Values in a comparison are the tool's or server's own text. Show them as data: escape
  them, and do not pass them to a model as instructions.
• A definition over 64 KiB (configurable up to 1 MiB) is approved by fingerprint only, as is
  one that does not fit the executor's budget for kept definitions (an eighth of the ledger). The
  guard says so (status: 'unavailable') instead of showing a diff.
• The in-memory guard forgets approved definitions on restart. Use the executor to keep them.
• A ledger written by 1.0.0 has no approved definitions: each tool reports first_approval
  until it is approved once with 1.1.0.
• The limits of 1.0.0 still apply; see its release notes and
  Support and limits.

Verification

All 19 checks passed on the release candidate 781a1ad
(pull request 58): npm run check on
Node 22, 24 and 26 on Linux and on macOS and Windows; the browser checks in Chromium,
Firefox and WebKit; the Neo4j integration tests; the Docker isolation and production-image
checks; CodeQL with no open alerts. CI and CodeQL also passed on the merge commit 8fd7c76.
Main CI run: 43412403731.

The nightly constrained-observer timing run (one logical CPU) did not pass on 8fd7c76. It
is not a required check, and that profile is not supported; see
Support and limits.

Upgrading from 1.0.0

No code change is needed.

• Ledger. formatVersion stays 1. A 1.0.0 ledger opens as it is, and 1.0.0 can still
  open a ledger that 1.1.0 wrote. 1.0.0 does not maintain the approved-definition record,
  so after going back to 1.0.0 and forward again a comparison can be against an older
  approval; toolChanges(name).approval.approvedAt shows which.
• MCP. If you store reviewed descriptorDigest values yourself, that keeps working.
  With operationChanges() the guard does the comparison for you.
• Scenario reports. catalogVersion is 1.4.0. A custom adapter without toolChanges
  still passes; it runs the 1.3.0 checks of S06.
• Agent Ops (source builds). GET /api/maintenance adds toolDefinition; the bundled
  page requires it, so deploy the service and the page together.