@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-hooks/assets/opencode-plugin.template.ts

@@ -0,0 +1,224 @@
+// AUTO-GENERATED by packages/agent-hooks (src/deploy/opencode-template.ts). Do not edit by hand.
+// Source: assets/hooks.json -> ONE OpenCode project plugin.
+//
+// Projected via fallback (owner rule: an event with no documented OpenCode
+// equivalent runs on a substitute event instead — see
+// this surface's `eventFallback` in packages/agent-hooks/deploy-profile.json):
+__ADL_FALLBACK_ENTRIES__
+
+interface HookCommandSpec {
+  command: string;
+  matcher?: string;
+  timeoutMs?: number;
+  fallbackFor?: string;
+}
+
+interface ToolHookInput {
+  tool: string;
+  sessionID?: string;
+  callID?: string;
+}
+
+interface ToolHookOutput {
+  args: Record<string, unknown>;
+}
+
+const HOOKS_TOOL_EXECUTE_BEFORE: HookCommandSpec[] = [
+__ADL_ARRAY_HOOKS_TOOL_EXECUTE_BEFORE__
+];
+
+const HOOKS_TOOL_EXECUTE_AFTER: HookCommandSpec[] = [
+__ADL_ARRAY_HOOKS_TOOL_EXECUTE_AFTER__
+];
+
+const HOOKS_CHAT_MESSAGE: HookCommandSpec[] = [
+__ADL_ARRAY_HOOKS_CHAT_MESSAGE__
+];
+
+const HOOKS_EVENT_SESSION_CREATED: HookCommandSpec[] = [
+__ADL_ARRAY_HOOKS_EVENT_SESSION_CREATED__
+];
+
+const HOOKS_EVENT_SESSION_IDLE: HookCommandSpec[] = [
+__ADL_ARRAY_HOOKS_EVENT_SESSION_IDLE__
+];
+
+const PLUGIN_NAME = "__ADL_PLUGIN_NAME__";
+
+
+async function runHookCommand(
+  spec: HookCommandSpec,
+  payload: Record<string, unknown>,
+  cwd: string,
+): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["/bin/sh", "-c", spec.command], {
+      cwd,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      ...(spec.timeoutMs ? { timeout: spec.timeoutMs, killSignal: "SIGTERM" } : {}),
+    });
+    proc.stdin.write(JSON.stringify(payload));
+    proc.stdin.end();
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    await proc.exited;
+    if (proc.exitCode !== 0 && proc.exitCode !== 2) {
+      console.error("[" + PLUGIN_NAME + "] hook command exited " + proc.exitCode + ": " + spec.command);
+    }
+    return { exitCode: proc.exitCode, stdout, stderr };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[" + PLUGIN_NAME + "] hook command crashed: " + spec.command + " -- " + message);
+    return { exitCode: null, stdout: "", stderr: message };
+  }
+}
+
+function denyReason(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
+  if (result.exitCode === 2) {
+    return result.stderr.trim() || "PreToolUse hook denied the call (exit code 2)";
+  }
+  try {
+    const parsed = JSON.parse(result.stdout) as {
+      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string };
+    };
+    if (parsed?.hookSpecificOutput?.permissionDecision === "deny") {
+      return parsed.hookSpecificOutput.permissionDecisionReason || "PreToolUse hook denied the call";
+    }
+  } catch {
+    // stdout was not JSON -- not a deny signal.
+  }
+  return undefined;
+}
+
+function applyUpdatedInput(
+  result: { stdout: string },
+  output: ToolHookOutput,
+): void {
+  let parsed: { hookSpecificOutput?: { updatedInput?: unknown } } | undefined;
+  try {
+    parsed = JSON.parse(result.stdout) as { hookSpecificOutput?: { updatedInput?: unknown } };
+  } catch {
+    return;
+  }
+  if (!parsed || !parsed.hookSpecificOutput || !Object.prototype.hasOwnProperty.call(parsed.hookSpecificOutput, "updatedInput")) {
+    return;
+  }
+  const updated = parsed.hookSpecificOutput.updatedInput;
+  if (typeof updated !== "object" || updated === null || Array.isArray(updated)) {
+    throw new Error("PreToolUse hook returned hookSpecificOutput.updatedInput that is not an object");
+  }
+  const record = updated as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    output.args[key] = record[key];
+  }
+}
+
+const adlPromptContext = new Map<string, string>();
+
+function extractHookContext(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
+  const trimmed = result.stdout.trim();
+  if (!trimmed) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed) as { hookSpecificOutput?: { additionalContext?: string } };
+    const additional = parsed?.hookSpecificOutput?.additionalContext;
+    if (typeof additional === "string" && additional.trim()) {
+      return additional.trim();
+    }
+  } catch {
+    // stdout was not JSON -- treat it as plain-text context.
+  }
+  return trimmed;
+}
+
+export const __ADL_PLUGIN_IDENTIFIER__ = async ({ directory }: { directory: string }) => {
+  return {
+  "chat.message": async (input: any, output: any) => {
+    const parts = output && Array.isArray(output.parts) ? output.parts : [];
+    const promptText = parts.filter((p: any) => p && p.type === "text").map((p: any) => p.text).join(" ");
+    let context: string | undefined;
+    for (const spec of HOOKS_CHAT_MESSAGE) {
+      const payload = {
+        hook_event_name: "UserPromptSubmit",
+        prompt: promptText,
+        cwd: directory,
+        session_id: input && input.sessionID,
+      };
+      const result = await runHookCommand(spec, payload, directory);
+      const extracted = extractHookContext(result);
+      if (extracted) context = context ? context + " " + extracted : extracted;
+    }
+    const sessionID = input && input.sessionID;
+    if (sessionID) {
+      if (context) adlPromptContext.set(sessionID, context);
+      else adlPromptContext.delete(sessionID);
+    }
+  },
+  "experimental.chat.system.transform": async (input: any, output: any) => {
+    const sessionID = input && input.sessionID;
+    if (!sessionID) return;
+    const context = adlPromptContext.get(sessionID);
+    if (context && output && Array.isArray(output.system)) {
+      output.system.push(context);
+    }
+  },
+  "tool.execute.before": async (input: ToolHookInput, output: ToolHookOutput) => {
+    for (const spec of HOOKS_TOOL_EXECUTE_BEFORE) {
+      if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
+      const payload = {
+        hook_event_name: "PreToolUse",
+        tool_name: input.tool,
+        tool_input: output.args,
+        cwd: directory,
+        session_id: input.sessionID,
+      };
+      const result = await runHookCommand(spec, payload, directory);
+      const reason = denyReason(result);
+      if (reason) throw new Error(reason);
+      applyUpdatedInput(result, output);
+    }
+  },
+  "tool.execute.after": async (input: ToolHookInput, output: ToolHookOutput) => {
+    for (const spec of HOOKS_TOOL_EXECUTE_AFTER) {
+      if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
+      const payload = {
+        hook_event_name: "PostToolUse",
+        tool_name: input.tool,
+        tool_input: output.args,
+        cwd: directory,
+        session_id: input.sessionID,
+      };
+      const result = await runHookCommand(spec, payload, directory);
+      // PostToolUse cannot block: the tool call already completed.
+    }
+  },
+  event: async ({ event }: { event: any }) => {
+    if (event && event.type === "session.created") {
+      for (const spec of HOOKS_EVENT_SESSION_CREATED) {
+        const payload = {
+          hook_event_name: "SessionStart",
+          cwd: directory,
+          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
+        };
+        await runHookCommand(spec, payload, directory);
+      }
+    }
+    if (event && event.type === "session.idle") {
+      for (const spec of HOOKS_EVENT_SESSION_IDLE) {
+        const payload = {
+          hook_event_name: "SessionIdle",
+          cwd: directory,
+          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
+          ...(spec.fallbackFor ? { fallback_for: spec.fallbackFor } : {}),
+        };
+        await runHookCommand(spec, payload, directory);
+      }
+    }
+  },
+  };
+};
+
+export default __ADL_PLUGIN_IDENTIFIER__;

