hilos-agent 0.9.0 → 0.9.2

package/src/claude-permissions.mjs

@@ -0,0 +1,445 @@
+// Claude Code runtime-permission adapter (0777).
+//
+// THE SEAM, live-verified against claude 2.1.233 (never docs-trusted, per 0521):
+// `--permission-prompt-tool mcp__<server>__<tool>` names an MCP tool the CLI
+// calls INSTEAD of showing its own interactive prompt. The flag is undocumented
+// in `claude --help` (a bogus flag errors with "unknown option"; this one is
+// accepted), so it was proven by running it:
+//
+//   • the tool receives `{ tool_name, input, tool_use_id }` — e.g.
+//     `{tool_name:"Bash", input:{command:"touch created.txt", description:…}}`;
+//   • it must answer with ONE text content block holding JSON:
+//     `{"behavior":"allow","updatedInput":{…}}` or
+//     `{"behavior":"deny","message":"…"}`;
+//   • the CLI BLOCKS on that call — a deliberately slow answer held a real run
+//     for 150s and it still executed the tool afterwards, so a card can wait on
+//     a human for minutes, not seconds;
+//   • a deny really stops the tool (the file was never created) and the message
+//     is handed to the model verbatim.
+//
+// This means claude needs NO new transport: the existing argv path (runCli,
+// resume, streaming, activity feed) is untouched, and permissions ride an MCP
+// server the daemon serves on loopback for the life of the run. Also verified:
+// claude accepts an `http`-type server in `--mcp-config` with an Authorization
+// header, so the daemon serves the tool IN-PROCESS — no bridge subprocess, and
+// the run's hilos callbacks are directly in scope.
+//
+// `--mcp-config` ADDS to the user's own servers (only `--strict-mcp-config`
+// would replace them), so gating a run never costs the operator their own MCP
+// setup.
+
+import http from "node:http";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import {
+  DEFAULT_PERMISSION_POLL_MS,
+  DEFAULT_PERMISSION_TIMEOUT_MS,
+  resolveHilosPermissionReply,
+} from "./permission-gate.mjs";
+
+/** The MCP server key and tool name the daemon serves. Together they form the
+ *  `mcp__<server>__<tool>` identifier claude's flag takes. */
+export const CLAUDE_PERMISSION_SERVER = "hilos_permissions";
+export const CLAUDE_PERMISSION_TOOL = "ask";
+export const CLAUDE_PERMISSION_TOOL_ID = `mcp__${CLAUDE_PERMISSION_SERVER}__${CLAUDE_PERMISSION_TOOL}`;
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+/** How long an ask waits for claude's real session id before standing in the
+ *  run's own. Claude's init frame lands in well under a second in practice. */
+const DEFAULT_SESSION_ID_WAIT_MS = 10_000;
+
+/** Tool names whose input names a file rather than a command. */
+const FILE_INPUT_KEYS = ["file_path", "path", "notebook_path"];
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Shape claude's permission-prompt payload into the SAME vendor-neutral request
+ * the opencode/ACP card flow already produces, so the card, its audit row, and
+ * the decision vocabulary are identical across vendors.
+ */
+export function normalizeClaudePermissionRequest(args, { sessionId = "", fallbackId = "0" } = {}) {
+  const toolName = typeof args?.tool_name === "string" ? args.tool_name : "tool";
+  const input = isObject(args?.input) ? args.input : {};
+  const vendorRequestId =
+    typeof args?.tool_use_id === "string" && args.tool_use_id
+      ? args.tool_use_id
+      : `claude_${fallbackId}`;
+  const command = typeof input.command === "string" ? input.command : null;
+  const filePath = FILE_INPUT_KEYS.map((key) => input[key]).find(
+    (value) => typeof value === "string" && value,
+  );
+  const resources = command ? [command] : filePath ? [filePath] : [];
+  // The card's one-line title: the command or file is what a human is actually
+  // deciding about, so it leads; the tool name is the fallback.
+  const title = command || filePath || toolName;
+  return {
+    vendor: "claude_code",
+    vendorRequestId,
+    sessionId: String(sessionId || ""),
+    action: toolName,
+    resources,
+    suggestedSave: undefined,
+    metadata: {
+      title,
+      ...(command ? { command } : {}),
+      ...(filePath ? { path: filePath } : {}),
+      transport: "mcp-permission-prompt",
+    },
+    source: { type: "tool", name: toolName },
+  };
+}
+
+/**
+ * Turn a hilos reply into claude's permission-prompt result.
+ *
+ * "once" and "always" both allow THIS call — the durable card already records
+ * which one a human chose, and claude's own allowlist is deliberately not
+ * widened from here: persisting an always-allow into the CLI's config would put
+ * an approval outside the audited substrate.
+ */
+/**
+ * @param {string} reply
+ * @param {unknown} input
+ * @param {{ outcome?: string, byPolicy?: boolean, policyReason?: string | null }} [opts]
+ */
+export function claudePermissionResult(
+  reply,
+  input,
+  { outcome = "decided", byPolicy = false, policyReason = null } = {},
+) {
+  if (reply === "once" || reply === "always") {
+    return { behavior: "allow", updatedInput: isObject(input) ? input : {} };
+  }
+  // 0813 — a workspace RULE refused this, not a person. Saying "a person
+  // declined" would be false, and it would also waste the one thing a standing
+  // rule can give the model that a one-off rejection cannot: the reason, which
+  // is the difference between a wall and an instruction. Only claude's seam
+  // carries a message at all; ACP and codex get their own bare rejection, so
+  // nothing here may imply the model was told when it was not.
+  //
+  // Provenance and reason are separate inputs because a rule need not carry a
+  // reason: deriving "policy" from "a reason exists" would send a reasonless
+  // rule's refusal back as a person's, which is the precise lie this avoids.
+  const reason = typeof policyReason === "string" ? policyReason.trim() : "";
+  const message =
+    outcome === "timeout"
+      ? "hilos: nobody answered this permission request in time, so it was declined. Don't retry it — say what you needed it for and stop."
+      : outcome === "aborted"
+        ? "hilos: the run was cancelled, so this was declined. Stop here."
+        : byPolicy
+          ? `hilos: your workspace's permission rules do not allow this.${reason ? ` ${reason}` : ""} Don't retry it — work within that rule, or say what you need.`
+          : "hilos: a person in the room declined this. Don't retry it — continue with what you can do without it, or explain what you need.";
+  return { behavior: "deny", message };
+}
+
+/**
+ * Does this run get the claude permission gate?
+ *
+ * The same rule the other vendors use: the workspace must have granted runtime
+ * permissions, and a run explicitly configured to never ask (the `skip` tier's
+ * bypass flags) has nothing to gate — hilos must be the one answering asks, so
+ * a run that answers its own is left exactly as the operator configured it.
+ *
+ * @param {{ vendor?: string, runtimePermissions?: boolean, codeArgs?: string[] }} o
+ */
+export function shouldGateClaudePermissions({ vendor, runtimePermissions, codeArgs = [] }) {
+  if (vendor !== "claude_code" || runtimePermissions !== true) return false;
+  const args = Array.isArray(codeArgs) ? codeArgs : [];
+  if (args.includes("--dangerously-skip-permissions")) return false;
+  // `--permission-mode bypassPermissions` is the same escape hatch by another
+  // spelling, and an operator who already named their own prompt tool owns it.
+  const modeIdx = args.indexOf("--permission-mode");
+  if (modeIdx >= 0 && args[modeIdx + 1] === "bypassPermissions") return false;
+  if (args.includes("--permission-prompt-tool")) return false;
+  return true;
+}
+
+/** The argv the gate appends to a claude code run. */
+export function claudePermissionArgs({ configPath, toolId = CLAUDE_PERMISSION_TOOL_ID }) {
+  return ["--mcp-config", configPath, "--permission-prompt-tool", toolId];
+}
+
+/** The flags to strip when a CLI turns out not to know them (compat retry). */
+export const CLAUDE_PERMISSION_FLAGS = ["--mcp-config", "--permission-prompt-tool"];
+
+/**
+ * Serve the permission tool on loopback for the life of one run.
+ *
+ * Bound to 127.0.0.1 on an ephemeral port with a random bearer token, and the
+ * generated config file is written 0600 and deleted on close — the token never
+ * appears in argv (where any local `ps` would read it).
+ *
+ * @param {{
+ *   requestPermission: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision: (handle: unknown, context: object) => Promise<unknown>,
+ *   sessionId?: string,
+ *   resolveSessionId?: () => string | null | undefined,
+ *   sessionIdWaitMs?: number,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   signal?: AbortSignal,
+ *   log?: { error?: (message: string) => void },
+ *   dir?: string,
+ * }} options
+ * @returns {Promise<{ configPath: string, toolId: string, url: string, port: number,
+ *   args: string[], setSessionId: (value: string) => void, pending: () => number,
+ *   close: () => Promise<void> }>}
+ */
+export async function startClaudePermissionServer({
+  requestPermission,
+  getPermissionDecision,
+  sessionId = "",
+  resolveSessionId,
+  sessionIdWaitMs = DEFAULT_SESSION_ID_WAIT_MS,
+  timeoutMs = DEFAULT_PERMISSION_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_PERMISSION_POLL_MS,
+  signal,
+  log,
+  dir = os.tmpdir(),
+}) {
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    throw new Error("claude permission server requires requestPermission and getPermissionDecision");
+  }
+  const token = randomBytes(24).toString("hex");
+  let seq = 0;
+  let inflight = 0;
+  let currentSessionId = String(sessionId || "");
+  // hilos's server REJECTS a permission request with an empty vendorSessionId,
+  // so a fresh run (no session to resume) must not ask with one — every card
+  // would fail before it existed. This is the run's own correlation id, used
+  // only if claude never tells us its real one.
+  const fallbackSessionId = `hilos-run-${randomBytes(8).toString("hex")}`;
+
+  /**
+   * The session id to stamp on an ask.
+   *
+   * On a fresh run claude only reveals its session id in the init frame of its
+   * stream, which normally lands well before the first tool call — but "well
+   * before" is luck, not a guarantee, so an ask that arrives first WAITS a
+   * bounded moment for the real id rather than racing it. If it never comes
+   * (a server without post_progress runs the CLI unstreamed, so there is no
+   * init frame at all), the run's own id stands in: a card a human can decide
+   * beats an ask that dies as an invalid request.
+   */
+  async function sessionIdForAsk() {
+    const pull = () => {
+      if (currentSessionId) return currentSessionId;
+      try {
+        const value = resolveSessionId?.();
+        if (typeof value === "string" && value) {
+          currentSessionId = value;
+          return value;
+        }
+      } catch {
+        /* a session-id lookup must never break the gate */
+      }
+      return "";
+    };
+    const found = pull();
+    if (found) return found;
+    // Nothing could arrive later (an unstreamed run supplies no resolver at
+    // all), so waiting would only delay a card nobody is going to improve.
+    if (typeof resolveSessionId !== "function") return fallbackSessionId;
+    const deadline = Date.now() + Math.max(0, sessionIdWaitMs);
+    while (Date.now() < deadline) {
+      if (signal?.aborted) break;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const later = pull();
+      if (later) return later;
+    }
+    log?.error?.(
+      `claude permission: no CLI session id yet; asking as ${fallbackSessionId} so the card still reaches the room`,
+    );
+    return fallbackSessionId;
+  }
+
+  const server = http.createServer((req, res) => {
+    if (req.headers.authorization !== `Bearer ${token}`) {
+      res.writeHead(401).end();
+      return;
+    }
+    if (req.method !== "POST") {
+      // No SSE lane: claude probes GET once, accepts the refusal, and uses POST.
+      res.writeHead(405).end();
+      return;
+    }
+    let body = "";
+    let tooBig = false;
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 1_000_000) {
+        tooBig = true;
+        req.destroy();
+      }
+    });
+    req.on("end", () => {
+      if (tooBig) return;
+      void handle(body, res);
+    });
+  });
+
+  async function handle(body, res) {
+    let msg;
+    try {
+      msg = JSON.parse(body);
+    } catch {
+      res.writeHead(400).end();
+      return;
+    }
+    const reply = (result) => {
+      if (res.writableEnded) return;
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result }));
+    };
+    // Notifications carry no id and expect no body.
+    if (msg?.id === undefined) {
+      res.writeHead(202).end();
+      return;
+    }
+    if (msg.method === "initialize") {
+      const requested =
+        typeof msg.params?.protocolVersion === "string" ? msg.params.protocolVersion : null;
+      reply({
+        protocolVersion: requested || PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "hilos-permissions", version: "1.0.0" },
+      });
+      return;
+    }
+    if (msg.method === "tools/list") {
+      reply({
+        tools: [
+          {
+            name: CLAUDE_PERMISSION_TOOL,
+            description:
+              "Ask the people in this hilos room to approve a tool call. Blocks until someone decides.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                tool_name: { type: "string" },
+                input: { type: "object" },
+                tool_use_id: { type: "string" },
+              },
+              required: ["tool_name", "input"],
+            },
+          },
+        ],
+      });
+      return;
+    }
+    if (msg.method === "tools/call") {
+      if (msg.params?.name !== CLAUDE_PERMISSION_TOOL) {
+        reply({
+          content: [{ type: "text", text: JSON.stringify({ behavior: "deny", message: "hilos: unknown tool" }) }],
+          isError: true,
+        });
+        return;
+      }
+      const args = isObject(msg.params?.arguments) ? msg.params.arguments : {};
+      const request = normalizeClaudePermissionRequest(args, {
+        sessionId: await sessionIdForAsk(),
+        fallbackId: String(++seq),
+      });
+      inflight++;
+      let outcome = "transport-error";
+      // Set only when a workspace RULE refused this ask (0813); a person's
+      // rejection leaves these alone and keeps the human wording. Provenance is
+      // tracked apart from the reason because a rule may carry no reason.
+      let byPolicy = false;
+      let policyReason = null;
+      let decisionReply = "reject";
+      try {
+        const resolved = await resolveHilosPermissionReply({
+          request,
+          requestPermission,
+          getPermissionDecision,
+          signal,
+          timeoutMs,
+          pollIntervalMs,
+          log,
+          label: "claude permission",
+        });
+        decisionReply = resolved.reply;
+        outcome = resolved.outcome;
+        byPolicy = resolved.byPolicy === true;
+        policyReason = resolved.policyReason ?? null;
+      } finally {
+        inflight--;
+      }
+      // A rejection is never an MCP error: an isError result makes claude retry
+      // or improvise around the block. A plain deny result is the refusal the
+      // CLI is built to respect.
+      reply({
+        content: [
+          { type: "text", text: JSON.stringify(
+              claudePermissionResult(decisionReply, args.input, {
+                outcome,
+                byPolicy,
+                policyReason,
+              }),
+            ) },
+        ],
+      });
+      return;
+    }
+    reply({});
+  }
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      resolve(undefined);
+    });
+  });
+  const { port } = /** @type {{ port: number }} */ (server.address());
+  const url = `http://127.0.0.1:${port}/mcp`;
+  const configPath = path.join(
+    dir,
+    `hilos-permission-${process.pid}-${randomBytes(6).toString("hex")}.json`,
+  );
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({
+      mcpServers: {
+        [CLAUDE_PERMISSION_SERVER]: { type: "http", url, headers: { Authorization: `Bearer ${token}` } },
+      },
+    }),
+    { mode: 0o600 },
+  );
+
+  return {
+    configPath,
+    toolId: CLAUDE_PERMISSION_TOOL_ID,
+    url,
+    port,
+    args: claudePermissionArgs({ configPath }),
+    /** Let the caller stamp the CLI's real session id onto later cards. */
+    setSessionId(value) {
+      if (typeof value === "string" && value) currentSessionId = value;
+    },
+    pending: () => inflight,
+    async close() {
+      try {
+        fs.unlinkSync(configPath);
+      } catch {
+        /* a leftover temp config must never fail a run */
+      }
+      // Drop keep-alive sockets first: server.close() waits for open
+      // connections, and a CLI that exited without closing its MCP socket
+      // would otherwise hang the run's teardown forever.
+      try {
+        server.closeAllConnections?.();
+      } catch {
+        /* older runtimes simply do not have it */
+      }
+      await new Promise((resolve) => server.close(() => resolve(undefined)));
+    },
+  };
+}

