opencode-castlegate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martins6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# opencode-castlegate
+
+OpenCode plugin that **auto-approves tool calls when they match your session intent**, and surfaces mismatches to you before execution.
+
+See [`SPEC.md`](./SPEC.md) for the full architecture and behavioral contract. Security model: [`docs/security-model.md`](./docs/security-model.md). Config schema: [`docs/config.md`](./docs/config.md).
+
+---
+
+## Install
+
+```sh
+opencode plugin add opencode-castlegate@latest
+```
+
+That is it. The plugin works **zero-config**: when no `model` block is set in `opencode.json`, it uses opencode's session-default model for the lightweight intent validator. If you want to pin a specific fast/cheap model, add a single block:
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-castlegate@latest"],
+  "opencode-castlegate": {
+    "model": { "providerID": "anthropic", "modelID": "claude-haiku-4-5" }
+  }
+}
+```
+
+See [`docs/config.md`](./docs/config.md) for the full schema.
+
+---
+
+## Local development
+
+This repo is for development against a host OpenCode installation. The plugin is loaded as a package from the host project's `.opencode/package.json`. Do not copy individual source files into `.opencode/plugins/`: the entry point imports the rest of the source tree.
+
+### 1. Clone and install dependencies
+
+```bash
+git clone https://github.com/Martins6/opencode-castlegate.git
+cd opencode-castlegate
+npm install
+```
+
+### 2. Verify the build is healthy
+
+```bash
+npm run typecheck
+npm test
+```
+
+Tests use Node's built-in test runner via `--experimental-strip-types`. bun is **not** required for development; opencode itself runs the plugin under bun at runtime.
+
+### 3. Link it into a host project
+
+Pick a project where you want to use opencode-castlegate, then:
+
+```bash
+# from inside the host project
+mkdir -p .opencode
+```
+
+Create `.opencode/package.json` with a `file:` dependency:
+
+```json
+{
+  "dependencies": {
+    "opencode-castlegate": "file:/absolute/path/to/opencode-castlegate"
+  }
+}
+```
+
+OpenCode runs `bun install` on startup to resolve `.opencode/package.json`, then loads the package named in the `plugin` array. No `.opencode/plugins/` file is needed for this package. If you previously copied `opencode-castlegate.ts` into that directory, remove it so the plugin is not registered twice.
+
+### 4. Configure
+
+Add the `opencode-castlegate` block to your host project's `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-castlegate"],
+  "opencode-castlegate": {
+    "model": { "providerID": "anthropic", "modelID": "claude-haiku-4-5" },
+    "intent": { "maxChars": 4000, "compactThreshold": 0.8, "maxRecentMessages": 20 },
+    "validate": {
+      "tools": ["bash", "edit", "write", "webfetch"],
+      "skip": ["read", "glob", "grep"],
+      "requireApprovalOnMismatch": true,
+      "failOpenOnError": true,
+      "cacheTtlMs": 30000,
+      "mode": "llm"
+    },
+    "storage": { "directory": ".opencode/intent" },
+    "logging": true
+  }
+}
+```
+
+See [`docs/config.md`](./docs/config.md) for the full schema.
+
+### 5. Manual smoke test
+
+Run the bundled end-to-end script (no opencode server required):
+
+```bash
+node --experimental-strip-types scripts/manual-e2e.ts
+```
+
+You should see output like:
+
+```
+plugin loaded: [ 'dispose', 'event', 'tool.execute.before', 'tool' ]
+digest file created: true
+logs after validation: 0
+intent_context tool result: ...
+```
+
+### 6. Iterating
+
+After editing files in this repo, restart the host project's OpenCode session. It reruns the `.opencode` dependency install and reloads the package on startup.
+
+If the host project is still using a stale local dependency, run `bun install` from its `.opencode/` directory before restarting the session.
+
+## Project layout
+
+```
+opencode-castlegate/
+├── SPEC.md                   Architecture + behavioral contract
+├── README.md                 This file (dev install)
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts              Plugin entry — wires all hooks
+│   ├── config.ts             Zod schema + parser
+│   ├── errors.ts             CastlegateIntentMismatchError
+│   ├── store.ts              Atomic digest store on disk
+│   ├── intent.ts             updateDigest (lightweight LLM merge)
+│   ├── validate.ts           validateToolCall + LRU cache
+│   ├── log.ts                Structured event logger
+│   ├── prompts/
+│   │   ├── intent-update.ts  Digest-merge prompt + parser
+│   │   └── intent-validate.ts Validator prompt + parser + arg summarizer
+│   └── tools/
+│       └── intent-context.ts Custom intent_context tool
+├── test/                     Node --test suite (34 tests)
+├── scripts/
+│   └── manual-e2e.ts         Boot fake client, exercise hooks
+└── docs/
+    ├── config.md             Full config reference
+    └── security-model.md     Threat model + logging + caching
+```
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,182 @@
+# SPEC — castlegate
+
+## 1. Purpose
+
+OpenCode plugin that gates tool calls against the user's stated session intent. A lightweight model maintains a rolling **intent digest** for the session. Each gated `tool.execute.before` call is validated against that digest:
+
+- **Match** → tool runs (no user prompt).
+- **Mismatch** → tool is blocked with a tagged error; the main agent surfaces the request to the user via its `question` tool.
+
+## 2. Non-goals
+
+- Not a sandbox. castlegate does not enforce OS-level isolation.
+- Not a static permission system. OpenCode's `permission` config handles pattern rules.
+- Not a replacement for the user's own judgment. The user can always say "yes" via the question tool.
+
+## 3. Architecture
+
+```
+              ┌────────────────────────────────────────────────┐
+              │                Plugin runtime                   │
+              │                                                │
+              │   event hook                                    │
+              │     └─► session.created    → seed digest file   │
+              │     └─► message.updated   → schedule digest    │
+              │                          update (1s debounce)  │
+              │     └─► session.deleted   → drop digest file   │
+              │                                                │
+              │   tool.execute.before                          │
+              │     └─► shouldValidate(tool, cfg)               │
+              │     └─► loadDigest(dir, sessionId)             │
+              │     └─► validateToolCall(...) ←─ LLM call      │
+              │     └─► match: allow | mismatch: throw tagged  │
+              │                                                │
+              │   tool.intent_context (custom)                  │
+              │     └─► returns current digest for the session │
+              │                                                │
+              │   dispose                                       │
+              │     └─► cancel timers, clear validator cache   │
+              └────────────────────────────────────────────────┘
+                              │                  │
+                              ▼                  ▼
+              .opencode/intent/<sid>.md    Sidecar session
+              (on-disk digest, atomic)     (validator LLM calls)
+```
+
+### 3.1 Sidecar session
+
+The validator LLM runs in a hidden, persistent opencode session created via `client.session.create({body: {title: "[castlegate] validator sidecar"}})`. This keeps validator calls out of the user's session history and amortizes session setup. One sidecar per plugin instance.
+
+### 3.2 Storage format
+
+`.opencode/intent/<sanitizedSessionId>.md`:
+
+```
+---
+digestVersion: 4
+lastMessageId: msg_41
+updatedAt: 2026-09-05T12:00:00.000Z
+charCount: 612
+---
+
+<markdown body, <= intent.maxChars>
+```
+
+Writes are atomic (temp file + `fs.rename`, with `fsync` of the temp file before the rename).
+
+### 3.3 Validator cache
+
+`validateToolCall` results are cached in-memory keyed by `sha256(tool + "\0" + JSON.stringify(args) + "\0" + digestVersion)` for `validate.cacheTtlMs`. Cache auto-invalidates when the digest version bumps (next `intent.updated`).
+
+## 4. Public surface
+
+### 4.1 Plugin entry
+
+```ts
+// src/index.ts
+export const CastlegatePlugin: Plugin = async (input, options) => { ... };
+export default CastlegatePlugin;
+export { CastlegateIntentMismatchError, CASTLEGATE_TAG };
+```
+
+### 4.2 Custom tool
+
+```
+intent_context
+  args: { format?: "summary" | "raw" }
+  returns: { title, output, metadata: { version, lastMessageId, updatedAt, charCount } }
+```
+
+### 4.3 Tagged error
+
+```ts
+class CastlegateIntentMismatchError extends Error {
+  readonly tag = "CASTLEGATE_INTENT_MISMATCH";
+  readonly tool: string;
+  readonly reason: string;
+  readonly severity: "low" | "medium" | "high";
+}
+```
+
+Error message format (must stay stable for the main agent to parse):
+
+```
+CASTLEGATE_INTENT_MISMATCH: tool '<name>' did not match the current session intent.
+Reason: <reason>
+Severity: <severity>
+Action required: surface this to the user via the question tool and wait for explicit approval before retrying the tool call.
+```
+
+### 4.4 Config
+
+See `docs/config.md`. The plugin is loaded as `opencode-castlegate` and its options use the top-level `opencode-castlegate` key in `opencode.json`.
+
+## 5. Behavioral contracts
+
+### 5.1 What `shouldValidate` returns
+
+| Condition | Result |
+|---|---|
+| `tool` ∈ `validate.skip` | `false` (skip) |
+| `validate.tools` set and `tool` ∉ `validate.tools` | `false` (skip) |
+| otherwise | `true` |
+
+### 5.2 What the validator returns
+
+```json
+{ "match": <bool>, "reason": <string>, "severity": "low" | "medium" | "high" }
+```
+
+Parsed from the lightweight model's text response. Accepts fenced JSON, surrounding prose, or plain JSON. Defaults severity to `medium` on unrecognized values.
+
+### 5.3 What happens on mismatch when `requireApprovalOnMismatch: true`
+
+`CastlegateIntentMismatchError` is thrown from `tool.execute.before`. OpenCode converts this to a tool error for the agent. The bash command never executes. The agent is expected to call its `question` tool with a yes/no/always choice.
+
+### 5.4 What happens on validator failure (`failOpenOnError`)
+
+| `failOpenOnError` | Behavior |
+|---|---|
+| `true` (default) | Log warning, allow tool call |
+| `false` | Throw `CastlegateIntentMismatchError` with severity `medium` (or `high` for `bash`) |
+
+### 5.5 What happens when no digest exists yet
+
+`validate.skip_no_digest` is logged and the tool call is allowed through. The intent ingestion loop will populate the digest before the next gated tool call (1s debounce).
+
+## 6. Lifecycle
+
+| Event | Handler |
+|---|---|
+| `session.created` | Initialize empty digest file (`digestVersion: 1`, body `""`) |
+| `message.updated` | Debounce 1s, then `updateDigest` |
+| `message.part.updated` / `message.part.removed` / `message.removed` | Same debounced path |
+| `session.deleted` | Delete digest file, drop per-session state |
+| `dispose()` | Cancel timers, clear cache |
+
+## 7. Logging
+
+All events flow through `client.app.log` with `service: "castlegate"`. Tool argument values are never logged; only the keys (e.g. `["command"]`) and the validator's reason string. See `docs/security-model.md` for the full event list.
+
+## 8. Failure modes
+
+| Mode | Symptom | Mitigation |
+|---|---|---|
+| Lightweight model call throws | `validate.error` event; `failOpenOnError` decides outcome | Configurable |
+| Lightweight model returns invalid JSON | parser throws → treated as validator error | Same |
+| Digest file corrupted | `loadDigest` returns `null` → treated as no digest → tool allowed | Atomic writes + version field help detect corruption; future: checksum |
+| Two updates race | Last write wins (atomic rename) | Acceptable; digest version makes stale reads detectable |
+| Opencode kills the sidecar session | Next validator call creates a fresh one (cache holds the stale id but call errors) | Acceptable; fallback decision applies |
+
+## 9. Future work
+
+- Decision journal: persist user-approved exceptions so the validator does not re-block after explicit approval.
+- Heuristic-only mode (`validate.mode: "heuristic"`) for zero-cost validation against the digest.
+- Compaction hook integration so the digest survives long sessions without losing the anchor intent.
+- Native `permission.ask` API integration once upstream issues #37164 / #34327 land.
+
+## 10. Compatibility
+
+- opencode ≥ 1.0 (uses `@opencode-ai/plugin` ≥ 1.18.0, SDK ≥ 1.18.0)
+- zod 4.1.x (locked; newer minor versions change the `_zod.version.minor` tag and break `tool()` typings)
+- Node ≥ 20 for development (type-check, tests). Runtime is bun, shipped via opencode.

package/docs/config.md

@@ -0,0 +1,53 @@
+# opencode-castlegate configuration
+
+The `opencode-castlegate` block in `opencode.json` (or `.opencode/opencode.json`) accepts the following keys. Defaults are shown.
+
+```ts
+{
+  model?: {
+    providerID: string,         // optional — defaults to opencode's session-default model
+    modelID: string,            // optional — defaults to opencode's session-default model
+  },
+  intent: {
+    maxChars: number,           // default 4000 — hard cap on digest size
+    compactThreshold: number,   // default 0.8 — fraction of maxChars at which a compact run is requested
+    maxRecentMessages: number,  // default 20 — how many recent messages to feed the lightweight model per digest update
+  },
+  validate: {
+    tools?: string[],           // optional allowlist; when set, ONLY these tools are validated
+    skip: string[],             // default [] — these tools are NEVER validated
+    requireApprovalOnMismatch: boolean, // default true — throw tagged error on mismatch
+    failOpenOnError: boolean,   // default true — allow tool call when validator errors
+    cacheTtlMs: number,         // default 30000 — skip repeat-validating identical calls within this window
+    mode: "llm" | "heuristic" | "both", // default "llm" — validator mode (heuristic-only is a future enhancement)
+  },
+  storage: {
+    directory: string,          // default ".opencode/intent" — relative paths resolve against the project directory
+  },
+  logging: boolean,             // default true — emit structured events via client.app.log
+}
+```
+
+> **Zero-config default.** When `model` is omitted, the plugin omits the `model` field from `client.session.prompt` and lets opencode resolve the session-default model. This is the recommended starting point — most users will never need to set `model`. Override only if you want to pin a specific fast/cheap model for the lightweight validator.
+
+## Behavior notes
+
+- **`validate.tools`** is the strongest signal: set it to gate only the tools you consider high-risk. If unset, every tool is validated (subject to `skip`).
+- **`validate.skip`** is honored even when `validate.tools` is set.
+- **`intent.maxChars`** is enforced after each digest update: any output over the limit is truncated. Compaction is requested (via the lightweight model) when the digest is at or above `intent.compactThreshold * intent.maxChars`.
+- **`validate.cacheTtlMs`** is a *defensive* cache, keyed by `hash(tool, args, digestVersion)`. Set to `0` to disable.
+- **`storage.directory`** is resolved against the plugin's working directory at runtime, so you can point it outside the project if desired.
+
+## Minimal config
+
+Zero-config (no `opencode-castlegate` block at all) works out of the box — the plugin uses opencode's session-default model.
+
+To pin a specific fast/cheap validator model:
+
+```json
+{
+  "opencode-castlegate": {
+    "model": { "providerID": "anthropic", "modelID": "claude-haiku-4-5" }
+  }
+}
+```

package/docs/security-model.md

@@ -0,0 +1,78 @@
+# castlegate security model
+
+## Threat model
+
+castlegate is a **defense-in-depth** layer on top of OpenCode's permission system. It is designed to catch the common case where an agent does something surprising — not to replace OS-level sandboxing, network policy, or secret management.
+
+In scope:
+
+- An agent drifting away from the user's stated session intent and making tool calls the user would not have approved.
+- Repeated trivial mistakes that the user has already corrected once in the conversation.
+- "Drive-by" tool calls (e.g. installing packages, running unrelated tests) that creep into a focused refactor.
+
+Out of scope:
+
+- A *deliberately* compromised model that intends to exfiltrate data — it can craft intent-matching phrasings or call tools castlegate is told to skip.
+- Prompt injection from tool *outputs* (e.g. a poisoned webfetch page that instructs the model). castlegate validates tool *call args*, not what the model does with results.
+- Resource exhaustion from the lightweight model itself; rate-limit upstream if this matters.
+
+## Fail-open vs fail-closed
+
+`validate.failOpenOnError` controls what happens when the validator itself fails (network blip, model error, malformed response):
+
+| `failOpenOnError` | Behavior on validator error |
+|---|---|
+| `true` (default) | Log a warning, allow the tool call to proceed |
+| `false` | Throw `CastlegateIntentMismatchError` as if it were a mismatch |
+
+**Default is fail-open** so transient outages don't break sessions. Flip to `false` for high-risk projects where you would rather the agent stop and check in than proceed with a stale (or missing) intent digest.
+
+## What gets logged
+
+`logging: true` emits structured events through `client.app.log` with `service: "castlegate"`:
+
+| Event | When | Notable fields |
+|---|---|---|
+| `session.initialized` | `session.created` | `sessionID` |
+| `intent.updated` | digest update succeeds | `version`, `compacted`, `intentShift`, `chars` |
+| `intent.update_error` | digest update throws | `error` |
+| `validate.match` | tool call matches digest | `tool`, `cached`, `severity` |
+| `validate.mismatch` | tool call does not match | `tool`, `reason`, `severity`, `argKeys` |
+| `validate.error` | validator itself failed | `tool`, `error` |
+| `validate.skip_no_digest` | no digest yet for session | `tool` |
+| `validate.digest_load_error` | could not load digest from disk | `tool`, `error` |
+
+Tool arguments are **never** logged in full — only the keys (e.g. `["command"]`, `["filePath"]`) and the validator's `reason`.
+
+## Permission flow
+
+When a mismatch is detected and `validate.requireApprovalOnMismatch` is `true`:
+
+1. castlegate throws `CastlegateIntentMismatchError` from `tool.execute.before`.
+2. OpenCode surfaces the error to the agent as a tool error.
+3. The agent is expected to use the `question` tool to ask the user for explicit approval before retrying the call.
+4. The tool call does **not** execute until the user approves.
+
+This works because of OpenCode's separation between agent error handling and tool execution: a thrown error in `tool.execute.before` aborts the tool call before it reaches the runtime.
+
+When upstream opencode lands a native `permission.ask` API inside `tool.execute.before` (issues #37164, #34327), castlegate will switch to using it without changing this contract.
+
+## Cache and replay
+
+`validate.cacheTtlMs` (default 30s) caches validation results keyed by `hash(tool, args, digestVersion)`. This means:
+
+- A repeated call within the window reuses the prior decision. This is intentional: if the agent retries an identical call after you approved it once, castlegate doesn't redo the LLM round-trip.
+- The cache is invalidated whenever the digest version bumps (after `intent.updated`). New context → new decisions.
+
+## Files written
+
+- `.opencode/intent/<sessionId>.md` — the digest for each session. Format is plain markdown with a YAML-ish front-matter header. **Not gitignored by default;** add it to `.gitignore` if you don't want digest snapshots in source control.
+- No other files are written.
+
+## Outbound network
+
+Every validated tool call adds one outbound call to the configured lightweight model. On long sessions with many tool calls, this can dominate cost. Mitigations:
+
+- `validate.skip` for tools you don't care about (e.g. `read`, `glob`, `grep`).
+- `validate.cacheTtlMs` (already on by default).
+- `validate.tools` to whitelist only the high-risk tools.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opencode-castlegate",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that auto-approves tool calls when they match the user's session intent, validated by a lightweight model.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types --test-reporter=spec test/store.test.ts test/validate.test.ts test/intent.test.ts test/config.test.ts test/errors.test.ts test/prompt-body.test.ts"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "agent",
+    "guardrail",
+    "intent",
+    "auto-approve"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Martins6/opencode-castlegate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Martins6/opencode-castlegate/issues"
+  },
+  "homepage": "https://github.com/Martins6/opencode-castlegate#readme",
+  "files": [
+    "src",
+    "README.md",
+    "SPEC.md",
+    "docs",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.0",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/config.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+
+export const ModelConfigSchema = z.object({
+  providerID: z.string().min(1),
+  modelID: z.string().min(1),
+});
+export type ModelConfig = z.infer<typeof ModelConfigSchema>;
+
+export const IntentConfigSchema = z.object({
+  maxChars: z.number().int().positive().default(4000),
+  compactThreshold: z.number().min(0.1).max(1).default(0.8),
+  maxRecentMessages: z.number().int().positive().default(20),
+});
+export type IntentConfig = z.infer<typeof IntentConfigSchema>;
+
+export const ValidateConfigSchema = z.object({
+  tools: z.array(z.string()).optional(),
+  skip: z.array(z.string()).default([]),
+  requireApprovalOnMismatch: z.boolean().default(true),
+  failOpenOnError: z.boolean().default(true),
+  cacheTtlMs: z.number().int().nonnegative().default(30_000),
+  mode: z.enum(["llm", "heuristic", "both"]).default("llm"),
+});
+export type ValidateConfig = z.infer<typeof ValidateConfigSchema>;
+
+export const StorageConfigSchema = z.object({
+  directory: z.string().default(".opencode/intent"),
+});
+export type StorageConfig = z.infer<typeof StorageConfigSchema>;
+
+export const CastlegateConfigSchema = z.object({
+  model: ModelConfigSchema.optional(),
+  intent: IntentConfigSchema.default(() => ({
+    maxChars: 4000,
+    compactThreshold: 0.8,
+    maxRecentMessages: 20,
+  })),
+  validate: ValidateConfigSchema.default(() => ({
+    skip: [],
+    requireApprovalOnMismatch: true,
+    failOpenOnError: true,
+    cacheTtlMs: 30_000,
+    mode: "llm" as const,
+  })),
+  storage: StorageConfigSchema.default(() => ({ directory: ".opencode/intent" })),
+  logging: z.boolean().default(true),
+});
+export type CastlegateConfig = z.infer<typeof CastlegateConfigSchema>;
+
+export function parseConfig(raw: unknown): CastlegateConfig {
+  return CastlegateConfigSchema.parse(raw);
+}
+
+export function safeParseConfig(raw: unknown): {
+  ok: true;
+  config: CastlegateConfig;
+} | {
+  ok: false;
+  error: z.ZodError;
+} {
+  const result = CastlegateConfigSchema.safeParse(raw);
+  if (result.success) return { ok: true, config: result.data };
+  return { ok: false, error: result.error };
+}

package/src/errors.ts

@@ -0,0 +1,28 @@
+export const CASTLEGATE_TAG = "CASTLEGATE_INTENT_MISMATCH";
+
+export class CastlegateIntentMismatchError extends Error {
+  readonly tag = CASTLEGATE_TAG;
+  readonly tool: string;
+  readonly reason: string;
+  readonly severity: "low" | "medium" | "high";
+
+  constructor(tool: string, reason: string, severity: "low" | "medium" | "high") {
+    const message =
+      `${CASTLEGATE_TAG}: tool '${tool}' did not match the current session intent.\n` +
+      `Reason: ${reason}\n` +
+      `Severity: ${severity}\n` +
+      `Action required: surface this to the user via the question tool and wait for explicit approval before retrying the tool call.`;
+    super(message);
+    this.name = "CastlegateIntentMismatchError";
+    this.tool = tool;
+    this.reason = reason;
+    this.severity = severity;
+  }
+
+  static isMismatch(err: unknown): err is CastlegateIntentMismatchError {
+    return (
+      err instanceof CastlegateIntentMismatchError ||
+      (err instanceof Error && err.message.startsWith(`${CASTLEGATE_TAG}:`))
+    );
+  }
+}