@crowdstrike/falcon-guardian-opencode-collector 0.0.0-stage → 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CrowdStrike
+
+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

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# falcon-guardian-opencode-collector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Falcon Guardian collector for OpenCode.
+
+## Setup
+
+Set the following environment variables:
+
+- `CS_AIDR_TOKEN`: Falcon Guardian API token.
+- `CS_AIDR_BASE_URL`: Falcon Guardian API base URL.
+
+Then restart the OpenCode background server:
+
+```
+opencode service restart
+```
+
+## Usage
+
+Load the plugin in `opencode.json(c)`:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@crowdstrike/falcon-guardian-opencode-collector",
+      "options": { "failureMode": "closed" },
+    },
+  ],
+}
+```
+
+## Configuration
+
+| Option | Env | Default |
+|---|---|---|
+| `token` | `CS_AIDR_TOKEN` | required |
+| `baseURL` | `CS_AIDR_BASE_URL` | `https://api.crowdstrike.com/aidr/aiguard` |
+| `timeout` (seconds) | | `30` |
+| `failureMode` (`open` or `closed`) | | `closed` |
+
+## Develop
+
+```sh
+pnpm install
+pnpm test
+pnpm lint && pnpm typecheck
+pnpm build
+```

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@crowdstrike/falcon-guardian-opencode-collector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Falcon Guardian collector for OpenCode",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CrowdStrike/falcon-guardian-opencode-collector.git"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "LICENSE.txt",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@crowdstrike/aidr": "^1.3.0",
+    "@opencode/plugin": "^2.0.32",
+    "@opencode/schema": "^2.0.32",
+    "plist": "^5.0.0",
+    "safe-execa": "^0.3.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.6",
+    "@containerbase/semantic-release-pnpm": "1.4.3",
+    "@tsconfig/node22": "22.0.6",
+    "@types/node": "22.19.17",
+    "conventional-changelog-conventionalcommits": "9.3.1",
+    "effect": "4.0.1",
+    "semantic-release": "25.0.9",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "node --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/guard.test.ts