package/packages/agent-hooks/bunfig.toml

@@ -0,0 +1,27 @@
+# Coverage is a build gate, not a report — ported from enact-repo-controls-m5.
+#
+# coveragePathIgnorePatterns is deliberately and permanently EMPTY. An
+# allowlist is where 100% goes to die: the first entry is always justified,
+# and by the tenth nobody remembers what is uncovered. Anything that "cannot
+# be covered" is restructured until it can (e.g. rules/registry.ts's
+# requireRegistered replacing an unreachable module-load throw).
+# test/unit/coverage-policy.test.ts asserts this list stays empty, the
+# thresholds stay at 100%, and `bun run check` keeps running `--coverage`.
+#
+# Unlike controls, `coverage` itself is not forced on here: `bun run check`
+# passes `--coverage`, so a targeted `bun test <file>` run is not failed by the
+# whole-suite threshold.
+
+[test]
+preload = ["./tests/preload-policy.ts"]
+coverageSkipTestFiles = true
+coverageReporter = ["text"]
+
+# Keys are `lines` / `functions` (plural). Bun 1.4.2 silently IGNORES the
+# singular `line` / `function` keys enact-repo-controls-m5 used — measured: a
+# 47%-covered run exited 0 under controls' form and 1 under this one — so the
+# controls gate never actually enforced anything. coverage-policy.test.ts
+# asserts the plural keys and proves a below-threshold run exits non-zero.
+[test.coverageThreshold]
+lines = 1.0
+functions = 1.0