package/src/cli.mjs

@@ -175,6 +175,10 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *   hilos-owned var (HILOS_*) is stripped from it regardless, and `PWD` is pinned
  *   to `cwd` when one is set (0615). Omit to inherit the daemon's environment
  *   minus HILOS_* (the safe default).
+ * @property {() => (void | Promise<void>)} [onPermissionGateDropped] - awaited
+ *   BEFORE the ungated compat retry is spawned when a CLI rejects the 0777
+ *   permission flags (0785), so the caller can warn its room while the run can
+ *   still be stopped. A throw here never fails the run.
  */
 
 /**
@@ -328,6 +332,37 @@ function runCliOnce(opts) {
 // inside runCli (not a wrapper) so every call site, present and future, gets it.
 const UNKNOWN_TRUST_RE = /unknown option '--trust'/;
 
+// Compat retry (0777): the permission gate adds `--permission-prompt-tool` (and
+// the `--mcp-config` that serves it) to claude runs. The flag is real but
+// undocumented on 2.1.233, so a Claude Code old enough not to know it would
+// reject the whole command. Rather than fail a run over a gate the CLI cannot
+// honor, strip BOTH flags (and their values) and retry once — the run then
+// behaves exactly as it did before 0777. It is logged as a lost gate, not
+// silently swallowed: the caller sees the first attempt's stderr in the run.
+//
+// 0785: a daemon console line is not the room. Before the ungated retry is
+// SPAWNED, `onPermissionGateDropped` gives the caller — which owns the channel
+// and the thread — its chance to tell the people watching, so the warning
+// arrives while the run can still be stopped instead of after every ungated
+// command has already executed. The result is also stamped
+// `permissionGateDropped:true` as a backstop for callers with no hook.
+const UNKNOWN_PERMISSION_FLAG_RE =
+  /unknown option '(--permission-prompt-tool|--mcp-config)'/;
+const PERMISSION_GATE_FLAGS = new Set(["--permission-prompt-tool", "--mcp-config"]);
+
+/** Drop each flag AND the value that follows it. */
+function stripFlagPairs(args, flags) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (flags.has(args[i])) {
+      i++; // skip its value
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
 /** @param {RunCliOptions} opts */
 export async function runCli(opts) {
   const first = await runCliOnce(opts);
@@ -340,5 +375,26 @@ export async function runCli(opts) {
   ) {
     return runCliOnce({ ...opts, args: args.filter((a) => a !== "--trust") });
   }
+  if (
+    first.status !== 0 &&
+    !first.aborted &&
+    args.includes("--permission-prompt-tool") &&
+    UNKNOWN_PERMISSION_FLAG_RE.test(first.stderr || "")
+  ) {
+    console.log(
+      "  code → this CLI doesn't support --permission-prompt-tool; retrying WITHOUT the hilos permission gate",
+    );
+    // Warn FIRST, then run. The hook is bounded by its owner; a failure here is
+    // not a reason to fail a run that is about to happen anyway.
+    if (typeof opts?.onPermissionGateDropped === "function") {
+      try {
+        await opts.onPermissionGateDropped();
+      } catch {
+        /* telling the room must never break the run */
+      }
+    }
+    const retried = await runCliOnce({ ...opts, args: stripFlagPairs(args, PERMISSION_GATE_FLAGS) });
+    return { ...retried, permissionGateDropped: true };
+  }
   return first;
 }