@morphed/agent-hook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 peakmojo
+
+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,62 @@
+# @morphed/agent-hook
+
+Morphed pre-tool hook for **Claude Code** and **Codex** — Build Guide Mechanism C.
+A tiny program the agent runs before any tool call. It asks Morphed's decision
+service and denies the call if policy says no, **before the write happens** —
+even in bypass/yolo mode (the bypass skips prompts, not hooks).
+
+## Install (one line)
+
+```bash
+npx @morphed/agent-hook init --token <MORPHED_API_KEY> --portal <PORTAL_ID>
+```
+
+This:
+1. Detects which agents are installed (`~/.claude/settings.json`, `~/.codex/config.toml`).
+2. Writes the `PreToolUse` hook with matchers `mcp__hubspot__.*|Bash`.
+3. Stores the API key in the OS keychain (via `keytar`; falls back to a `0600`
+   `~/.morphed/agent-hook.json` if the native module isn't available).
+
+### Whole-org enforcement
+
+```bash
+npx @morphed/agent-hook init --token <KEY> --portal <ID> --org
+```
+
+`--org` writes **managed settings** so individuals can't disable it:
+- Claude Code: managed `managed-settings.json` (OS-specific path).
+- Codex: `requirements.toml` with `allow_managed_hooks_only = true`.
+
+## How the hook works
+
+`morphed-hook` reads the agent's pre-tool JSON from stdin, pulls `tool_name` +
+`tool_input`, calls `POST /v1/decision` (`surface: claude_code` or `codex`,
+HMAC-signed with the tenant key), and prints the agent's allow/deny JSON:
+
+```json
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Morphed blocked this write. … STOP — do not retry…" } }
+```
+
+- Morphed `approved` → `allow`; `blocked`/`approval_required` → `deny`;
+  `modify` → `ask`.
+- Deny copy is phrased to make the agent **stop cleanly and escalate** rather
+  than go idle or loop on a block.
+- Codex `PermissionRequest` events get the `decision.behavior` shape; both agents'
+  `PreToolUse` events get the `hookSpecificOutput.permissionDecision` shape.
+- **Fail-open**: if Morphed is unreachable or the machine isn't enrolled, the
+  hook allows the call (the backstop, Mechanism F, still catches the write) — a
+  Morphed outage never wedges the agent.
+
+## Honest limit
+
+The hook governs the machines it's installed on. It is **enrolment, not magic** —
+Morphed can't gate an agent it was never wired into. Anything outside it still
+falls to the backstop.
+
+## Tests
+
+```bash
+npm test   # 16 unit tests: both agent JSON shapes, decision mapping, HMAC, installer
+```

package/bin/cli.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * agent-hook CLI — `npx @morphed/agent-hook init`.
+ *
+ * Flags:
+ *   --token <key>      Morphed API key (the per-tenant signing secret). Or MORPHED_API_KEY.
+ *   --portal <id>      Morphed portal id. Or MORPHED_PORTAL_ID.
+ *   --api-base <url>   default https://api.morphed.io. Or MORPHED_API_BASE.
+ *   --org              write managed settings so individuals can't disable it.
+ *   --agent <name>     force a target (claude_code|codex); repeatable. Default: auto-detect.
+ */
+
+import installer from '../src/installer.mjs';
+
+function parseArgs(argv) {
+  const out = { agents: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === 'init') out.cmd = 'init';
+    else if (a === '--org') out.org = true;
+    else if (a === '--token') out.token = argv[++i];
+    else if (a === '--portal') out.portalId = argv[++i];
+    else if (a === '--api-base') out.apiBase = argv[++i];
+    else if (a === '--agent') out.agents.push(argv[++i]);
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.cmd !== 'init') {
+    console.log('Usage: npx @morphed/agent-hook init --token <key> --portal <id> [--org] [--agent claude_code|codex]');
+    process.exit(args.cmd ? 0 : 1);
+  }
+  const token = args.token || process.env.MORPHED_API_KEY;
+  const portalId = args.portalId || process.env.MORPHED_PORTAL_ID;
+  const apiBase = args.apiBase || process.env.MORPHED_API_BASE || 'https://api.morphed.io';
+  const agents = args.agents.length ? args.agents : null;
+
+  const result = await installer.init({ token, portalId, apiBase, org: !!args.org, agents });
+
+  console.log(`✅ Morphed agent hook installed.`);
+  console.log(`   API key stored via: ${result.secretStore}`);
+  console.log(`   Agents: ${result.agents.join(', ') || '(none detected — pass --agent)'}`);
+  for (const w of result.written) {
+    console.log(`   • ${w.agent}: ${w.managed ? 'managed ' : ''}${w.file}`);
+  }
+  if (result.org) console.log(`   Org-managed: individuals cannot disable this hook.`);
+  console.log(`   Matcher: ${installer.HOOK_MATCHER}`);
+}
+
+main().catch((err) => {
+  console.error(`✗ ${err.message}`);
+  process.exit(1);
+});