package/packages/agent-hooks/deploy-profile.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "./deploy-profile.schema.json",
+  "source": "assets/hooks.json",
+  "legacyLock": ".agents/adl-repo.lock.json",
+  "surfaces": [
+    {
+      "name": "claude",
+      "format": "claude-settings",
+      "file": ".claude/settings.json",
+      "hostSuffix": "claude"
+    },
+    {
+      "name": "codex",
+      "format": "codex-hooks",
+      "file": ".codex/hooks.json",
+      "hostSuffix": "codex",
+      "timeoutOverrides": { "adl hook crg session-stop": 3 }
+    },
+    {
+      "name": "cursor",
+      "format": "cursor-hooks-v1",
+      "file": ".cursor/hooks.json",
+      "hostSuffix": "cursor",
+      "eventNames": {
+        "PreToolUse": "preToolUse",
+        "UserPromptSubmit": "beforeSubmitPrompt",
+        "SessionStart": "sessionStart",
+        "PostToolUse": "postToolUse",
+        "SessionEnd": "sessionEnd"
+      },
+      "matchers": {
+        "Bash": "Shell",
+        "Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file": "Write"
+      },
+      "unmappedMatcher": "drop"
+    },
+    {
+      "name": "opencode",
+      "format": "opencode-plugin",
+      "file": ".opencode/plugins/adl-repo.ts",
+      "hostSuffix": "opencode",
+      "matchers": {
+        "Bash": "bash",
+        "Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file": "write|edit"
+      },
+      "unmappedMatcher": "keep",
+      "timeoutUnit": "ms",
+      "template": "opencode-plugin.template.ts",
+      "pluginName": "adl-repo",
+      "eventFallback": { "SessionEnd": "SessionIdle" }
+    }
+  ]
+}

