agent-relay-runner 0.11.4 → 0.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.3"
+    "agent-relay-sdk": "0.2.4"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/hooks.json

@@ -11,6 +11,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/permission-request.sh\"",
+            "timeout": 900
+          }
+        ]
+      }
+    ],
     "PermissionRequest": [
       {
         "hooks": [

package/plugins/claude/monitors/relay-monitor.ts

@@ -1,6 +1,6 @@
 import type { Message } from "agent-relay-sdk";
 import { claudeProviderMessageText } from "../../../src/adapters/claude-delivery";
-import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT } from "../../../src/relay-instructions";
+import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT, workspaceDepsNoteFromEnv } from "../../../src/relay-instructions";
 
 const port = process.env.AGENT_RELAY_RUNNER_PORT;
 if (!port) process.exit(0);
@@ -16,6 +16,11 @@ ws.onmessage = (event) => {
   deliveryCount += 1;
   if (firstDelivery) {
     console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    const wsNote = workspaceDepsNoteFromEnv();
+    if (wsNote) {
+      console.log("");
+      console.log(wsNote);
+    }
     console.log("");
     firstDelivery = false;
   }

package/src/adapter.ts

@@ -89,12 +89,15 @@ export interface TerminalAttachSpec {
   ttlMs?: number;
 }
 
-export type ProviderPermissionDecision = "approve" | "approve-session" | "deny" | "abort";
+export type ProviderPermissionDecision = "approve" | "approve-session" | "deny" | "abort" | "answer";
 
 export interface ProviderPermissionDecisionInput {
   approvalId: string;
   decision: ProviderPermissionDecision;
   reason?: string;
+  // For "answer" decisions (Claude AskUserQuestion): maps each question's text
+  // to the chosen option label(s). Multi-select labels are comma-joined.
+  answers?: Record<string, string>;
 }
 
 export interface ProviderAdapter {

package/src/adapters/codex.ts

@@ -3,6 +3,13 @@ import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { workspaceDepsNoteFromEnv } from "../relay-instructions";
+
+/** Relay context prepended to a Codex agent's first turn: the standard relay
+ * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
+function codexRelayContextBlock(): string {
+  return [RELAY_CONTEXT, workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
+}
 import { prepareCodexProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { CodexAppClient, type ClientEvent } from "./codex-client";
 
@@ -159,7 +166,7 @@ export class CodexAdapter implements ProviderAdapter {
       text,
     ].filter(Boolean).join("\n\n");
     if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
-      input = RELAY_CONTEXT + "\n\n" + input;
+      input = codexRelayContextBlock() + "\n\n" + input;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
     console.error(`[agent-relay] starting Codex initial prompt in thread ${threadId}`);
@@ -171,7 +178,7 @@ export class CodexAdapter implements ProviderAdapter {
     const threadId = await ensureCodexThread(process);
     let text = [codexLaunchContext(process), providerMessageText(messages)].filter(Boolean).join("\n\n");
     if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
-      text = RELAY_CONTEXT + "\n\n" + text;
+      text = codexRelayContextBlock() + "\n\n" + text;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
     console.error(codexDeliveryNotice(messages, threadId));

package/src/control-server.ts

@@ -197,9 +197,25 @@ async function handlePermissionRequest(
   return Response.json(claudePermissionHookResponse(decision, body));
 }
 
-function claudePermissionApprovalView(id: string, body: Record<string, unknown>): Record<string, unknown> {
+export function claudePermissionApprovalView(id: string, body: Record<string, unknown>): Record<string, unknown> {
   const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
   const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  // AskUserQuestion is not a yes/no gate — it asks the user to pick answers.
+  // Surface the structured questions so the dashboard can render a form and
+  // return the selections via an "answer" decision (handled in the hook
+  // response below as a PreToolUse allow + updatedInput).
+  if (toolName === "AskUserQuestion" && Array.isArray(toolInput.questions) && toolInput.questions.length) {
+    const count = toolInput.questions.length;
+    return {
+      id,
+      provider: "claude",
+      kind: "questions",
+      title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
+      body: "",
+      questions: toolInput.questions,
+      choices: [],
+    };
+  }
   const command = typeof toolInput.command === "string" ? toolInput.command : "";
   const description = typeof toolInput.description === "string" ? toolInput.description : "";
   const bodyText = [
@@ -222,7 +238,30 @@ function claudePermissionApprovalView(id: string, body: Record<string, unknown>)
   };
 }
 
-function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
+export function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
+  // AskUserQuestion comes through a PreToolUse hook. The only way to satisfy it
+  // headlessly is permissionDecision "allow" + updatedInput carrying the answers
+  // (echoing back the original questions). A bare "allow" is not sufficient, so
+  // anything that is not a populated answer is treated as a deny.
+  if (body.hook_event_name === "PreToolUse") {
+    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+    if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+          updatedInput: { ...toolInput, answers: decision.answers },
+        },
+      };
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: decision.reason || "Dismissed from Agent Relay dashboard",
+      },
+    };
+  }
   const hookEventName = "PermissionRequest";
   if (decision.decision === "approve" || decision.decision === "approve-session") {
     const suggestions = Array.isArray(body.permission_suggestions) ? body.permission_suggestions : [];

package/src/relay-instructions.ts

@@ -23,3 +23,38 @@ export const CLAUDE_READ_ONLY_RELAY_CONTEXT = `${CLAUDE_RELAY_CONTEXT}
 This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:
 
 agent-relay /reply <messageId> "<your reply>"`;
+
+/**
+ * Provider-agnostic caveat injected into every spawned agent that runs in an
+ * isolated workspace, regardless of which project it is working in. Isolated
+ * workspaces are git worktrees whose node_modules are provisioned by the
+ * orchestrator (see AGENT_RELAY_WORKSPACE_DEPS): symlinked from the main
+ * checkout by default. The agent needs to know this so it doesn't run a clean
+ * install that mutates the shared node_modules. Returns "" when no note applies
+ * (shared workspace, or deps installed fresh / unknown).
+ */
+export function workspaceDepsNote(input: { mode?: string | null; depsMode?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  switch (input.depsMode) {
+    case "symlink":
+      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+    case "none":
+      return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
+    default:
+      return "";
+  }
+}
+
+/** Resolve the workspace deps caveat from the runner/monitor environment.
+ * AGENT_RELAY_WORKSPACE_JSON carries the resolved workspace metadata (mode +
+ * deps) and is the authoritative source. Best-effort: never throws. */
+export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined> = process.env): string {
+  const json = env.AGENT_RELAY_WORKSPACE_JSON;
+  if (!json) return "";
+  try {
+    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string } };
+    return workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null });
+  } catch {
+    return "";
+  }
+}