@@ -0,0 +1,375 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { Agent } from '@opencode/schema/agent';
+import { Model } from '@opencode/schema/model';
+import { Provider } from '@opencode/schema/provider';
+import { Session } from '@opencode/schema/session';
+import { SessionMessage } from '@opencode/schema/session-message';
+import { Tool } from '@opencode/schema/tool';
+import * as guard from './guard.ts';
+
+const meta: guard.Meta = {
+  user: 'dennis',
+  directory: '/w',
+  version: '2.0.26',
+  processID: 4242,
+  model: {
+    providerID: Provider.ID.make('anthropic'),
+    id: Model.ID.make('claude-sonnet-5'),
+  },
+  sensorAID: 'd4208f3f3cf544f196bfe612aa8035fe',
+};
+
+const ids = {
+  sessionID: Session.ID.make('ses_1'),
+  agent: Agent.ID.make('build'),
+  messageID: SessionMessage.ID.make('msg_1'),
+  id: Tool.CallID.make('call_1'),
+};
+
+const prompt = (): guard.PromptEvent => ({
+  sessionID: ids.sessionID,
+  messageID: ids.messageID,
+  prompt: {
+    text: 'read @notes.md, my SSN is 900-12-3456',
+    files: [
+      {
+        uri: 'file:///w/notes.md',
+        mention: { start: 5, end: 14, text: '@notes.md' },
+      },
+    ],
+  },
+  delivery: 'steer',
+});
+
+const toolInput = (): guard.ToolInputEvent => ({
+  ...ids,
+  tool: 'write',
+  input: { filePath: '/w/a.txt', content: '900-12-3456' },
+});
+
+const toolOutput = (result: Tool.Result): guard.ToolOutputEvent => ({
+  ...ids,
+  tool: 'shell',
+  input: { command: 'cat a.txt' },
+  status: 'completed',
+  result,
+});
+
+/** A request as sent on the wire. */
+const wire = (req: object): unknown => JSON.parse(JSON.stringify(req));
+
+const blocked = {
+  summary: 'SSN was detected and blocked.',
+  result: { blocked: true },
+};
+const redacted = (...messages: object[]) => ({
+  result: { transformed: true, guard_output: { messages } },
+});
+
+test('token and base URL come from options, then the environment', () => {
+  const env = {
+    CS_AIDR_TOKEN: 'env-token',
+    CS_AIDR_BASE_URL: 'https://api.us-2.crowdstrike.com/aidr/aiguard',
+  };
+  assert.deepEqual(guard.config({}, env), {
+    token: 'env-token',
+    baseURL: 'https://api.us-2.crowdstrike.com/aidr/aiguard',
+    timeoutMillis: 30_000,
+    failureMode: 'closed',
+  });
+  assert.deepEqual(
+    guard.config(
+      {
+        token: 'opt',
+        baseURL: 'https://api.collector-crowdstrike.com',
+        timeout: 5,
+        failureMode: 'open',
+      },
+      env
+    ),
+    {
+      token: 'opt',
+      baseURL: 'https://api.collector-crowdstrike.com',
+      timeoutMillis: 5_000,
+      failureMode: 'open',
+    }
+  );
+});
+
+test('a base URL off CrowdStrike HTTPS hosts leaves no token', () => {
+  for (const baseURL of [
+    'https://evil.com',
+    'https://evilcrowdstrike.com',
+    'https://crowdstrike.com.evil.com',
+    'https://api.crowdstrike.com@evil.com',
+    'https://evil.com\\.crowdstrike.com',
+    'http://api.crowdstrike.com',
+    'not a url',
+  ])
+    assert.ok(
+      guard.config({ baseURL }, { CS_AIDR_TOKEN: 't' }).token instanceof Error,
+      baseURL
+    );
+});
+
+test('a missing token or invalid options leave no token', () => {
+  assert.ok(guard.config({}, {}).token instanceof Error);
+  const invalid = guard.config(
+    { token: 1, failureMode: 'open' },
+    { CS_AIDR_TOKEN: 't' }
+  );
+  assert.ok(invalid.token instanceof Error);
+  assert.equal(invalid.failureMode, 'closed');
+  assert.equal(
+    guard.config({ failureMode: 'shut' }, { CS_AIDR_TOKEN: 't' }).failureMode,
+    'closed'
+  );
+});
+
+test('prompt is sent as input', () => {
+  assert.deepEqual(wire(guard.promptRequest(prompt(), meta)), {
+    guard_input: {
+      messages: [
+        { role: 'user', content: 'read @notes.md, my SSN is 900-12-3456' },
+      ],
+    },
+    event_type: 'input',
+    llm_provider: 'anthropic',
+    model: 'claude-sonnet-5',
+    session_id: 'ses_1',
+    user_id: 'dennis',
+    agent_type: 'code-assistant',
+    is_agent: true,
+    process_id: '4242',
+    process_tags: ['213584428666668'],
+    extra_info: {
+      app_name: 'OpenCode',
+      app_version: '2.0.26',
+      user_name: 'dennis',
+      opencode_hook_name: 'session.prompt',
+      opencode_directory: '/w',
+      sensor_aid: 'd4208f3f3cf544f196bfe612aa8035fe',
+    },
+  });
+});
+
+test('Windows sensor AID is the AG value as lowercase hex', () => {
+  const sim =
+    'HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\services\\CSAgent\\Sim\r\n';
+  assert.equal(
+    guard.windowsSensorAID(
+      `\r\n${sim}    AFLAGS    REG_BINARY    00000000\r\n` +
+        '    AG    REG_BINARY    D4208F3F3CF544F196BFE612AA8035FE\r\n\r\n' +
+        'End of search: 2 match(es) found.\r\n'
+    ),
+    'd4208f3f3cf544f196bfe612aa8035fe'
+  );
+  assert.equal(
+    guard.windowsSensorAID(`${sim}    AG    REG_BINARY    D4208F3F\r\n`),
+    undefined
+  );
+  assert.equal(guard.windowsSensorAID(''), undefined);
+});
+
+test('macOS sensor AID is the plist aid as lowercase hex', () => {
+  const info = (aid: string) => `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>aid</key>
+    ${aid}
+    <key>cid</key>
+    <string>6CB9530D078E415F96CE34BE06631A37</string>
+    <key>sensor_loaded</key>
+    <true/>
+</dict>
+</plist>
+`;
+  assert.equal(
+    guard.macSensorAID(
+      info('<string>D4208F3F3CF544F196BFE612AA8035FE</string>')
+    ),
+    'd4208f3f3cf544f196bfe612aa8035fe'
+  );
+  assert.equal(
+    guard.macSensorAID(info('<string>D4208F3F</string>')),
+    undefined
+  );
+  assert.equal(guard.macSensorAID(info('<true/>')), undefined);
+  assert.equal(guard.macSensorAID('falconctl: permission denied'), undefined);
+  assert.equal(guard.macSensorAID(''), undefined);
+});
+
+test('tool input is sent as JSON-encoded arguments', () => {
+  const bare = { ...meta, model: undefined, sensorAID: undefined };
+  const req = guard.toolInputRequest(toolInput(), bare);
+  assert.deepEqual(wire(req), {
+    ...(wire(guard.promptRequest(prompt(), bare)) as object),
+    event_type: 'tool_input',
+    guard_input: {
+      messages: [
+        {
+          role: 'assistant',
+          content: null,
+          tool_calls: [
+            {
+              id: 'call_1',
+              type: 'function',
+              function: {
+                name: 'write',
+                arguments: '{"filePath":"/w/a.txt","content":"900-12-3456"}',
+              },
+            },
+          ],
+        },
+      ],
+    },
+    extra_info: {
+      app_name: 'OpenCode',
+      app_version: '2.0.26',
+      user_name: 'dennis',
+      opencode_hook_name: 'tool.execute.before',
+      opencode_directory: '/w',
+      opencode_tool_name: 'write',
+      opencode_agent: 'build',
+    },
+  });
+});
+
+test('tool output is sent as the text the model reads', () => {
+  const sent = (result: Tool.Result) =>
+    (
+      wire(guard.toolOutputRequest(toolOutput(result), meta)) as {
+        guard_input: { messages: unknown[] };
+      }
+    ).guard_input.messages[1];
+  const message = (content: string) => ({
+    role: 'tool',
+    tool_call_id: 'call_1',
+    content,
+  });
+  assert.deepEqual(
+    sent({ content: '900-12-3456\n' }),
+    message('900-12-3456\n')
+  );
+  assert.deepEqual(
+    sent({
+      content: [
+        { type: 'text', text: 'a' },
+        { type: 'file', uri: 'data:image/png;base64,', mime: 'image/png' },
+        { type: 'text', text: 'b' },
+      ],
+    }),
+    message('a\nb')
+  );
+  assert.deepEqual(
+    sent({ output: { exitCode: 0 } }),
+    message('{"exitCode":0}')
+  );
+});
+
+test('verdicts', () => {
+  assert.deepEqual(
+    guard.verdict({ result: { blocked: false, transformed: false } }),
+    { type: 'allow' }
+  );
+  assert.deepEqual(guard.verdict(blocked), {
+    type: 'block',
+    reason: 'Falcon Guardian: SSN was detected and blocked.',
+  });
+  assert.throws(() => guard.verdict({ result: { transformed: true } }));
+  assert.throws(() => guard.verdict(redacted()));
+});
+
+test('failure mode decides when there is no verdict', () => {
+  assert.deepEqual(guard.failure('open', 'timeout'), { type: 'allow' });
+  assert.deepEqual(guard.failure('closed', 'timeout'), {
+    type: 'block',
+    reason: 'Falcon Guardian: timeout',
+  });
+});
+
+test('allowed events are unchanged', () => {
+  const allow = { type: 'allow' } as const;
+  const [p, i, o] = [prompt(), toolInput(), toolOutput({ content: 'x' })];
+  assert.equal(guard.applyToPrompt(p, allow), undefined);
+  assert.equal(guard.applyToToolInput(i, allow), undefined);
+  assert.equal(guard.applyToToolOutput(o, allow), undefined);
+  assert.deepEqual(
+    [p, i, o],
+    [prompt(), toolInput(), toolOutput({ content: 'x' })]
+  );
+});
+
+test('blocked events are rejected with the reason, unchanged', () => {
+  const block = guard.verdict(blocked);
+  const reason = 'Falcon Guardian: SSN was detected and blocked.';
+  const [p, i, o] = [prompt(), toolInput(), toolOutput({ content: 'x' })];
+  assert.equal(guard.applyToPrompt(p, block), reason);
+  assert.equal(guard.applyToToolInput(i, block), reason);
+  assert.equal(guard.applyToToolOutput(o, block), reason);
+  assert.deepEqual(
+    [p, i, o],
+    [prompt(), toolInput(), toolOutput({ content: 'x' })]
+  );
+});
+
+test('redacted prompt keeps attachments without mentions', () => {
+  const event = prompt();
+  guard.applyToPrompt(
+    event,
+    guard.verdict(
+      redacted({ role: 'user', content: 'read @notes.md, my SSN is <US_SSN>' })
+    )
+  );
+  assert.deepEqual(wire(event.prompt), {
+    text: 'read @notes.md, my SSN is <US_SSN>',
+    files: [{ uri: 'file:///w/notes.md' }],
+  });
+});
+
+test('redacted tool input rewrites the call', () => {
+  const event = toolInput();
+  const res = redacted({
+    role: 'assistant',
+    content: null,
+    tool_calls: [
+      {
+        id: 'call_1',
+        type: 'function',
+        function: {
+          name: 'write',
+          arguments: '{"filePath":"/w/a.txt","content":"<US_SSN>"}',
+        },
+      },
+    ],
+  });
+  assert.equal(guard.applyToToolInput(event, guard.verdict(res)), undefined);
+  assert.deepEqual(event.input, { filePath: '/w/a.txt', content: '<US_SSN>' });
+});
+
+test('redacted tool output replaces the output', () => {
+  const event = toolOutput({
+    output: { stdout: '900-12-3456' },
+    content: '900-12-3456',
+  });
+  const res = redacted(
+    { role: 'assistant', tool_calls: [] },
+    { role: 'tool', tool_call_id: 'call_1', content: '<US_SSN>' }
+  );
+  guard.applyToToolOutput(event, guard.verdict(res));
+  assert.deepEqual(event.result, { content: '<US_SSN>' });
+});
+
+test('redaction of the wrong message kind is an error', () => {
+  const user = guard.verdict(redacted({ role: 'user', content: 'x' }));
+  assert.throws(() => guard.applyToToolInput(toolInput(), user));
+  assert.throws(() =>
+    guard.applyToToolOutput(toolOutput({ content: 'x' }), user)
+  );
+  const tool = guard.verdict(
+    redacted({ role: 'tool', tool_call_id: 'call_1', content: 'x' })
+  );
+  assert.throws(() => guard.applyToPrompt(prompt(), tool));
+});