package/packages/agent-hooks/deploy-profile.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "agent-hooks deploy profile",
+  "description": "The ONLY definition of the hook deploy profile's shape (mirrors packages/agent-skills' deploy-profile.schema.json, D2). Declares which repo-relative file each agent surface's hook wiring is written to, in what wire format, and how assets/hooks.json's canonical event names, matchers and timeouts translate for that surface. src/deploy/profile.ts validates every profile against this schema via ajv and adds only the two cross-field checks a JSON Schema cannot express (duplicate surface name, duplicate surface file) — everything else (required fields, formats, string/number record shapes, and which fields an opencode-plugin surface requires vs. forbids) is enforced here.",
+  "type": "object",
+  "required": ["source", "surfaces"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repo-relative path (from the package root) to the canonical hooks document, e.g. assets/hooks.json."
+    },
+    "surfaces": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "oneOf": [{ "$ref": "#/definitions/opencodePluginSurface" }, { "$ref": "#/definitions/jsonHooksSurface" }] }
+    },
+    "legacyLock": {
+      "type": "string",
+      "pattern": "^\\.[A-Za-z0-9_./-]+$",
+      "description": "Repo-relative path to the pre-agent-hooks engine's own install lock (e.g. .agents/adl-repo.lock.json), if this repo may still carry one. When present, deploy takes over a hook entry whose content hash matches a sha256 that lock recorded under merged[<surface file>].entries at path [\"hooks\", <event>] (H-takeover, Tarun 2026-09-28) instead of treating it as foreign, and rewrites the opencode-plugin file when its whole-file hash matches the lock's files[<surface file>].sha256. Optional: a profile with no legacy engine to migrate from omits it."
+    }
+  },
+  "definitions": {
+    "stringRecord": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "positiveNumberRecord": {
+      "type": "object",
+      "additionalProperties": { "type": "number", "exclusiveMinimum": 0 }
+    },
+    "commonSurfaceProperties": {
+      "name": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Short surface identifier, e.g. claude, codex, cursor, opencode."
+      },
+      "file": {
+        "type": "string",
+        "pattern": "^\\.[A-Za-z0-9_./-]+$",
+        "description": "Repo-relative target file, e.g. .claude/settings.json."
+      },
+      "hostSuffix": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Appended to every command as ' --host=<hostSuffix>'."
+      },
+      "eventNames": {
+        "$ref": "#/definitions/stringRecord",
+        "description": "Canonical event name (PreToolUse, UserPromptSubmit, SessionStart, PostToolUse, SessionEnd) -> this surface's own event name. Omitted keys keep the canonical name unchanged."
+      },
+      "matchers": {
+        "$ref": "#/definitions/stringRecord",
+        "description": "Source matcher string -> this surface's own matcher string. A source matcher absent from this map falls back to unmappedMatcher."
+      },
+      "unmappedMatcher": {
+        "type": "string",
+        "enum": ["keep", "drop"],
+        "description": "What to do with a source matcher not listed in `matchers`: keep it verbatim (default), or drop the matcher field entirely."
+      },
+      "timeoutOverrides": {
+        "$ref": "#/definitions/positiveNumberRecord",
+        "description": "Full source command (before --host is appended, e.g. 'adl hook crg session-stop') -> a timeout in the SOURCE unit (seconds) that replaces assets/hooks.json's own timeout for this surface only."
+      },
+      "timeoutUnit": {
+        "type": "string",
+        "enum": ["s", "ms"],
+        "description": "Unit this surface's rendered timeout is expressed in. Default 's' (assets/hooks.json's own unit); opencode-plugin uses 'ms'."
+      }
+    },
+    "opencodePluginSurface": {
+      "type": "object",
+      "required": ["name", "format", "file", "hostSuffix", "template", "pluginName"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "$ref": "#/definitions/commonSurfaceProperties/name" },
+        "format": { "const": "opencode-plugin" },
+        "file": { "$ref": "#/definitions/commonSurfaceProperties/file" },
+        "hostSuffix": { "$ref": "#/definitions/commonSurfaceProperties/hostSuffix" },
+        "matchers": { "$ref": "#/definitions/commonSurfaceProperties/matchers" },
+        "unmappedMatcher": { "$ref": "#/definitions/commonSurfaceProperties/unmappedMatcher" },
+        "timeoutOverrides": { "$ref": "#/definitions/commonSurfaceProperties/timeoutOverrides" },
+        "timeoutUnit": { "$ref": "#/definitions/commonSurfaceProperties/timeoutUnit" },
+        "template": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Template asset path, relative to assets/, e.g. opencode-plugin.template.ts."
+        },
+        "pluginName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The plugin's kebab-case name, e.g. adl-repo. Fills PLUGIN_NAME and (camelCased + \"Plugin\") the exported identifier."
+        },
+        "eventFallback": {
+          "$ref": "#/definitions/stringRecord",
+          "description": "Canonical event -> the OpenCode event it is projected onto because OpenCode has no native equivalent, e.g. {\"SessionEnd\": \"SessionIdle\"}."
+        }
+      }
+    },
+    "jsonHooksSurface": {
+      "type": "object",
+      "required": ["name", "format", "file", "hostSuffix"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "$ref": "#/definitions/commonSurfaceProperties/name" },
+        "format": { "enum": ["claude-settings", "codex-hooks", "cursor-hooks-v1"] },
+        "file": { "$ref": "#/definitions/commonSurfaceProperties/file" },
+        "hostSuffix": { "$ref": "#/definitions/commonSurfaceProperties/hostSuffix" },
+        "eventNames": { "$ref": "#/definitions/commonSurfaceProperties/eventNames" },
+        "matchers": { "$ref": "#/definitions/commonSurfaceProperties/matchers" },
+        "unmappedMatcher": { "$ref": "#/definitions/commonSurfaceProperties/unmappedMatcher" },
+        "timeoutOverrides": { "$ref": "#/definitions/commonSurfaceProperties/timeoutOverrides" },
+        "timeoutUnit": { "$ref": "#/definitions/commonSurfaceProperties/timeoutUnit" }
+      }
+    }
+  }
+}