package/bin/morphed-hook.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * morphed-hook — the pre-tool hook binary (Mechanism C).
+ *
+ * Reads the agent's pre-tool JSON from stdin, extracts tool_name + tool_input,
+ * calls /v1/decision (surface=claude_code or codex), and prints the agent's
+ * allow/deny JSON to stdout. Exits 0 in all cases (the JSON carries the verdict;
+ * exit 2 is reserved as a hard-deny fallback if stdout can't be written).
+ */
+
+import { loadCredentials } from '../src/keychain.mjs';
+import { requestDecision } from '../src/decisionClient.mjs';
+import { buildHookOutput, toDecisionInput } from '../src/shapes.mjs';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+    // If nothing is piped, don't hang forever.
+    setTimeout(() => resolve(data), 2000);
+  });
+}
+
+function detectSurface(payload) {
+  // turn_id is Codex-specific; CODEX_* env or an explicit surface override also work.
+  if (process.env.MORPHED_HOOK_SURFACE) return process.env.MORPHED_HOOK_SURFACE;
+  if (payload.turn_id || process.env.CODEX_HOME || /codex/i.test(payload.agent || '')) return 'codex';
+  return 'claude_code';
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload = {};
+  try { payload = raw ? JSON.parse(raw) : {}; } catch { payload = {}; }
+
+  const surface = detectSurface(payload);
+  const hookEventName = payload.hook_event_name || 'PreToolUse';
+
+  const creds = await loadCredentials();
+  if (!creds.secret || !creds.portalId) {
+    // Not configured → defer to the agent's normal flow (allow) rather than block
+    // a machine that was never enrolled. (Enrolment, not magic — per the brief.)
+    process.stdout.write(JSON.stringify(buildHookOutput(surface, { decision: 'approved', reason: 'Morphed hook not configured on this machine.' }, hookEventName)));
+    return;
+  }
+
+  const input = toDecisionInput(payload, surface);
+  const decision = await requestDecision({ apiBase: creds.apiBase, portalId: creds.portalId, secret: creds.secret, input });
+  process.stdout.write(JSON.stringify(buildHookOutput(surface, decision, hookEventName)));
+}
+
+main().catch((err) => {
+  // Fail-open on unexpected error so a hook bug never wedges the agent.
+  process.stderr.write(`[morphed-hook] ${err.message}\n`);
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Morphed hook error; allowed (backstop still watching).' },
+  }));
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@morphed/agent-hook",
+  "version": "0.1.0",
+  "description": "Morphed pre-tool hook for Claude Code and Codex — gates HubSpot writes through Morphed's decision service before they happen (Build Guide Mechanism C).",
+  "type": "module",
+  "bin": {
+    "morphed-hook": "bin/morphed-hook.mjs",
+    "agent-hook": "bin/cli.mjs"
+  },
+  "exports": {
+    "./shapes": "./src/shapes.mjs",
+    "./installer": "./src/installer.mjs",
+    "./decisionClient": "./src/decisionClient.mjs"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "prepublishOnly": "npm test"
+  },
+  "engines": { "node": ">=18" },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "files": ["bin/", "src/", "README.md", "LICENSE"],
+  "keywords": [
+    "claude-code",
+    "codex",
+    "hook",
+    "pre-tool",
+    "pretooluse",
+    "hubspot",
+    "crm",
+    "governance",
+    "guardrails",
+    "agent",
+    "morphed"
+  ],
+  "homepage": "https://github.com/graemewil/Morphed_Magic_Cards_Links_V2/tree/main/packages/agent-hook#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graemewil/Morphed_Magic_Cards_Links_V2.git",
+    "directory": "packages/agent-hook"
+  },
+  "bugs": {
+    "url": "https://github.com/graemewil/Morphed_Magic_Cards_Links_V2/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/decisionClient.mjs

@@ -0,0 +1,45 @@
+/**
+ * decisionClient — Mechanism C. Signs the request body with the tenant secret
+ * (HMAC, same scheme as the server's decisionSigning) and calls /v1/decision.
+ */
+
+import crypto from 'node:crypto';
+
+export function computeSignature(secret, rawBody) {
+  const hex = crypto.createHmac('sha256', String(secret)).update(rawBody).digest('hex');
+  return `sha256=${hex}`;
+}
+
+/**
+ * @returns the parsed /v1/decision response, or a fail-open 'approved' result
+ * when Morphed is unreachable (a Morphed outage must not wedge the dev's agent;
+ * the backstop still catches the write).
+ */
+export async function requestDecision({ apiBase, portalId, secret, input, timeoutMs = 8000, fetchImpl = globalThis.fetch }) {
+  const rawBody = JSON.stringify(input);
+  const signature = computeSignature(secret, rawBody);
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetchImpl(`${apiBase.replace(/\/+$/, '')}/v1/decision`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Morphed-Portal': String(portalId),
+        'X-Morphed-Signature': signature,
+      },
+      body: rawBody,
+      signal: controller.signal,
+    });
+    if (!resp.ok) {
+      return { decision: 'approved', risk_level: 'low', reason: `Morphed check skipped (HTTP ${resp.status}); backstop still watching.`, _failOpen: true };
+    }
+    return await resp.json();
+  } catch (err) {
+    return { decision: 'approved', risk_level: 'low', reason: `Morphed unreachable (${err.message}); backstop still watching.`, _failOpen: true };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export default { computeSignature, requestDecision };

package/src/installer.mjs

@@ -0,0 +1,122 @@
+/**
+ * installer — `npx @morphed/agent-hook init`.
+ *
+ * Detects which agents are installed, writes the PreToolUse hook config
+ * (matchers mcp__hubspot__.*|Bash), and stores the API key in the OS keychain.
+ * With --org it writes managed settings so individuals can't disable it
+ * (Claude Code managed-settings.json / Codex requirements.toml).
+ *
+ * All functions accept a `home` + `platform` for testability.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const HOOK_MATCHER = 'mcp__hubspot__.*|Bash';
+const MARKER = 'morphed-agent-hook';
+
+function ensureDir(p) { if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true }); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; } }
+function writeJson(p, obj) { ensureDir(path.dirname(p)); fs.writeFileSync(p, JSON.stringify(obj, null, 2)); }
+
+/** Paths for each agent, per scope (user vs org-managed). */
+export function agentPaths({ home = os.homedir(), platform = process.platform } = {}) {
+  const claudeUser = path.join(home, '.claude', 'settings.json');
+  const codexUser = path.join(home, '.codex', 'config.toml');
+  let claudeManaged, codexManaged;
+  if (platform === 'win32') {
+    claudeManaged = path.join(process.env.ProgramData || 'C:/ProgramData', 'ClaudeCode', 'managed-settings.json');
+    codexManaged = path.join(process.env.ProgramData || 'C:/ProgramData', 'Codex', 'requirements.toml');
+  } else if (platform === 'darwin') {
+    claudeManaged = '/Library/Application Support/ClaudeCode/managed-settings.json';
+    codexManaged = '/etc/codex/requirements.toml';
+  } else {
+    claudeManaged = '/etc/claude-code/managed-settings.json';
+    codexManaged = '/etc/codex/requirements.toml';
+  }
+  return { claudeUser, codexUser, claudeManaged, codexManaged };
+}
+
+/** Which agents are installed on this machine. */
+export function detectAgents({ home = os.homedir() } = {}) {
+  const found = [];
+  if (fs.existsSync(path.join(home, '.claude'))) found.push('claude_code');
+  if (fs.existsSync(path.join(home, '.codex'))) found.push('codex');
+  return found;
+}
+
+/** Insert the Morphed PreToolUse hook into a Claude Code settings.json object. */
+export function applyClaudeHook(settings = {}, { command = 'morphed-hook' } = {}) {
+  const next = { ...settings };
+  next.hooks = next.hooks || {};
+  const list = Array.isArray(next.hooks.PreToolUse) ? next.hooks.PreToolUse.slice() : [];
+  // Idempotent: drop any prior morphed entry first.
+  const filtered = list.filter((e) => !(e?.hooks || []).some((h) => String(h.command || '').includes('morphed-hook')));
+  filtered.push({ matcher: HOOK_MATCHER, hooks: [{ type: 'command', command }] });
+  next.hooks.PreToolUse = filtered;
+  return next;
+}
+
+export function writeClaudeHook({ home = os.homedir(), platform = process.platform, org = false, command = 'morphed-hook' } = {}) {
+  const paths = agentPaths({ home, platform });
+  const file = org ? paths.claudeManaged : paths.claudeUser;
+  const settings = readJson(file);
+  const updated = applyClaudeHook(settings, { command });
+  writeJson(file, updated);
+  return { file, managed: org };
+}
+
+/** Build the Codex TOML hook block (+ requirements wrapper for org installs). */
+export function codexHookToml({ org = false, command = 'morphed-hook' } = {}) {
+  const block = [
+    `# >>> ${MARKER} >>>`,
+    ...(org ? ['allow_managed_hooks_only = true', '[features]', 'hooks = true', ''] : []),
+    '[[hooks.PreToolUse]]',
+    `matcher = "${HOOK_MATCHER}"`,
+    '',
+    '[[hooks.PreToolUse.hooks]]',
+    'type = "command"',
+    `command = "${command}"`,
+    'timeout = 15',
+    `# <<< ${MARKER} <<<`,
+    '',
+  ].join('\n');
+  return block;
+}
+
+export function writeCodexHook({ home = os.homedir(), platform = process.platform, org = false, command = 'morphed-hook' } = {}) {
+  const paths = agentPaths({ home, platform });
+  const file = org ? paths.codexManaged : paths.codexUser;
+  ensureDir(path.dirname(file));
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
+  // Idempotent: strip a prior morphed block.
+  const stripped = existing.replace(new RegExp(`# >>> ${MARKER} >>>[\\s\\S]*?# <<< ${MARKER} <<<\\n?`, 'g'), '');
+  fs.writeFileSync(file, `${stripped}${stripped && !stripped.endsWith('\n') ? '\n' : ''}${codexHookToml({ org, command })}`);
+  return { file, managed: org };
+}
+
+/**
+ * Full init. Stores credentials + writes hooks for detected (or requested)
+ * agents. Returns a summary the CLI prints.
+ */
+export async function init({ token, portalId, apiBase = 'https://api.morphed.io', org = false, agents = null, home = os.homedir(), platform = process.platform } = {}) {
+  if (!token) throw new Error('init: a Morphed API token is required (--token or MORPHED_API_KEY).');
+  if (!portalId) throw new Error('init: a portal id is required (--portal or MORPHED_PORTAL_ID).');
+
+  const keychain = (await import('./keychain.mjs')).default;
+  const stored = await keychain.storeCredentials({ portalId, apiBase, secret: token });
+
+  const targets = agents || detectAgents({ home });
+  const written = [];
+  if (targets.includes('claude_code')) written.push({ agent: 'claude_code', ...writeClaudeHook({ home, platform, org }) });
+  if (targets.includes('codex')) written.push({ agent: 'codex', ...writeCodexHook({ home, platform, org }) });
+
+  return { secretStore: stored.secretStore, agents: targets, written, org };
+}
+
+export default {
+  HOOK_MATCHER, agentPaths, detectAgents, applyClaudeHook, writeClaudeHook,
+  codexHookToml, writeCodexHook, init,
+};

package/src/keychain.mjs

@@ -0,0 +1,82 @@
+/**
+ * keychain — stores the Morphed API key (the per-tenant signing secret) in the
+ * OS keychain via keytar when available, falling back to a 0600 config file so
+ * the hook works even where the native keytar module can't be built.
+ *
+ * Non-secret config (apiBase, portalId) lives in ~/.morphed/agent-hook.json;
+ * the secret lives in the keychain (or, in fallback mode, the same file with
+ * tight perms).
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const SERVICE = 'morphed-agent-hook';
+const CONFIG_DIR = path.join(os.homedir(), '.morphed');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'agent-hook.json');
+
+async function loadKeytar() {
+  try {
+    const mod = await import('keytar');
+    return mod.default || mod;
+  } catch {
+    return null; // native module unavailable → file fallback
+  }
+}
+
+function readConfigFile() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfigFile(cfg) {
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch { /* windows */ }
+}
+
+/** Persist apiBase + portalId (non-secret) and the secret (keychain or file). */
+export async function storeCredentials({ portalId, apiBase, secret }) {
+  const cfg = readConfigFile();
+  cfg.portalId = portalId;
+  cfg.apiBase = apiBase;
+  const keytar = await loadKeytar();
+  if (keytar && secret) {
+    await keytar.setPassword(SERVICE, String(portalId), String(secret));
+    cfg.secretStore = 'keychain';
+    delete cfg.secret;
+  } else if (secret) {
+    cfg.secretStore = 'file';
+    cfg.secret = secret; // file is 0600
+  }
+  writeConfigFile(cfg);
+  return { secretStore: cfg.secretStore };
+}
+
+/** Resolve { apiBase, portalId, secret } for the hook at runtime. */
+export async function loadCredentials() {
+  // Env overrides win (useful for CI / managed/org installs).
+  const envPortal = process.env.MORPHED_PORTAL_ID;
+  const envSecret = process.env.MORPHED_API_KEY;
+  const envBase = process.env.MORPHED_API_BASE;
+  const cfg = readConfigFile();
+  const portalId = envPortal || cfg.portalId || null;
+  const apiBase = envBase || cfg.apiBase || 'https://api.morphed.io';
+  if (envSecret) return { portalId, apiBase, secret: envSecret };
+
+  if (cfg.secretStore === 'keychain' && portalId) {
+    const keytar = await loadKeytar();
+    if (keytar) {
+      const secret = await keytar.getPassword(SERVICE, String(portalId));
+      if (secret) return { portalId, apiBase, secret };
+    }
+  }
+  return { portalId, apiBase, secret: cfg.secret || null };
+}
+
+export const paths = { CONFIG_DIR, CONFIG_FILE, SERVICE };
+export default { storeCredentials, loadCredentials, paths };