package/src/runner.ts

@@ -500,13 +500,23 @@ export class AgentRunner {
     const approvalId = typeof params.approvalId === "string" ? params.approvalId : "";
     const decision = typeof params.decision === "string" ? params.decision : "";
     if (!approvalId) throw new Error("approvalId required");
-    if (decision !== "approve" && decision !== "approve-session" && decision !== "deny" && decision !== "abort") {
-      throw new Error("decision must be approve, approve-session, deny, or abort");
+    if (decision !== "approve" && decision !== "approve-session" && decision !== "deny" && decision !== "abort" && decision !== "answer") {
+      throw new Error("decision must be approve, approve-session, deny, abort, or answer");
+    }
+    const answersRaw = params.answers;
+    const answers = answersRaw && typeof answersRaw === "object" && !Array.isArray(answersRaw)
+      ? Object.fromEntries(
+          Object.entries(answersRaw as Record<string, unknown>).filter(([, v]) => typeof v === "string") as [string, string][],
+        )
+      : undefined;
+    if (decision === "answer" && (!answers || Object.keys(answers).length === 0)) {
+      throw new Error("answers required for answer decision");
     }
     const input: ProviderPermissionDecisionInput = {
       approvalId,
       decision: decision as ProviderPermissionDecision,
       ...(typeof params.reason === "string" ? { reason: params.reason } : {}),
+      ...(answers ? { answers } : {}),
     };
     if (this.control?.resolvePermissionDecision(input)) {
       return { approvalId, decision, provider: "claude" };