package/packages/agent-hooks/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@adl/agent-hooks",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Agent hook runtime (pre-tool-use guard, user-prompt-submit skill suggestions, briefing, crg) for Claude Code, Codex, Cursor, Kimi, and OpenCode, built as a single compiled bun build --compile binary and installed fleet-wide at /usr/local/bin/adl by fleet.",
+  "scripts": {
+    "start": "bun src/main.ts",
+    "build": "bun ../../workflows/scripts/build/agent-hooks/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --timeout 30000",
+    "test:coverage": "bun test --coverage --timeout 30000",
+    "check": "bun run typecheck && bun test --coverage"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "minisearch": "7.2.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/bun": "latest"
+  }
+}

package/packages/agent-hooks/src/cli/args.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared argv parsing and repo resolution for the non-hook commands
+ * (`adl hook rules ...`, `adl hook doctor`).
+ *
+ * Repo resolution is exactly the hook runtime's own (`main.ts`): walk up from
+ * the start directory to the git root and look for `adl-config.toml`
+ * there (`../gating/root.ts`), then decode it with `../gating/config.ts`. The
+ * only difference is the start directory — `--repo <path>` (resolved against
+ * cwd) instead of a host payload's cwd.
+ */
+
+import { readFileSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decodeConfig, type AdlRepoConfig } from '../gating/config.ts'
+import { MARKER, realRootIO, resolveManagedRepo } from '../gating/root.ts'
+import type { HookResult } from '../hooks/contract.ts'
+
+/** Same `{ stdout, stderr, exitCode }` shape every hook handler returns; `main.ts` writes it out. */
+export type CliResult = HookResult
+
+export function cliError(message: string): CliResult {
+  return { stdout: '', stderr: `adl hook: ${message}\n`, exitCode: 1 }
+}
+
+export interface ParsedArgs {
+  readonly positionals: readonly string[]
+  readonly repo: string | undefined
+  readonly json: boolean
+}
+
+/** Parse `[--repo <path>|--repo=<path>] [--json]` plus positionals. `allowJson` false rejects `--json` as unknown. */
+export function parseArgs(argv: readonly string[], allowJson: boolean): ParsedArgs | { readonly error: string } {
+  const positionals: string[] = []
+  let repo: string | undefined
+  let json = false
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] as string
+    if (arg === '--repo' || arg.startsWith('--repo=')) {
+      const value = arg === '--repo' ? argv[++index] : arg.slice('--repo='.length)
+      if (value === undefined || value === '') return { error: '--repo requires a path' }
+      repo = value
+    } else if (arg === '--json' && allowJson) {
+      json = true
+    } else if (arg.startsWith('-')) {
+      return { error: `unknown option '${arg}'` }
+    } else {
+      positionals.push(arg)
+    }
+  }
+  return { positionals, repo, json }
+}
+
+export interface RepoState {
+  readonly start: string
+  readonly root: string | null
+  readonly managed: boolean
+  readonly configPath: string | null
+}
+
+export type LoadedRepo =
+  | { readonly ok: true; readonly state: RepoState; readonly config: AdlRepoConfig }
+  | { readonly ok: false; readonly state: RepoState; readonly error: string }
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** The built-in config an unmanaged repo is described with — the decode of an empty file, i.e. the schema defaults. */
+export function defaultConfig(): AdlRepoConfig {
+  return (decodeConfig('') as { readonly value: AdlRepoConfig }).value
+}
+
+/**
+ * Resolve the start directory (`--repo` against cwd, else cwd) and load the
+ * repo's config. `null` when `--repo` is not a directory. An unmanaged repo
+ * loads the built-in defaults; a managed repo whose config fails to decode is
+ * `ok: false` carrying the exact message `main.ts` prints for the same file.
+ */
+export function loadRepo(cwd: string, repoArg: string | undefined): LoadedRepo | null {
+  const start = resolve(cwd, repoArg ?? '.')
+  if (!isDirectory(start)) return null
+  const managed = resolveManagedRepo(realRootIO, start)
+  const state: RepoState = { start, root: managed.root, managed: managed.managed, configPath: managed.configPath }
+  if (managed.configPath === null) return { ok: true, state, config: defaultConfig() }
+  const decoded = decodeConfig(readFileSync(managed.configPath, 'utf8'))
+  if (!decoded.ok) {
+    return { ok: false, state, error: `invalid ${managed.configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}` }
+  }
+  return { ok: true, state, config: decoded.value }
+}
+
+/** Why a repo is unmanaged, phrased for a report line. */
+export function unmanagedReason(state: RepoState): string {
+  return state.root === null ? `no git root found above ${state.start}` : `no ${MARKER} at git root ${state.root}`
+}