package/src/shapes.mjs

@@ -0,0 +1,136 @@
+/**
+ * Agent hook output shapes — Mechanism C.
+ *
+ * Translates a Morphed decision into the allow/deny JSON each agent runtime
+ * expects from a pre-tool hook. Verified against code.claude.com/docs (Claude
+ * Code) and developers.openai.com/codex (Codex), 29 May 2026.
+ *
+ *   Claude Code (PreToolUse):
+ *     { hookSpecificOutput: { hookEventName:"PreToolUse",
+ *         permissionDecision:"allow|deny|ask", permissionDecisionReason } }
+ *
+ *   Codex (PreToolUse):  same hookSpecificOutput shape.
+ *   Codex (PermissionRequest):
+ *     { hookSpecificOutput: { hookEventName:"PermissionRequest",
+ *         decision: { behavior:"allow|deny", message } } }
+ */
+
+// Map a Morphed decision verb → an agent permission verb.
+//   approved          → allow
+//   approval_required → deny (the agent must stop and escalate to Morphed)
+//   blocked           → deny
+//   modify            → ask (let the user/agent reconsider with the corrected state)
+export function permissionFor(decision) {
+  switch (decision) {
+    case 'approved': return 'allow';
+    case 'modify': return 'ask';
+    case 'blocked':
+    case 'approval_required':
+    default: return 'deny';
+  }
+}
+
+/**
+ * Deny/escalate copy. Phrased so the agent STOPS cleanly rather than going idle
+ * or silently looping on a block (the known "agent goes idle on block" quirk):
+ * it states the verdict, says do-not-retry, and points to the resolution path.
+ */
+export function reasonText({ decision, reason, hold_token }) {
+  const base = reason || 'Morphed policy gates this write.';
+  if (decision === 'approval_required') {
+    return `Morphed requires human approval before this write. ${base} ` +
+      `STOP now — do not retry or work around it. A request has been opened in Morphed` +
+      `${hold_token ? ` (hold ${hold_token.slice(0, 12)}…)` : ''}; resume once it is approved.`;
+  }
+  if (decision === 'blocked') {
+    return `Morphed blocked this write. ${base} ` +
+      `STOP — do not retry with a variation. If this is wrong, ask the operator to adjust the policy in Morphed.`;
+  }
+  if (decision === 'modify') {
+    return `Morphed would modify this write to stay within policy. ${base} ` +
+      `Reconsider using the corrected value, or request approval in Morphed.`;
+  }
+  return base;
+}
+
+/**
+ * Build the stdout JSON for a given agent surface + Morphed decision.
+ * @param {'claude_code'|'codex'} surface
+ * @param {object} decision  the /v1/decision response
+ * @param {string} hookEventName  e.g. PreToolUse | PermissionRequest
+ */
+export function buildHookOutput(surface, decision, hookEventName = 'PreToolUse') {
+  const permission = permissionFor(decision.decision);
+  const message = reasonText(decision);
+
+  // Codex PermissionRequest uses the decision.behavior nesting.
+  if (surface === 'codex' && hookEventName === 'PermissionRequest') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: { behavior: permission === 'ask' ? 'deny' : permission, message },
+      },
+    };
+  }
+
+  // Claude Code + Codex PreToolUse share the hookSpecificOutput shape.
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: hookEventName || 'PreToolUse',
+      permissionDecision: permission,
+      permissionDecisionReason: message,
+    },
+  };
+
+  // Claude Code supports `updatedInput` on PreToolUse: for a Morphed `modify`
+  // decision with a corrected state, rewrite the tool input and allow it
+  // (corrected-before) instead of just asking — verified on code.claude.com.
+  if (surface === 'claude_code' && decision.decision === 'modify' && decision.modified_state) {
+    out.hookSpecificOutput.permissionDecision = 'allow';
+    out.hookSpecificOutput.updatedInput = { properties: decision.modified_state };
+    out.hookSpecificOutput.permissionDecisionReason =
+      `Morphed corrected this write to stay within policy: ${decision.reason || ''}`.trim();
+  }
+  return out;
+}
+
+/**
+ * Translate a raw pre-tool payload into a /v1/decision request body.
+ * tool_name + tool_input vary by tool; we extract the most decision-relevant
+ * signal (the changed field + proposed value for HubSpot writes; the command
+ * for Bash) and let the decision service score it.
+ */
+export function toDecisionInput(payload, surface) {
+  const toolName = payload.tool_name || payload.toolName || '';
+  const toolInput = payload.tool_input || payload.toolInput || {};
+  const isHubspot = /hubspot/i.test(toolName);
+
+  // HubSpot MCP write tools carry { objectType, objectId, properties }.
+  if (isHubspot) {
+    const objectType = toolInput.objectType || toolInput.object_type || toolInput.objectTypeId || null;
+    const objectId = toolInput.objectId || toolInput.object_id || toolInput.id || null;
+    const props = toolInput.properties || toolInput.propertiesToUpdate || {};
+    const field = Object.keys(props || {})[0] || toolInput.propertyName || null;
+    const action = /delete|archive/i.test(toolName) ? 'delete' : 'set_property';
+    return {
+      surface, firewall_phase: 'before', object_type: objectType, object_id: objectId, action, field,
+      proposed_state: Object.keys(props || {}).length ? props : (field && toolInput.propertyValue !== undefined ? { [field]: toolInput.propertyValue } : null),
+      actor: surface,
+    };
+  }
+
+  // Bash / raw CLI — catches curl-to-HubSpot and CLI writes. No structured
+  // field, so the decision service evaluates the action/command generically.
+  return {
+    surface,
+    firewall_phase: 'before', // the hook denies before the tool fires
+    object_type: null,
+    object_id: null,
+    action: toolName === 'Bash' || toolName === 'bash' ? 'bash' : toolName,
+    field: null,
+    proposed_state: { command: toolInput.command || toolInput.cmd || null },
+    actor: surface,
+  };
+}
+
+export default { permissionFor, reasonText, buildHookOutput, toDecisionInput };