package/src/guard.ts

@@ -0,0 +1,347 @@
+import type {
+  AidrPostV1GuardChatCompletionsResponses,
+  ChatCompletionsGuard,
+} from '@crowdstrike/aidr';
+import type { Model } from '@opencode/plugin/effect';
+import type { SessionPrompt } from '@opencode/plugin/effect/session';
+import type { ToolHooks } from '@opencode/plugin/effect/tool';
+import type { Tool } from '@opencode/schema/tool';
+import { Exit, Schema } from 'effect';
+import * as plist from 'plist';
+
+export type FailureMode = 'open' | 'closed';
+
+const OPENCODE_PROCESS_TAG = '213584428666668';
+
+/** Allowed base URL hosts. */
+const ALLOWED_HOST = /\.(collector-)?crowdstrike\.com$/;
+
+/**
+ * Plugin options from `opencode.json`.
+ */
+const Options = Schema.Struct({
+  token: Schema.optional(Schema.String),
+  baseURL: Schema.optional(Schema.String),
+  /** Seconds to wait for a verdict, including polling. */
+  timeout: Schema.optional(Schema.Number),
+  failureMode: Schema.optional(Schema.Literals(['open', 'closed'])),
+});
+
+export interface Config {
+  /** Collector token, or why the collector can't use one. */
+  readonly token: string | Error;
+  readonly baseURL: string;
+  readonly timeoutMillis: number;
+  readonly failureMode: FailureMode;
+}
+
+/**
+ * The collector config from plugin `options` and `env`.
+ */
+export function config(
+  options: unknown,
+  env: Readonly<Record<string, string | undefined>>
+): Config {
+  const decoded = Schema.decodeUnknownExit(Options)(options);
+  const opts = Exit.isSuccess(decoded) ? decoded.value : {};
+  const token = opts.token ?? env.CS_AIDR_TOKEN;
+  const baseURL =
+    opts.baseURL ??
+    env.CS_AIDR_BASE_URL ??
+    'https://api.crowdstrike.com/aidr/aiguard';
+  const url = URL.parse(baseURL);
+  return {
+    token: Exit.isFailure(decoded)
+      ? new Error(`invalid plugin options: ${decoded.cause}`)
+      : url?.protocol !== 'https:' || !ALLOWED_HOST.test(url.hostname)
+        ? new Error(
+            `base URL ${baseURL} is not HTTPS on *.crowdstrike.com or *.collector-crowdstrike.com`
+          )
+        : (token ?? new Error('CS_AIDR_TOKEN is not set')),
+    baseURL,
+    timeoutMillis: (opts.timeout ?? 30) * 1000,
+    failureMode: opts.failureMode ?? 'closed',
+  };
+}
+
+const ToolCall = Schema.Struct({
+  id: Schema.String,
+  type: Schema.Literal('function'),
+  function: Schema.Struct({
+    name: Schema.String,
+    /** JSON-encoded arguments. */
+    arguments: Schema.String,
+  }),
+});
+
+/** An OpenAI Chat Completions message. */
+const Message = Schema.Union([
+  Schema.Struct({ role: Schema.Literal('user'), content: Schema.String }),
+  Schema.Struct({
+    role: Schema.Literal('assistant'),
+    content: Schema.optional(Schema.NullOr(Schema.String)),
+    tool_calls: Schema.Array(ToolCall),
+  }),
+  Schema.Struct({
+    role: Schema.Literal('tool'),
+    tool_call_id: Schema.String,
+    content: Schema.String,
+  }),
+]);
+type Message = typeof Message.Type;
+
+/**
+ * `guard_input` as sent, and `guard_output` as returned with redactions
+ * applied.
+ */
+const GuardInput = Schema.Struct({ messages: Schema.Array(Message) });
+
+/**
+ * What the collector knows about the OpenCode process and session beyond the
+ * hook event.
+ */
+export interface Meta {
+  readonly user: string | undefined;
+  /** Directory of the plugin's OpenCode location. */
+  readonly directory: string;
+  readonly version: string;
+  readonly processID: number;
+  /** Model of the session's latest model request, if any. */
+  readonly model: Model.Ref | undefined;
+  readonly sensorAID: string | undefined;
+}
+
+/**
+ * The Falcon sensor agent ID in `reg query <CSAgent\Sim> /v AG` output, as
+ * lowercase hex. `undefined` unless `AG` holds exactly 16 bytes.
+ */
+export function windowsSensorAID(regOutput: string): string | undefined {
+  return /^\s*AG\s+REG_BINARY\s+([0-9A-F]{32})\s*$/im
+    .exec(regOutput)?.[1]
+    ?.toLowerCase();
+}
+
+/**
+ * The Falcon sensor agent ID in `falconctl info` output, as lowercase hex.
+ * `undefined` unless the plist's `aid` holds 32 hex digits.
+ */
+export function macSensorAID(falconctlOutput: string): string | undefined {
+  let info: plist.PlistValue;
+  try {
+    info = plist.parse(falconctlOutput);
+  } catch {
+    return undefined;
+  }
+  const aid =
+    typeof info === 'object' && info !== null && 'aid' in info
+      ? info.aid
+      : undefined;
+  return typeof aid === 'string' && /^[0-9A-F]{32}$/i.test(aid)
+    ? aid.toLowerCase()
+    : undefined;
+}
+
+export type PromptEvent = SessionPrompt;
+export type ToolInputEvent = ToolHooks['execute.before'];
+export type ToolOutputEvent = ToolHooks['execute.after'] & {
+  readonly status: 'completed';
+};
+
+export function promptRequest(
+  event: PromptEvent,
+  meta: Meta
+): ChatCompletionsGuard {
+  return request(
+    'input',
+    'session.prompt',
+    event.sessionID,
+    [{ role: 'user', content: event.prompt.text }],
+    meta
+  );
+}
+
+export function toolInputRequest(
+  event: ToolInputEvent,
+  meta: Meta
+): ChatCompletionsGuard {
+  return request(
+    'tool_input',
+    'tool.execute.before',
+    event.sessionID,
+    [toolCall(event)],
+    meta,
+    event
+  );
+}
+
+export function toolOutputRequest(
+  event: ToolOutputEvent,
+  meta: Meta
+): ChatCompletionsGuard {
+  const output = {
+    role: 'tool',
+    tool_call_id: event.id,
+    content: outputText(event.result),
+  } as const;
+  return request(
+    'tool_output',
+    'tool.execute.after',
+    event.sessionID,
+    [toolCall(event), output],
+    meta,
+    event
+  );
+}
+
+function request(
+  eventType: 'input' | 'tool_input' | 'tool_output',
+  hook: 'session.prompt' | 'tool.execute.before' | 'tool.execute.after',
+  sessionID: string,
+  messages: readonly Message[],
+  meta: Meta,
+  tool?: { readonly tool: string; readonly agent: string }
+): ChatCompletionsGuard {
+  return {
+    guard_input: { messages },
+    event_type: eventType,
+    llm_provider: meta.model?.providerID,
+    model: meta.model?.id,
+    session_id: sessionID,
+    user_id: meta.user,
+    agent_type: 'code-assistant',
+    is_agent: true,
+    process_id: String(meta.processID),
+    process_tags: [OPENCODE_PROCESS_TAG],
+    extra_info: {
+      app_name: 'OpenCode',
+      app_version: meta.version,
+      user_name: meta.user,
+      opencode_hook_name: hook,
+      opencode_directory: meta.directory,
+      opencode_tool_name: tool?.tool,
+      opencode_agent: tool?.agent,
+      sensor_aid: meta.sensorAID,
+    },
+  };
+}
+
+function toolCall(event: ToolInputEvent | ToolOutputEvent): Message {
+  return {
+    role: 'assistant',
+    content: null,
+    tool_calls: [
+      {
+        id: event.id,
+        type: 'function',
+        function: {
+          name: event.tool,
+          arguments: JSON.stringify(event.input) ?? 'null',
+        },
+      },
+    ],
+  };
+}
+
+function outputText({ content, output }: Tool.Result): string {
+  if (typeof content === 'string') return content;
+  if (content !== undefined && content.length > 0)
+    return content
+      .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+      .join('\n');
+  return typeof output === 'string' ? output : (JSON.stringify(output) ?? '');
+}
+
+export type Verdict =
+  | { readonly type: 'allow' }
+  | { readonly type: 'block'; readonly reason: string }
+  /** The redacted copy of the last message sent. */
+  | { readonly type: 'redact'; readonly message: Message };
+
+type GuardResult = AidrPostV1GuardChatCompletionsResponses[200]['result'];
+
+/**
+ * The verdict in a successful Falcon Guardian response. Throws if a redaction
+ * has no usable `guard_output`.
+ */
+export function verdict(res: {
+  readonly summary?: string;
+  readonly result?: GuardResult;
+}): Verdict {
+  if (res.result?.blocked)
+    return {
+      type: 'block',
+      reason: `Falcon Guardian: ${res.summary ?? 'blocked by policy'}`,
+    };
+  if (!res.result?.transformed) return { type: 'allow' };
+  const message = Schema.decodeUnknownSync(GuardInput)(
+    res.result.guard_output
+  ).messages.at(-1);
+  if (message === undefined) throw new Error('guard_output has no messages');
+  return { type: 'redact', message };
+}
+
+/** The verdict when Falcon Guardian can't give one because of `error`. */
+export function failure(mode: FailureMode, error: unknown): Verdict {
+  return mode === 'open'
+    ? { type: 'allow' }
+    : { type: 'block', reason: `Falcon Guardian: ${error}` };
+}
+
+/**
+ * Rewrite the prompt for `verdict`. Returns the reason to reject the prompt
+ * with, if any.
+ */
+export function applyToPrompt(
+  event: PromptEvent,
+  verdict: Verdict
+): string | undefined {
+  if (verdict.type === 'allow') return undefined;
+  if (verdict.type === 'block') return verdict.reason;
+  if (verdict.message.role !== 'user')
+    throw new Error("guard_output doesn't end with a user message");
+  const { files, agents, skills } = event.prompt;
+  // Mention offsets point into the original text.
+  event.prompt = {
+    text: verdict.message.content,
+    files: files?.map(({ mention: _, ...file }) => file),
+    agents: agents?.map(({ mention: _, ...agent }) => agent),
+    skills: skills?.map(({ mention: _, ...skill }) => skill),
+  };
+  return undefined;
+}
+
+/**
+ * Rewrite the tool input for `verdict`. Returns the reason to reject the call
+ * with, if any.
+ */
+export function applyToToolInput(
+  event: ToolInputEvent,
+  verdict: Verdict
+): string | undefined {
+  if (verdict.type === 'allow') return undefined;
+  if (verdict.type === 'block') return verdict.reason;
+  const call =
+    verdict.message.role === 'assistant'
+      ? verdict.message.tool_calls[0]
+      : undefined;
+  if (call === undefined)
+    throw new Error("guard_output doesn't end with a tool call");
+  event.input = JSON.parse(call.function.arguments);
+  return undefined;
+}
+
+/**
+ * Rewrite the tool output for `verdict`. Returns the reason to reject the
+ * output with, if any.
+ */
+export function applyToToolOutput(
+  event: ToolOutputEvent,
+  verdict: Verdict
+): string | undefined {
+  if (verdict.type === 'allow') return undefined;
+  if (verdict.type === 'block') return verdict.reason;
+  if (verdict.message.role !== 'tool')
+    throw new Error("guard_output doesn't end with a tool message");
+  event.result = { content: verdict.message.content };
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/** Falcon Guardian collector for OpenCode. */
+
+import { AIGuard, type ChatCompletionsGuard } from '@crowdstrike/aidr';
+import { type Model, Plugin } from '@opencode/plugin/effect';
+import { Tool } from '@opencode/schema/tool';
+import { Cause, Effect } from 'effect';
+import { safeExeca } from 'safe-execa';
+import * as guard from './guard.ts';
+
+/** Keep the thrown error, so its message reaches the log and closed reasons. */
+const unwrap = (error: unknown) => error;
+const attempt = <A>(f: () => A) => Effect.try({ try: f, catch: unwrap });
+
+const REG_KEY = 'HKLM\\System\\CurrentControlSet\\services\\CSAgent\\Sim';
+const FALCONCTL = '/Applications/Falcon.app/Contents/Resources/falconctl';
+
+/** `parse` of the command's stdout. `undefined` on any failure. */
+const readCommand = (
+  file: string,
+  args: readonly string[],
+  parse: (stdout: string) => string | undefined
+): Effect.Effect<string | undefined> =>
+  Effect.tryPromise(() => safeExeca(file, args, { timeout: 5000 })).pipe(
+    Effect.map(({ stdout }) =>
+      typeof stdout === 'string' ? parse(stdout) : undefined
+    ),
+    Effect.orElseSucceed(() => undefined)
+  );
+
+/**
+ * The Falcon sensor agent ID from the Windows registry or macOS `falconctl`.
+ * `undefined` on other platforms or on any failure.
+ */
+const readSensorAID: Effect.Effect<string | undefined> =
+  process.platform === 'win32'
+    ? readCommand('reg', ['query', REG_KEY, '/v', 'AG'], guard.windowsSensorAID)
+    : process.platform === 'darwin'
+      ? readCommand(FALCONCTL, ['info'], guard.macSensorAID)
+      : Effect.succeed(undefined);
+
+export default Plugin.define({
+  id: 'falcon-guardian',
+  effect: Effect.fn(function* (ctx) {
+    const config = guard.config(ctx.options, process.env);
+    if (config.token instanceof Error)
+      yield* Effect.logError(`Falcon Guardian: ${config.token.message}`);
+    const client =
+      typeof config.token === 'string'
+        ? new AIGuard({
+            token: config.token,
+            baseURLTemplate: config.baseURL,
+            timeout: config.timeoutMillis,
+          })
+        : undefined;
+    const user = process.env.USER ?? process.env.USERNAME;
+    const sensorAID = yield* readSensorAID;
+    const models = new Map<string, Model.Ref>();
+    const meta = (sessionID: string): guard.Meta => ({
+      user,
+      directory: ctx.location.directory,
+      version: ctx.app.version,
+      processID: process.pid,
+      model: models.get(sessionID),
+      sensorAID,
+    });
+
+    const ask = (request: ChatCompletionsGuard) =>
+      client === undefined
+        ? Effect.fail(config.token)
+        : Effect.tryPromise({
+            try: (signal) => client.guardChatCompletions(request, { signal }),
+            catch: unwrap,
+          }).pipe(
+            Effect.timeoutOrElse({
+              duration: config.timeoutMillis,
+              orElse: () =>
+                Effect.fail(
+                  new Error(
+                    `AIDR gave no verdict within ${config.timeoutMillis} ms`
+                  )
+                ),
+            }),
+            Effect.flatMap((res) =>
+              res.status === 'Success'
+                ? attempt(() => guard.verdict(res))
+                : Effect.fail(
+                    new Error(
+                      `AIDR returned ${res.status}: ${res.summary ?? ''}`
+                    )
+                  )
+            )
+          );
+
+    /** Build the request, get the verdict, and apply it. */
+    const guarded = <A>(
+      build: () => ChatCompletionsGuard,
+      apply: (verdict: guard.Verdict) => A
+    ) =>
+      attempt(build).pipe(
+        Effect.flatMap(ask),
+        Effect.flatMap((verdict) => attempt(() => apply(verdict))),
+        Effect.catchCause((cause) => {
+          const error = Cause.squash(cause);
+          return Effect.logWarning('Falcon Guardian: no verdict', cause).pipe(
+            Effect.as(
+              apply(
+                guard.failure(
+                  config.failureMode,
+                  error instanceof Error ? error.message : error
+                )
+              )
+            )
+          );
+        })
+      );
+
+    // The prompt and execute.after hooks have no error channel, so a block is a
+    // defect. OpenCode then fails the prompt request or the turn.
+    const die = (reason: string | undefined) =>
+      reason === undefined ? Effect.void : Effect.die(new Error(reason));
+
+    yield* ctx.session.hook('context', (event) =>
+      Effect.sync(() => void models.set(event.sessionID, event.model))
+    );
+
+    yield* ctx.session.hook('prompt', (event) =>
+      guarded(
+        () => guard.promptRequest(event, meta(event.sessionID)),
+        (verdict) => guard.applyToPrompt(event, verdict)
+      ).pipe(Effect.flatMap(die))
+    );
+
+    yield* ctx.tool.hook('execute.before', (event) =>
+      guarded(
+        () => guard.toolInputRequest(event, meta(event.sessionID)),
+        (verdict) => guard.applyToToolInput(event, verdict)
+      ).pipe(
+        Effect.flatMap((reason) =>
+          reason === undefined
+            ? Effect.void
+            : Effect.fail(new Tool.Error({ message: reason }))
+        )
+      )
+    );
+
+    yield* ctx.tool.hook('execute.after', (event) =>
+      event.status === 'completed'
+        ? guarded(
+            () => guard.toolOutputRequest(event, meta(event.sessionID)),
+            (verdict) => guard.applyToToolOutput(event, verdict)
+          ).pipe(Effect.flatMap(die))
+        : Effect.void
+    );
+  }),
+});