relay-companion 0.1.48 → 0.1.49

package/bin/relay.js

@@ -8,8 +8,18 @@ import { spawnSync, spawn } from "node:child_process";
 import readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { RelayClient } from "../src/client.js";
-import { writeConfig, readConfig, apiUrl, DEFAULT_API_URL, DEFAULT_WEB_URL } from "../src/config.js";
-import { runTaskDaemon, pollTaskRuntimeOnce } from "../src/task-daemon.js";
+import {
+  COMPANION_MODE_FULL,
+  COMPANION_MODE_MESSAGES_ONLY,
+  DEFAULT_COMPANION_MODE,
+  writeConfig,
+  readConfig,
+  apiUrl,
+  companionModeCliArgs,
+  DEFAULT_API_URL,
+  DEFAULT_WEB_URL,
+} from "../src/config.js";
+import { runOrdinaryRelayDaemon, runTaskDaemon, pollTaskRuntimeOnce } from "../src/task-daemon.js";
 import { runMcpServer } from "../src/mcp.js";
 import { repairDesktopSurfaces, runSetupInstall, runUninstall } from "../src/install.js";
 import { runUpdateOnce } from "../src/auto-update.js";
@@ -37,6 +47,21 @@ function parseFlags(argv) {
   return { flags, positional };
 }
 
+function modeFromFlags(flags) {
+  if (flags["messages-only"] && flags.full) {
+    throw new Error("Choose either --messages-only or --full, not both.");
+  }
+  if (flags["messages-only"]) return COMPANION_MODE_MESSAGES_ONLY;
+  if (flags.full) return COMPANION_MODE_FULL;
+  return DEFAULT_COMPANION_MODE;
+}
+
+function requireTaskFeatures(flags = {}) {
+  if (modeFromFlags(flags) === COMPANION_MODE_MESSAGES_ONLY) {
+    throw new Error("Relay Tasks are disabled in messages-only mode.");
+  }
+}
+
 function companionVersion() {
   try {
     const require = createRequire(import.meta.url);
@@ -115,8 +140,12 @@ function statusAreaReopenText() {
 }
 
 /** Register the Relay tools into Claude Code + Codex and start the receive daemon. */
-async function applyInstall({ requireLiveTools = false, requiredHosts = requiredLiveHosts() } = {}) {
-  const { installed, missing, daemon, pill, activations = [], binStable = true } = await runSetupInstall();
+async function applyInstall({
+  requireLiveTools = false,
+  requiredHosts = requiredLiveHosts(),
+  mode = DEFAULT_COMPANION_MODE,
+} = {}) {
+  const { installed, missing, daemon, pill, activations = [], binStable = true } = await runSetupInstall({ mode });
   if (installed.length) console.log(`Added Relay to ${installed.join(" and ")} on this machine.`);
   if (!binStable) {
     console.log(
@@ -158,12 +187,18 @@ async function applyInstall({ requireLiveTools = false, requiredHosts = required
 
 /** Full setup: pair this device, then install the tools + daemon. */
 async function cmdSetup(flags) {
+  const mode = modeFromFlags(flags);
+  writeConfig({ companionMode: mode });
   await cmdPair(flags, { promptForDefaults: Boolean(flags.interactive) });
   console.log("");
   await applyInstall({
     requireLiveTools: Boolean(flags["require-live-tools"]) || shouldRequireLiveTools(),
     requiredHosts: requiredLiveHosts(),
+    mode,
   });
+  if (mode === COMPANION_MODE_MESSAGES_ONLY) {
+    console.log("Relay is installed in ordinary-messages-only mode; Relay Tasks are not polled or exposed to agents.");
+  }
   const token = setupOpenRelayToken(flags);
   if (token) {
     console.log("");
@@ -185,16 +220,18 @@ async function cmdSetup(flags) {
 }
 
 /** Install the tools + daemon on a device that is already paired. */
-async function cmdInstall() {
+async function cmdInstall(flags = {}) {
   if (!readConfig().deviceToken) {
     throw new Error("This device is not paired yet. Run `relay setup` with a pairing code first.");
   }
-  await applyInstall({ requireLiveTools: shouldRequireLiveTools(), requiredHosts: requiredLiveHosts() });
+  const mode = modeFromFlags(flags);
+  writeConfig({ companionMode: mode });
+  await applyInstall({ requireLiveTools: shouldRequireLiveTools(), requiredHosts: requiredLiveHosts(), mode });
 }
 
 function cmdRepairDesktop(flags = {}) {
   const reload = !flags["no-restart"];
-  const repaired = repairDesktopSurfaces({ reload });
+  const repaired = repairDesktopSurfaces({ reload, mode: modeFromFlags(flags) });
   if (!repaired.ok) {
     const failures = [
       !repaired.daemon?.ok && `daemon: ${repaired.daemon?.reason || "install failed"}`,
@@ -225,7 +262,8 @@ async function cmdWhoami() {
   console.log(`${me.user.name} <${me.user.email}>  (api: ${apiUrl()})`);
 }
 
-async function cmdTasksOnce() {
+async function cmdTasksOnce(flags = {}) {
+  requireTaskFeatures(flags);
   const out = await pollTaskRuntimeOnce({ log: (m) => console.log(`[relay] ${m}`) });
   console.log(
     `Processed ${out.sessions.length} task session(s), ${out.messages.length} message(s), ${out.notifications.length} Relay companion item(s).`,
@@ -265,28 +303,36 @@ function openUrl(url) {
 async function cmdOpen(positional, flags) {
   const log = (m) => process.stderr.write(`[relay] ${m}\n`);
   const host = String(flags.host || flags.in || "claude").toLowerCase();
+  const mode = modeFromFlags(flags);
   if (flags.task) {
+    requireTaskFeatures(flags);
     const result = await openTask({ taskId: String(flags.task), host, log });
     console.log(JSON.stringify(result, null, 2));
     return;
   }
   const id = positional[0] || flags.id;
   if (!id) throw new Error("Usage: relay open <id> --host claude|codex  (or: relay open --task <taskId> --host claude|codex)");
-  const result = await openRelay({ id, host, log });
+  const result = await openRelay({ id, host, log, allowTaskRows: mode === COMPANION_MODE_FULL });
   console.log(JSON.stringify(result, null, 2));
 }
 
 async function cmdOpenNotification(flags) {
+  const mode = modeFromFlags(flags);
+  if (flags.task) requireTaskFeatures(flags);
   let target = flags.url;
   if (!target && flags.task) target = `/app/tasks/${encodeURIComponent(flags.task)}`;
   if (!target && flags.message) target = "/app/relays";
-  target ||= "/app/tasks";
+  target ||= mode === COMPANION_MODE_MESSAGES_ONLY ? "/app/relays" : "/app/tasks";
+  if (mode === COMPANION_MODE_MESSAGES_ONLY && /(^|\/)tasks(?:[/?#]|$)/.test(String(target))) {
+    throw new Error("Relay Tasks are disabled in messages-only mode.");
+  }
   const url = absoluteWebTarget(target);
   const opened = openUrl(url);
   console.log(opened ? `Opened ${url}` : `Open this Relay URL: ${url}`);
 }
 
 async function cmdAnswerQuestion(flags) {
+  requireTaskFeatures(flags);
   const taskId = flags.task || flags.taskId;
   const messageId = flags.message || flags.messageId;
   let answer = flags.answer;
@@ -303,7 +349,7 @@ async function cmdAnswerQuestion(flags) {
 }
 
 /** Launch (or signal) the desktop Relay companion pill and verify it is visible. */
-async function cmdPill() {
+async function cmdPill(flags = {}) {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const overlayMain = path.resolve(here, "../overlay/main.cjs");
   // require("electron") returns the path to the electron binary when resolved under node.
@@ -323,11 +369,15 @@ async function cmdPill() {
   }
   const reopenNonce = `cli-${process.pid}-${randomUUID()}`;
   let spawnError = null;
-  const child = spawn(electronPath, [overlayMain, "--relay-reopen", reopenNonce], {
-    detached: true,
-    stdio: "ignore",
-    env: { ...process.env },
-  });
+  const child = spawn(
+    electronPath,
+    [overlayMain, ...companionModeCliArgs(modeFromFlags(flags)), "--relay-reopen", reopenNonce],
+    {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env },
+    },
+  );
   child.on("error", (error) => {
     spawnError = error;
   });
@@ -356,7 +406,7 @@ async function main() {
     case "pair":
       return cmdPair(flags);
     case "install":
-      return cmdInstall();
+      return cmdInstall(flags);
     case "repair-desktop":
       return cmdRepairDesktop(flags);
     case "uninstall":
@@ -364,7 +414,7 @@ async function main() {
     case "whoami":
       return cmdWhoami();
     case "tasks":
-      return cmdTasksOnce();
+      return cmdTasksOnce(flags);
     case "open":
       return cmdOpen(positional, flags);
     case "open-notification":
@@ -373,37 +423,40 @@ async function main() {
     case "answer":
       return cmdAnswerQuestion(flags);
     case "daemon":
-      return runTaskDaemon({ intervalMs: Number(flags.interval) || 4000 });
+      return modeFromFlags(flags) === COMPANION_MODE_MESSAGES_ONLY
+        ? runOrdinaryRelayDaemon({ intervalMs: Number(flags.interval) || 4000 })
+        : runTaskDaemon({ intervalMs: Number(flags.interval) || 4000 });
     case "pill":
-      return cmdPill();
+      return cmdPill(flags);
     case "mcp":
-      return runMcpServer();
+      return runMcpServer({ mode: modeFromFlags(flags) });
     case "update":
     case "self-update":
-      return runUpdateOnce().then(() => {});
+      return runUpdateOnce({ mode: modeFromFlags(flags) }).then(() => {});
     default:
       console.log(
         [
           "Relay companion",
           "",
           "Usage:",
-          "  relay setup [--code CODE] [--name NAME]               Pair this machine and add Relay to Claude Code + Codex",
+          "  relay setup [--code CODE] [--name NAME] [--messages-only|--full]",
+          "                                                               Pair and install; ordinary messages only by default",
           "  relay version                                         Print the installed Relay companion version",
           "  relay setup --code CODE --open-relay TOKEN --host codex|claude",
           "  relay setup --interactive                             Prompt for API URL and device name during setup",
-          "  relay install                                         Add Relay to your agents (device already paired)",
+          "  relay install [--messages-only|--full]                Add Relay to your agents; --full explicitly enables Relay Tasks",
           "  relay uninstall                                       Remove Relay from your agents and stop the daemon",
-          "  relay repair-desktop [--no-restart]                  Repair Relay.app and background services without changing MCP/account state",
+          "  relay repair-desktop [--no-restart] [--messages-only|--full] Repair Relay.app and background services without changing MCP/account state",
           "  relay pair [--api URL] [--web URL] [--code CODE]      Pair this machine only (no agent install)",
-          "  relay tasks                                           Pull and process task agent runtime once",
+          "  relay tasks --full                                    Pull and process the opt-in Relay Task runtime once",
           "  relay open <id> --host claude|codex                  Materialize a staged Relay row into a native agent session",
-          "  relay open --task <taskId> --host claude|codex       Materialize a Relay task into a native agent session",
+          "  relay open --task <taskId> --host claude|codex --full Materialize an opt-in Relay Task into a native agent session",
           "  relay open-notification [--url PATH] [--task ID]      Open a Relay companion target in the browser",
-          "  relay answer-question --task ID --message ID --answer TEXT",
-          "  relay daemon [--interval MS]                          Run the task runtime daemon",
-          "  relay pill                                            Launch the desktop Relay companion pill",
-          "  relay mcp                                             Run the MCP server (for your agent)",
-          "  relay update                                          Update to the latest published companion and restart",
+          "  relay answer-question --task ID --message ID --answer TEXT --full",
+          "  relay daemon [--interval MS] [--messages-only|--full] Run ordinary receive by default; Tasks require --full",
+          "  relay pill [--messages-only|--full]                   Launch the ordinary pill by default; Tasks require --full",
+          "  relay mcp [--messages-only|--full]                    Run ordinary tools by default; Tasks require --full",
+          "  relay update [--messages-only|--full]                 Update while preserving only the explicitly selected profile",
           "  relay whoami                                          Show the paired account",
         ].join("\n"),
       );

package/overlay/main.cjs

@@ -51,6 +51,11 @@ const {
   showInactiveOnAllSpaces,
   subscribeActiveSpaceChanges,
 } = require("./space-presence.cjs");
+const {
+  COMPANION_MODE_FULL,
+  companionModeFromRuntime,
+  taskFeaturesAllowed,
+} = require("./mode-policy.cjs");
 
 const RELAY_HOME = process.env.RELAY_HOME || process.env.RELAY_COMPANION_HOME || path.join(os.homedir(), ".relay-companion");
 const STATE_PATH = path.join(RELAY_HOME, "state.json");
@@ -245,6 +250,17 @@ function readConfigFile() {
   }
 }
 
+// The Granular-linked user profile is deliberately ordinary-Relay-only. Resolve the
+// mode before creating clients or IPC handlers, and reject invalid persisted/env
+// values instead of silently enabling the dormant Relay Tasks surface.
+const COMPANION_MODE = companionModeFromRuntime({
+  argv: process.argv,
+  env: process.env,
+  config: readConfigFile(),
+});
+const TASK_FEATURES_ALLOWED = taskFeaturesAllowed(COMPANION_MODE);
+const COMPANION_MODE_CLI_ARG = COMPANION_MODE === COMPANION_MODE_FULL ? "--full" : "--messages-only";
+
 function deviceToken() {
   if (process.env.RELAY_DEVICE_TOKEN) return process.env.RELAY_DEVICE_TOKEN;
   return readConfigFile().deviceToken || "";
@@ -279,6 +295,18 @@ function taskWebUrl(taskId) {
   return `${webBase()}/app/tasks/${encodeURIComponent(taskId)}`;
 }
 
+function isRelayTaskWebTarget(pathOrUrl) {
+  const value = String(pathOrUrl || "").trim();
+  if (!value) return false;
+  try {
+    const base = new URL(`${webBase()}/`);
+    const target = new URL(value, base);
+    return target.origin === base.origin && /^\/app\/tasks(?:\/|$)/.test(target.pathname);
+  } catch {
+    return /(^|\/)app\/tasks(?:[/?#]|$)/.test(value);
+  }
+}
+
 // ---- state.json reading (Relay attention rows) ---------------------------
 
 function readStore() {
@@ -335,6 +363,7 @@ function readRelays() {
   return Object.entries(packets)
     .map(([id, p]) => ({ id, ...(p || {}) }))
     .filter((p) => p.direction === "inbound")
+    .filter((p) => TASK_FEATURES_ALLOWED || p.relayNotificationKind === "plain_relay")
     .map((p) => ({
       id: p.id,
       direction: "inbound",
@@ -430,6 +459,10 @@ function ensureSentLoaded() {
 let tasksCache = [];
 let tasksLoadedOnce = null; // a promise that resolves after the first task load
 async function refreshTasks() {
+  if (!TASK_FEATURES_ALLOWED) {
+    tasksCache = [];
+    return tasksCache;
+  }
   try {
     const client = await relayClient();
     const res = await client.listTasks();
@@ -743,6 +776,9 @@ function approvalIdForRow(row) {
 }
 
 async function runMutation(label, fn) {
+  if (!TASK_FEATURES_ALLOWED) {
+    return { ok: false, error: "Relay Tasks are disabled in messages-only mode." };
+  }
   try {
     await fn();
     await refreshTasks();
@@ -1119,6 +1155,10 @@ async function openPacket(packetId, { sent = false } = {}) {
     if (!sent) ackPacket(packetId);
     if (win && !win.isDestroyed()) win.webContents.send("openDone", packetId); // stop the row spinner
   };
+  if (!TASK_FEATURES_ALLOWED && (row?.taskId || isRelayTaskWebTarget(row?.actionUrl))) {
+    console.error("[overlay] refusing to open a Relay Task in messages-only mode:", packetId);
+    return finish();
+  }
   if (process.env.RELAY_OVERLAY_TEST_NO_HOST_OPEN === "1") return finish();
   if (row && row.relayNotificationKind === "connector_reauth") {
     shell
@@ -1139,10 +1179,14 @@ async function openPacket(packetId, { sent = false } = {}) {
       // then keep the row spinner alive while it does post-import title repair.
       env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
     }
-    const child = spawn(process.execPath, [RELAY_CLI, "open", materializationId, "--host", host], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+    const child = spawn(
+      process.execPath,
+      [RELAY_CLI, "open", materializationId, "--host", host, COMPANION_MODE_CLI_ARG],
+      {
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
     let out = "";
     let err = "";
     child.stdout.on("data", (data) => (out += data));
@@ -1204,6 +1248,7 @@ async function openPacket(packetId, { sent = false } = {}) {
 // rail seeded with the task's objective + state + an instruction to call
 // relay_task_status for live detail. The web view is only used if the CLI fails.
 function openTaskDetail(taskId) {
+  if (!TASK_FEATURES_ALLOWED) return;
   if (!taskId) return;
   frontmostBundleId((bundle) => {
     const host = resolveClickHost(bundle);
@@ -1217,10 +1262,14 @@ function openTaskDetail(taskId) {
       // Let the overlay own the actual deep-link launch (see openPacket).
       env.RELAY_IMPORT_CLAUDE_DESKTOP = "0";
     }
-    const child = spawn(process.execPath, [RELAY_CLI, "open", "--task", taskId, "--host", host], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+    const child = spawn(
+      process.execPath,
+      [RELAY_CLI, "open", "--task", taskId, "--host", host, COMPANION_MODE_CLI_ARG],
+      {
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
     let out = "";
     let err = "";
     child.stdout.on("data", (data) => (out += data));
@@ -1271,6 +1320,10 @@ function openTaskDetail(taskId) {
 }
 
 function openUrlTarget(url) {
+  if (!TASK_FEATURES_ALLOWED && isRelayTaskWebTarget(url)) {
+    console.error("[overlay] refusing to open a Relay Task URL in messages-only mode");
+    return;
+  }
   const target = absoluteUrl(url);
   shell.openExternal(target).catch((error) => console.error("[overlay] open failed:", error && error.message));
 }
@@ -1677,6 +1730,9 @@ ipcMain.handle("relay:refreshTasks", async () => {
 // Live task detail for the in-pill task view (GET /v1/tasks/:id, same payload the
 // web detail page renders from). The renderer polls this while the view is open.
 ipcMain.handle("relay:taskStatus", async (_e, taskId) => {
+  if (!TASK_FEATURES_ALLOWED) {
+    return { ok: false, error: "Relay Tasks are disabled in messages-only mode." };
+  }
   if (!taskId) return { ok: false, error: "Missing task id." };
   try {
     const client = await relayClient();

package/overlay/mode-policy.cjs

@@ -0,0 +1,37 @@
+"use strict";
+
+const COMPANION_MODE_FULL = "full";
+const COMPANION_MODE_MESSAGES_ONLY = "messages-only";
+
+function normalizeCompanionMode(value) {
+  const mode = String(value || "").trim();
+  if (mode === COMPANION_MODE_FULL || mode === COMPANION_MODE_MESSAGES_ONLY) return mode;
+  throw new Error(`Unsupported Relay companion mode: ${mode || "(empty)"}`);
+}
+
+function companionModeFromRuntime({ argv = [], env = {}, config = {} } = {}) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const messagesOnly = args.includes("--messages-only");
+  const full = args.includes("--full");
+  if (messagesOnly && full) throw new Error("Choose either --messages-only or --full, not both.");
+  if (messagesOnly) return COMPANION_MODE_MESSAGES_ONLY;
+  if (full) return COMPANION_MODE_FULL;
+
+  // A stored/environmental full value records an old preference but cannot widen
+  // a no-flag launch. Relay Tasks require the explicit --full process argument.
+  const configured = env.RELAY_COMPANION_MODE || config.companionMode;
+  if (configured) normalizeCompanionMode(configured);
+  return COMPANION_MODE_MESSAGES_ONLY;
+}
+
+function taskFeaturesAllowed(mode) {
+  return normalizeCompanionMode(mode) === COMPANION_MODE_FULL;
+}
+
+module.exports = {
+  COMPANION_MODE_FULL,
+  COMPANION_MODE_MESSAGES_ONLY,
+  companionModeFromRuntime,
+  normalizeCompanionMode,
+  taskFeaturesAllowed,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relay-companion",
-  "version": "0.1.48",
-  "description": "Relay companion: connects local coding agents to Relay tasks, approvals, and connector tools.",
+  "version": "0.1.49",
+  "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {
     "relay": "bin/relay.js"

package/src/auto-update.js

@@ -17,6 +17,11 @@ import path from "node:path";
 import fs from "node:fs";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_COMPANION_MODE,
+  companionModeCliArgs,
+  normalizeCompanionMode,
+} from "./config.js";
 
 export const PACKAGE_NAME = "relay-companion";
 const DAEMON_LABEL = "work.relay.companion";
@@ -199,6 +204,7 @@ export function spawnDetachedUpdate({
   spawnImpl = spawn,
   log = () => {},
   ensureDir = true,
+  mode = DEFAULT_COMPANION_MODE,
 } = {}) {
   if (ensureDir) {
     try {
@@ -214,6 +220,8 @@ export function spawnDetachedUpdate({
   const restore = parseVersion(currentVersion) ? currentVersion : "latest";
   const install = managedInstallInfo(packageRoot, { home });
   if (!install) throw new Error(`cannot update unmanaged package root: ${packageRoot}`);
+  const normalizedMode = normalizeCompanionMode(mode);
+  const repairModeArgs = companionModeCliArgs(normalizedMode).map(q).join(" ");
   const runtimeDir = runtimeNpmDir(execPath);
   // Prepend the running runtime's bin dir so `node`/`npm` in the script resolve to the
   // exact toolchain that owns the running install, not whatever a fixed PATH finds.
@@ -285,7 +293,7 @@ export function spawnDetachedUpdate({
     `  if [ "$VERSION_OK" = 1 ] && [ -x "$ELECTRON" ] && [ -f "$PKG/bin/relay.js" ] && grep -q '"version"' "$PKG/package.json" 2>/dev/null; then`,
     // Rebuild version-coupled app/plist paths from the NEW package before restart.
     // --no-restart keeps sequencing here: pill first, daemon (our parent) last.
-    `    if "$NODE" "$PKG/bin/relay.js" repair-desktop --no-restart >> ${LOG} 2>&1; then DESKTOP_OK=1; else echo "[relay-update] $(date) desktop repair FAILED" >> ${LOG} 2>&1; fi`,
+    `    if "$NODE" "$PKG/bin/relay.js" repair-desktop --no-restart${repairModeArgs ? ` ${repairModeArgs}` : ""} >> ${LOG} 2>&1; then DESKTOP_OK=1; else echo "[relay-update] $(date) desktop repair FAILED" >> ${LOG} 2>&1; fi`,
     `  fi`,
     `  if [ "$DESKTOP_OK" = 1 ]; then`,
     `    echo "[relay-update] $(date) install and desktop repair verified; restarting services" >> ${LOG} 2>&1`,
@@ -342,7 +350,9 @@ export function createAutoUpdater({
   // "always idle" so the pure decision logic stays testable without runtime.
   hasActiveWork = () => false,
   log = () => {},
+  mode = DEFAULT_COMPANION_MODE,
 } = {}) {
+  const normalizedMode = normalizeCompanionMode(mode);
   // This is the version of the code loaded in THIS process, not a fresh read of the
   // package.json on every tick. If npm writes a new tree but launchctl restart fails,
   // the old daemon must keep retrying rather than see the new on-disk version and
@@ -380,7 +390,7 @@ export function createAutoUpdater({
     state.updating = true;
     state.updateStartedAt = t;
     try {
-      spawnUpdate({ log, currentVersion: runningVersion, targetVersion: latest, packageRoot });
+      spawnUpdate({ log, currentVersion: runningVersion, targetVersion: latest, packageRoot, mode: normalizedMode });
     } catch (err) {
       state.updating = false;
       log(`auto-update launch failed: ${err && err.message ? err.message : String(err)}`);
@@ -456,8 +466,11 @@ export function createAutoUpdater({
 
 // One-shot for the `relay update` CLI: check once and, if a newer version exists,
 // launch the update. Prints a human-readable line. Bypasses the interval gate.
-export async function runUpdateOnce({ log = (m) => console.log(`[relay] ${m}`) } = {}) {
-  const updater = createAutoUpdater({ checkIntervalMs: 0, log });
+export async function runUpdateOnce({
+  log = (m) => console.log(`[relay] ${m}`),
+  mode = DEFAULT_COMPANION_MODE,
+} = {}) {
+  const updater = createAutoUpdater({ checkIntervalMs: 0, log, mode });
   const result = await updater.tick();
   switch (result.status) {
     case "updating":

package/src/config.js

@@ -4,6 +4,14 @@ import path from "node:path";
 
 export const DEFAULT_API_URL = "https://aia6vj5pgp.us-east-1.awsapprunner.com";
 export const DEFAULT_WEB_URL = "https://sendrelays.com";
+export const COMPANION_MODE_FULL = "full";
+export const COMPANION_MODE_MESSAGES_ONLY = "messages-only";
+export const DEFAULT_COMPANION_MODE = COMPANION_MODE_MESSAGES_ONLY;
+
+export function normalizeCompanionMode(value = DEFAULT_COMPANION_MODE) {
+  if (value === COMPANION_MODE_FULL || value === COMPANION_MODE_MESSAGES_ONLY) return value;
+  throw new Error(`Invalid Relay companion mode: ${String(value)}`);
+}
 
 /**
  * Companion configuration lives in ~/.relay/config.json. It holds the device
@@ -80,6 +88,20 @@ export function currentUser() {
   return readConfig().user || null;
 }
 
+/**
+ * Read the stored profile choice for diagnostics and explicit registration work.
+ * Runtime entry points do not use this value to widen a no-flag launch: Tasks still
+ * require an explicit --full argument on the process being launched.
+ */
+export function companionMode() {
+  const configured = process.env.RELAY_COMPANION_MODE || readConfig().companionMode || DEFAULT_COMPANION_MODE;
+  return normalizeCompanionMode(configured);
+}
+
+export function companionModeCliArgs(mode = DEFAULT_COMPANION_MODE) {
+  return normalizeCompanionMode(mode) === COMPANION_MODE_FULL ? ["--full"] : ["--messages-only"];
+}
+
 /** Durable local runtime ledger for agent task sessions. */
 export function taskLedgerPath() {
   return path.join(configDir(), "task-ledger.json");

package/src/desktop-migration.js

@@ -9,6 +9,7 @@ import {
   relayBinPath,
   stableNodePath,
 } from "./install.js";
+import { DEFAULT_COMPANION_MODE, normalizeCompanionMode } from "./config.js";
 
 const DEFAULT_RETRY_DELAYS_MS = [15_000, 60_000, 5 * 60_000];
 
@@ -52,9 +53,15 @@ function markerSurfacePaths(marker) {
 
 export function desktopMigrationMarkerIsCurrent(
   marker,
-  { version, packageRoot, existsSync = fs.existsSync } = {},
+  { version, packageRoot, mode = DEFAULT_COMPANION_MODE, existsSync = fs.existsSync } = {},
 ) {
-  if (!marker || marker.version !== version || path.resolve(String(marker.packageRoot || "")) !== path.resolve(packageRoot)) {
+  const normalizedMode = normalizeCompanionMode(mode);
+  if (
+    !marker ||
+    marker.version !== version ||
+    marker.mode !== normalizedMode ||
+    path.resolve(String(marker.packageRoot || "")) !== path.resolve(packageRoot)
+  ) {
     return false;
   }
   const surfaces = markerSurfacePaths(marker);
@@ -87,10 +94,10 @@ function writeMarkerAtomic(markerPath, marker) {
  *
  * npm lifecycle scripts are not a reliable migration boundary: recent npm clients
  * can suppress unapproved postinstall hooks. The newly loaded daemon therefore
- * repairs its own desktop surfaces once per package version as well. It writes the
- * daemon plist without reloading it (never unload the process executing this code),
- * then installs/reloads only the pill so Relay.app and KeepAlive become effective
- * immediately.
+ * repairs its own desktop surfaces once per package version and companion mode as
+ * well. It writes the daemon plist without reloading it (never unload the process
+ * executing this code), then installs/reloads only the pill so Relay.app and
+ * KeepAlive become effective immediately.
  */
 export function runDesktopStartupMigration({
   platform = process.platform,
@@ -105,20 +112,28 @@ export function runDesktopStartupMigration({
   installDaemonImpl = installDaemonAutostart,
   installPillImpl = installPillAutostart,
   runCommand,
+  mode = DEFAULT_COMPANION_MODE,
 } = {}) {
   if (platform !== "darwin") return { attempted: false, ok: true, reason: "not-darwin", retryable: false };
   if (!managedInstallInfo(packageRoot, { home: homeDir })) {
     return { attempted: false, ok: true, reason: "unmanaged-install", retryable: false };
   }
   if (!version) return { attempted: false, ok: false, reason: "version-unavailable", retryable: false };
+  const normalizedMode = normalizeCompanionMode(mode);
 
   const markerPath = desktopMigrationMarkerPath({ homeDir, version });
   const marker = readMarkerImpl(markerPath);
-  if (desktopMigrationMarkerIsCurrent(marker, { version, packageRoot, existsSync })) {
+  if (desktopMigrationMarkerIsCurrent(marker, { version, packageRoot, mode: normalizedMode, existsSync })) {
     return { attempted: false, ok: true, reason: "already-current", markerPath, marker, retryable: false };
   }
 
-  const sharedOptions = { platform, homeDir, reload: false, ...(runCommand ? { runCommand } : {}) };
+  const sharedOptions = {
+    platform,
+    homeDir,
+    reload: false,
+    mode: normalizedMode,
+    ...(runCommand ? { runCommand } : {}),
+  };
   let daemon;
   try {
     // Refresh the daemon's on-disk plist first, but NEVER unload/reload the daemon
@@ -175,6 +190,7 @@ export function runDesktopStartupMigration({
 
   const nextMarker = {
     version,
+    mode: normalizedMode,
     packageRoot: path.resolve(packageRoot),
     appPath: pill.appPath,
     pillPlistPath: pill.plistPath,
@@ -200,7 +216,8 @@ export function runDesktopStartupMigration({
 
 /** Run immediately, then retry a bounded number of transient failures on unref'd timers. */
 export function startDesktopStartupMigration({
-  runMigration = () => runDesktopStartupMigration(),
+  mode = DEFAULT_COMPANION_MODE,
+  runMigration = () => runDesktopStartupMigration({ mode }),
   retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
   setTimeoutImpl = setTimeout,
   log = () => {},

package/src/install.js

@@ -5,12 +5,18 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { activateCodexMcp, verifyClaudeMcpRegistration } from "./setup-activation.js";
+import {
+  DEFAULT_COMPANION_MODE,
+  companionModeCliArgs,
+  normalizeCompanionMode,
+} from "./config.js";
 
 // Persistent install of the Relay companion into the user's local agents.
 //
 // After pairing, this registers the Relay MCP server (`relay mcp`) into Claude
 // Code and Codex at user scope, so EVERY interactive session gets the Relay
-// tools + the user's connected provider tools — not just background task runs.
+// ordinary-message tools. The dormant Task/provider surface is registered only
+// when setup was explicitly invoked with --full.
 // It also installs a launchd agent that keeps the receive daemon running.
 
 const DAEMON_LAUNCH_LABEL = "work.relay.companion";
@@ -180,6 +186,7 @@ export function installRelayMacApp({
   overlayMain,
   homeDir = os.homedir(),
   runCommand = run,
+  mode = DEFAULT_COMPANION_MODE,
 } = {}) {
   if (!electronPath || !overlayMain || !fs.existsSync(electronPath) || !fs.existsSync(overlayMain)) {
     return { ok: false, reason: "pill_runtime_missing", electronPath, overlayMain };
@@ -208,6 +215,7 @@ export function installRelayMacApp({
   const logPath = path.join(homeDir, ".relay", "pill.log");
   const pillPlistPath = path.join(homeDir, "Library", "LaunchAgents", `${PILL_LAUNCH_LABEL}.plist`);
   const version = packageVersion(packageRoot);
+  const overlayModeArgs = companionModeCliArgs(mode);
 
   try {
     fs.rmSync(stagingDir, { recursive: true, force: true });
@@ -253,7 +261,7 @@ export function installRelayMacApp({
       "  /bin/sleep 0.1",
       '  i=$((i + 1))',
       "done",
-      `nohup ${shellSingleQuote(electronPath)} ${shellSingleQuote(overlayMain)} --relay-reopen "$nonce" >> ${shellSingleQuote(logPath)} 2>&1 &`,
+      `nohup ${shellSingleQuote(electronPath)} ${shellSingleQuote(overlayMain)}${overlayModeArgs.length ? ` ${overlayModeArgs.map(shellSingleQuote).join(" ")}` : ""} --relay-reopen "$nonce" >> ${shellSingleQuote(logPath)} 2>&1 &`,
       "exit 0",
       "",
     ].join("\n");
@@ -419,7 +427,12 @@ function writeTextAtomic(file, value) {
   fs.renameSync(tmp, file);
 }
 
-export function writeClaudeCodeMcpConfig(bin = relayBinPath(), node = stableNodePath(), configPath = claudeCodeConfigPath()) {
+export function writeClaudeCodeMcpConfig(
+  bin = relayBinPath(),
+  node = stableNodePath(),
+  configPath = claudeCodeConfigPath(),
+  { mode = DEFAULT_COMPANION_MODE } = {},
+) {
   if (!fs.existsSync(configPath)) return { ok: false, reason: "claude_config_missing", configPath };
   try {
     const cfg = readJsonObject(configPath);
@@ -432,7 +445,7 @@ export function writeClaudeCodeMcpConfig(bin = relayBinPath(), node = stableNode
       relay: {
         type: "stdio",
         command: node,
-        args: [bin, "mcp"],
+        args: [bin, "mcp", ...companionModeCliArgs(mode)],
         env: {},
       },
     };
@@ -471,11 +484,15 @@ function tomlQuote(value) {
   return JSON.stringify(String(value));
 }
 
-export function codexRelayMcpTomlSection(bin = relayBinPath(), node = stableNodePath()) {
+export function codexRelayMcpTomlSection(
+  bin = relayBinPath(),
+  node = stableNodePath(),
+  { mode = DEFAULT_COMPANION_MODE } = {},
+) {
   return [
     "[mcp_servers.relay]",
     `command = ${tomlQuote(node)}`,
-    `args = [${[bin, "mcp"].map(tomlQuote).join(", ")}]`,
+    `args = [${[bin, "mcp", ...companionModeCliArgs(mode)].map(tomlQuote).join(", ")}]`,
     "startup_timeout_sec = 30",
     "tool_timeout_sec = 300",
     "",
@@ -512,14 +529,22 @@ export function removeTomlTable(text, tableName) {
   return `${before}${before && after ? "\n\n" : ""}${after}${before || after ? "\n" : ""}`;
 }
 
-export function writeCodexMcpConfig(bin = relayBinPath(), node = stableNodePath(), configPath = codexConfigPath()) {
+export function writeCodexMcpConfig(
+  bin = relayBinPath(),
+  node = stableNodePath(),
+  configPath = codexConfigPath(),
+  { mode = DEFAULT_COMPANION_MODE } = {},
+) {
   const configDir = path.dirname(configPath);
   if (!fs.existsSync(configPath) && !fs.existsSync(configDir)) {
     return { ok: false, reason: "codex_config_missing", configPath };
   }
   try {
     const existing = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
-    writeTextAtomic(configPath, replaceTomlTable(existing, "mcp_servers.relay", codexRelayMcpTomlSection(bin, node)));
+    writeTextAtomic(
+      configPath,
+      replaceTomlTable(existing, "mcp_servers.relay", codexRelayMcpTomlSection(bin, node, { mode })),
+    );
     return { ok: true, method: "config", configPath };
   } catch (error) {
     return {
@@ -600,34 +625,44 @@ export function commandExists(cmd) {
 }
 
 /** Register the Relay MCP into Claude Code at user scope (loads in every session). Idempotent. */
-export function installClaudeCode(bin = relayBinPath(), node = stableNodePath(), { command = "claude" } = {}) {
+export function installClaudeCode(
+  bin = relayBinPath(),
+  node = stableNodePath(),
+  { command = "claude", mode = DEFAULT_COMPANION_MODE } = {},
+) {
+  const modeArgs = companionModeCliArgs(mode);
   let cliResult = null;
   if (commandExists(command)) {
     run(command, ["mcp", "remove", "-s", "user", "relay"]); // ignore if absent
-    cliResult = run(command, ["mcp", "add", "-s", "user", "relay", "--", node, bin, "mcp"]);
+    cliResult = run(command, ["mcp", "add", "-s", "user", "relay", "--", node, bin, "mcp", ...modeArgs]);
     if (cliResult.ok || /already exists/i.test(cliResult.out)) {
       return { ok: true, method: "cli" };
     }
   }
 
-  const configResult = writeClaudeCodeMcpConfig(bin, node);
+  const configResult = writeClaudeCodeMcpConfig(bin, node, claudeCodeConfigPath(), { mode });
   if (configResult.ok) return configResult;
   if (cliResult) return { ok: false, reason: "registration_failed", detail: cliResult.out, configPath: configResult.configPath };
   return { ok: false, reason: "claude_code_not_found", configPath: configResult.configPath };
 }
 
 /** Register the Relay MCP into Codex (loads in every session). Idempotent. */
-export function installCodex(bin = relayBinPath(), node = stableNodePath(), { command = "codex" } = {}) {
+export function installCodex(
+  bin = relayBinPath(),
+  node = stableNodePath(),
+  { command = "codex", mode = DEFAULT_COMPANION_MODE } = {},
+) {
+  const modeArgs = companionModeCliArgs(mode);
   let cliResult = null;
   if (commandExists(command)) {
     run(command, ["mcp", "remove", "relay"]); // ignore if absent
-    cliResult = run(command, ["mcp", "add", "relay", "--", node, bin, "mcp"]);
+    cliResult = run(command, ["mcp", "add", "relay", "--", node, bin, "mcp", ...modeArgs]);
     if (cliResult.ok || /already exists/i.test(cliResult.out)) {
       return { ok: true, method: "cli" };
     }
   }
 
-  const configResult = writeCodexMcpConfig(bin, node);
+  const configResult = writeCodexMcpConfig(bin, node, codexConfigPath(), { mode });
   if (configResult.ok) return configResult;
   if (cliResult) return { ok: false, reason: "registration_failed", detail: cliResult.out, configPath: configResult.configPath };
   return { ok: false, reason: "codex_not_found", configPath: configResult.configPath };
@@ -637,15 +672,23 @@ export function installCodex(bin = relayBinPath(), node = stableNodePath(), { co
 export function installDaemonAutostart(
   bin = relayBinPath(),
   node = stableNodePath(),
-  { platform = process.platform, runCommand = run, reload = true, homeDir = os.homedir() } = {},
+  {
+    platform = process.platform,
+    runCommand = run,
+    reload = true,
+    homeDir = os.homedir(),
+    mode = DEFAULT_COMPANION_MODE,
+  } = {},
 ) {
+  const normalizedMode = normalizeCompanionMode(mode);
+  const daemonArgs = [bin, "daemon", ...companionModeCliArgs(normalizedMode)];
   if (platform === "win32") {
     const logPath = path.join(homeDir, ".relay", "daemon.log");
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     const res = installWindowsLogonTask({
       taskName: WINDOWS_DAEMON_TASK_NAME,
       executable: node,
-      args: [bin, "daemon"],
+      args: daemonArgs,
       logPath,
       runCommand,
     });
@@ -666,8 +709,7 @@ export function installDaemonAutostart(
   <key>ProgramArguments</key>
   <array>
     <string>${plistEscape(node)}</string>
-    <string>${plistEscape(bin)}</string>
-    <string>daemon</string>
+${daemonArgs.map((argument) => `    <string>${plistEscape(argument)}</string>`).join("\n")}
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
@@ -690,13 +732,20 @@ export function installDaemonAutostart(
 /** Install + load a launchd agent that starts the visible Relay pill (macOS). */
 export function installPillAutostart(
   bin = relayBinPath(),
-  { platform = process.platform, runCommand = run, reload = true, homeDir = os.homedir() } = {},
+  {
+    platform = process.platform,
+    runCommand = run,
+    reload = true,
+    homeDir = os.homedir(),
+    mode = DEFAULT_COMPANION_MODE,
+  } = {},
 ) {
   if (platform !== "darwin" && platform !== "win32") return { ok: false, reason: "autostart_unsupported_platform" };
   const packageRoot = packageRootForBin(bin);
   const electron = ensureElectronRuntime(packageRoot, { runCommand });
   const electronPath = electron.electronPath;
   const overlayMain = path.join(packageRoot, "overlay", "main.cjs");
+  const pillArgs = [overlayMain, ...companionModeCliArgs(mode)];
   if (!electron.ok || !electronPath || !fs.existsSync(overlayMain)) {
     return { ok: false, reason: "pill_runtime_missing", electronPath, overlayMain, electron };
   }
@@ -706,7 +755,7 @@ export function installPillAutostart(
     const res = installWindowsLogonTask({
       taskName: WINDOWS_PILL_TASK_NAME,
       executable: electronPath,
-      args: [overlayMain],
+      args: pillArgs,
       logPath,
       runCommand,
     });
@@ -718,7 +767,7 @@ export function installPillAutostart(
   const logPath = path.join(home, ".relay", "pill.log");
   fs.mkdirSync(path.dirname(plistPath), { recursive: true });
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
-  const relayApp = installRelayMacApp({ bin, electronPath, overlayMain, homeDir, runCommand });
+  const relayApp = installRelayMacApp({ bin, electronPath, overlayMain, homeDir, runCommand, mode });
   if (!relayApp.ok) return { ...relayApp, electronPath, overlayMain, logPath };
   const pathEnv = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
   const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -729,7 +778,7 @@ export function installPillAutostart(
   <key>ProgramArguments</key>
   <array>
     <string>${plistEscape(electronPath)}</string>
-    <string>${plistEscape(overlayMain)}</string>
+${pillArgs.map((argument) => `    <string>${plistEscape(argument)}</string>`).join("\n")}
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
@@ -798,7 +847,8 @@ function installWindowsLogonTask({ taskName, executable, args = [], logPath = nu
  * Detect Claude Code + Codex, register the Relay MCP into each present, and
  * start the receive daemon. Returns a summary for the CLI to print.
  */
-export async function runSetupInstall() {
+export async function runSetupInstall({ mode = DEFAULT_COMPANION_MODE } = {}) {
+  const normalizedMode = normalizeCompanionMode(mode);
   const { bin, stable: binStable } = resolveStableBin();
   // Bake the upgrade-surviving node path into the MCP registrations too, not just the
   // daemon plist — otherwise a `brew upgrade node` / `nvm uninstall` deletes the
@@ -808,7 +858,7 @@ export async function runSetupInstall() {
   const installed = [];
   const missing = [];
   const activations = [];
-  const claude = installClaudeCode(bin, node);
+  const claude = installClaudeCode(bin, node, { mode: normalizedMode });
   if (claude.ok) {
     installed.push("Claude Code");
     activations.push(verifyClaudeMcpRegistration({ configPath: claude.configPath }));
@@ -817,7 +867,7 @@ export async function runSetupInstall() {
   } else {
     missing.push("Claude Code (registration failed)");
   }
-  const codex = installCodex(bin, node);
+  const codex = installCodex(bin, node, { mode: normalizedMode });
   if (codex.ok) {
     installed.push("Codex");
     activations.push(await activateCodexMcp());
@@ -826,8 +876,8 @@ export async function runSetupInstall() {
   } else {
     missing.push("Codex (registration failed)");
   }
-  const daemon = installDaemonAutostart(bin);
-  const pill = installPillAutostart(bin);
+  const daemon = installDaemonAutostart(bin, node, { mode: normalizedMode });
+  const pill = installPillAutostart(bin, { mode: normalizedMode });
   return { installed, missing, daemon, pill, activations, binStable };
 }
 
@@ -843,12 +893,14 @@ export function repairDesktopSurfaces({
   runCommand = run,
   reload = true,
   homeDir = os.homedir(),
+  mode = DEFAULT_COMPANION_MODE,
 } = {}) {
-  const pill = installPillAutostart(bin, { platform, runCommand, reload, homeDir });
+  const normalizedMode = normalizeCompanionMode(mode);
+  const pill = installPillAutostart(bin, { platform, runCommand, reload, homeDir, mode: normalizedMode });
   // Reload the daemon last. A repair may be invoked by the updater's detached child;
   // replacing the pill first avoids killing the update-owning daemon before all other
   // desktop surfaces are ready.
-  const daemon = installDaemonAutostart(bin, node, { platform, runCommand, reload, homeDir });
+  const daemon = installDaemonAutostart(bin, node, { platform, runCommand, reload, homeDir, mode: normalizedMode });
   return { ok: Boolean(daemon.ok && pill.ok), daemon, pill };
 }
 

package/src/materializer.js

@@ -89,9 +89,21 @@ function readRowContent(rowState) {
 // snapshotted packet content, and — when the row points at a task — fetch the
 // verified task object via the RelayClient so the per-kind seed is grounded in the
 // real API. Returns a normalized "row" the host writers consume.
-async function resolveRow(id, { log = () => {} } = {}) {
+async function resolveRow(id, { log = () => {}, allowTaskRows = false } = {}) {
   const rowState = getRowState(id);
-  if (!rowState) return resolvePublicOpenToken(id, { log });
+  if (!rowState) {
+    const resolved = await resolvePublicOpenToken(id, { log });
+    if (!allowTaskRows && resolved?.row?.taskId) {
+      throw new Error("Relay Tasks are disabled in messages-only mode.");
+    }
+    return resolved;
+  }
+  // A stale row from a prior full-mode launch must not smuggle Task behavior into
+  // a no-flag/messages-only open. Reject before reading content or calling
+  // GET /v1/tasks/:id; explicit full callers opt in through allowTaskRows.
+  if (!allowTaskRows && rowState.taskId) {
+    throw new Error("Relay Tasks are disabled in messages-only mode.");
+  }
   const content = readRowContent(rowState);
   // The staged content packet carries the same fields under different names
   // (briefingMarkdown/displayTitle/sender). Merge so either source satisfies the
@@ -116,6 +128,9 @@ async function resolveRow(id, { log = () => {} } = {}) {
     delivery: content?.delivery || rowState.delivery || null,
     sender: content?.sender || (rowState.senderName ? { name: rowState.senderName } : null),
   };
+  if (!allowTaskRows && row.taskId) {
+    throw new Error("Relay Tasks are disabled in messages-only mode.");
+  }
 
   // When the row points at a task, fetch the verified task object so the per-kind
   // seed builder can ground the session in the real question / result / objective
@@ -204,10 +219,10 @@ function resolveCwd() {
   return process.env.RELAY_OPEN_CWD || os.homedir();
 }
 
-export async function openRelay({ id, host = "claude", log = () => {} } = {}) {
+export async function openRelay({ id, host = "claude", log = () => {}, allowTaskRows = false } = {}) {
   if (!id) throw new Error("openRelay requires a row id");
   const cleanHost = String(host || "claude").toLowerCase();
-  const { row, rowState } = await resolveRow(id, { log });
+  const { row, rowState } = await resolveRow(id, { log, allowTaskRows });
   return materializeRowInHost({ id, row, rowState, host: cleanHost, log });
 }
 

package/src/mcp.js

@@ -3,12 +3,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { prepareOrdinaryRelayAttachments, prepareTaskMessageAttachments, prepareTaskResult } from "./attachments.js";
 import { RelayClient } from "./client.js";
+import {
+  COMPANION_MODE_FULL,
+  DEFAULT_COMPANION_MODE,
+  COMPANION_MODE_MESSAGES_ONLY,
+  normalizeCompanionMode,
+} from "./config.js";
 
 export const TOOLS = [
   {
     name: "relay_send",
     description:
-      "Send an ordinary Relay message or handoff to another person. Use this for the normal product flow when the human says things like 'send Sven a relay asking how he is doing' or 'relay this context to Jordan'. This is NOT a task and does not create an agent coordination run. If the recipient has Relay, it appears in their Relay companion pill and Relays list; if they do not have Relay, Relay emails them a public link saying the sender sent a relay, with options to open it in Claude or Codex without creating an account. Do not use task-only tools for this ordinary communication path.",
+      "Send an ordinary Relay message or handoff. Use this for the normal product flow when the human says things like 'send Sven a relay asking how he is doing' or 'relay this context to Jordan'. Granular digital employees appear as managed, workspace-labelled contacts; use relay_contacts_search and pass the exact matching contactId so a user with several workspaces reaches the intended employee. That message is authored by this human and wakes their employee; it is NOT a Relay task or deterministic workflow. Never use task-only tools to contact a Granular employee. For other recipients, an on-Relay message appears in their companion and Relays list; an off-Relay recipient receives an email open link.",
     inputSchema: {
       type: "object",
       properties: {
@@ -62,7 +68,7 @@ export const TOOLS = [
   {
     name: "relay_contacts_search",
     description:
-      "Search this human's Relay contact book before sending an ordinary relay. Use it when the human gives a name like 'Sven' and you need the correct person/email. If results are ambiguous, ask the human which contact they meant rather than guessing.",
+      "Search this human's Relay contact book before sending an ordinary relay. For a Granular digital employee, search by the workspace name when known (or 'Granular' to discover the workspace-labelled managed contacts), then pass the exact contactId to relay_send. Use it for human names like 'Sven' too. If several workspaces or people plausibly match, ask which contact they meant rather than guessing.",
     inputSchema: {
       type: "object",
       properties: { query: { type: "string" } },
@@ -444,6 +450,21 @@ export const TOOLS = [
   },
 ];
 
+export const MESSAGE_ONLY_TOOL_NAMES = new Set([
+  "relay_send",
+  "relay_contacts_search",
+  "relay_contact_update",
+  "relay_inbox_list",
+  "relay_acknowledge",
+]);
+
+export function toolsForMode(mode = DEFAULT_COMPANION_MODE) {
+  const normalized = normalizeCompanionMode(mode);
+  return normalized === COMPANION_MODE_MESSAGES_ONLY
+    ? TOOLS.filter((tool) => MESSAGE_ONLY_TOOL_NAMES.has(tool.name))
+    : TOOLS;
+}
+
 function text(obj) {
   return { content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] };
 }
@@ -463,7 +484,11 @@ function relaySendResultForAgent(result) {
   };
 }
 
-export async function handleCall(client, name, args) {
+export async function handleCall(client, name, args, { mode = DEFAULT_COMPANION_MODE } = {}) {
+  const normalizedMode = normalizeCompanionMode(mode);
+  if (normalizedMode === COMPANION_MODE_MESSAGES_ONLY && !MESSAGE_ONLY_TOOL_NAMES.has(name)) {
+    throw new Error(`Tool ${name} is unavailable in the ordinary-messages-only Relay profile`);
+  }
   switch (name) {
     case "relay_send":
       return text(
@@ -637,17 +662,18 @@ export async function handleCall(client, name, args) {
   }
 }
 
-export async function runMcpServer() {
+export async function runMcpServer({ mode = DEFAULT_COMPANION_MODE } = {}) {
+  const normalizedMode = normalizeCompanionMode(mode);
   const client = new RelayClient();
   const server = new Server(
     { name: "relay-companion", version: "0.2.0-agent-protocol" },
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolsForMode(normalizedMode) }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     try {
-      return await handleCall(client, req.params.name, req.params.arguments || {});
+      return await handleCall(client, req.params.name, req.params.arguments || {}, { mode: normalizedMode });
     } catch (err) {
       // Surface the API's validation detail so the calling agent can self-correct
       // instead of guessing what "invalid_request" meant.
@@ -671,8 +697,17 @@ export async function runMcpServer() {
   await server.connect(transport);
 }
 
+export function mcpModeFromArgv(argv = []) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const messagesOnly = args.includes("--messages-only");
+  const full = args.includes("--full");
+  if (messagesOnly && full) throw new Error("Choose either --messages-only or --full, not both.");
+  if (full) return COMPANION_MODE_FULL;
+  return DEFAULT_COMPANION_MODE;
+}
+
 if (import.meta.url === `file://${process.argv[1]}`) {
-  runMcpServer().catch((err) => {
+  runMcpServer({ mode: mcpModeFromArgv(process.argv.slice(2)) }).catch((err) => {
     // eslint-disable-next-line no-console
     console.error(err);
     process.exit(1);

package/src/notifications.js

@@ -46,7 +46,7 @@ function relayCliCommand(args) {
 }
 
 function relayAnswerCommand(taskId, messageId) {
-  return relayCliCommand(["answer-question", "--task", taskId, "--message", messageId, "--answer", "..."]);
+  return relayCliCommand(["answer-question", "--task", taskId, "--message", messageId, "--answer", "...", "--full"]);
 }
 
 function actionForNotification(notification) {

package/src/runtime.js

@@ -5,11 +5,17 @@ import readline from "node:readline";
 import { randomUUID } from "node:crypto";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { configDir, taskLedgerPath } from "./config.js";
+import {
+  COMPANION_MODE_FULL,
+  companionModeCliArgs,
+  configDir,
+  taskLedgerPath,
+} from "./config.js";
 
 const CODEX_APP_SERVER_TIMEOUT_MS = 30_000;
 const codexAppServerConnections = new Map();
 const claudeSdkRuns = new Map();
+const TASK_MCP_MODE_ARGS = companionModeCliArgs(COMPANION_MODE_FULL);
 
 function now() {
   return new Date().toISOString();
@@ -126,7 +132,7 @@ function mcpConfigPath(hostKind, relaySessionId) {
     mcpServers: {
       relay: {
         command: process.execPath,
-        args: [relayBinPath(), "mcp"],
+        args: [relayBinPath(), "mcp", ...TASK_MCP_MODE_ARGS],
         env: {
           RELAY_API_URL: process.env.RELAY_API_URL || "",
           RELAY_DEVICE_TOKEN: process.env.RELAY_DEVICE_TOKEN || "",
@@ -145,7 +151,7 @@ function relayCodexConfigArgs(relaySessionId) {
     "-c",
     `mcp_servers.relay.command=${JSON.stringify(process.execPath)}`,
     "-c",
-    `mcp_servers.relay.args=${JSON.stringify([bin, "mcp"])}`,
+    `mcp_servers.relay.args=${JSON.stringify([bin, "mcp", ...TASK_MCP_MODE_ARGS])}`,
     "-c",
     `mcp_servers.relay.startup_timeout_sec=30`,
     "-c",
@@ -167,7 +173,7 @@ function relayCodexAppServerConfig() {
     mcp_servers: {
       relay: {
         command: process.execPath,
-        args: [relayBinPath(), "mcp"],
+        args: [relayBinPath(), "mcp", ...TASK_MCP_MODE_ARGS],
         env,
         startup_timeout_sec: 30,
         tool_timeout_sec: 300,
@@ -185,7 +191,7 @@ function relayClaudeMcpServers() {
     relay: {
       type: "stdio",
       command: process.execPath,
-      args: [relayBinPath(), "mcp"],
+      args: [relayBinPath(), "mcp", ...TASK_MCP_MODE_ARGS],
       env,
       timeout: 300_000,
       alwaysLoad: true,

package/src/task-daemon.js

@@ -21,6 +21,7 @@ import {
 } from "./notifications.js";
 import { createAutoUpdater } from "./auto-update.js";
 import { startDesktopStartupMigration } from "./desktop-migration.js";
+import { COMPANION_MODE_FULL, COMPANION_MODE_MESSAGES_ONLY } from "./config.js";
 
 function idempotencyKey(prefix) {
   return `${prefix}_${randomUUID()}`;
@@ -219,6 +220,23 @@ async function pollHumanNotifications({ client, ledger, stageCompanionItem, stag
   }
 }
 
+/**
+ * Poll only the ordinary Relay inbox. This is the complete receive loop used by
+ * messages-only installations: it deliberately has no task, task-session,
+ * connector, or task-notification client calls.
+ */
+export async function pollOrdinaryRelayOnce({
+  client = new RelayClient(),
+  log = () => {},
+  stagePlainRelay = defaultStagePlainRelayItem,
+} = {}) {
+  const ledger = readTaskLedger();
+  const ordinaryRelays = await pollPlainInbox({ client, ledger, stagePlainRelay, log });
+  pruneLedger(ledger);
+  writeTaskLedger(ledger);
+  return { ordinaryRelays };
+}
+
 export async function pollTaskRuntimeOnce({
   client = new RelayClient(),
   log = () => {},
@@ -366,6 +384,52 @@ export function startAutoUpdateLoop({
   return { run, timer, stop: () => clearIntervalImpl(timer) };
 }
 
+export async function runOrdinaryRelayDaemon({ intervalMs = 4000 } = {}) {
+  // Keep the messages-only receiver alive through transient staging failures.
+  process.on("uncaughtException", (err) => {
+    // eslint-disable-next-line no-console
+    console.error(`[relay] uncaught exception (continuing): ${err && err.stack ? err.stack : err}`);
+  });
+  process.on("unhandledRejection", (reason) => {
+    // eslint-disable-next-line no-console
+    console.error(`[relay] unhandled rejection (continuing): ${reason && reason.stack ? reason.stack : reason}`);
+  });
+  const log = (m) => console.log(`[relay] ${m}`);
+  startDesktopStartupMigration({ log, mode: COMPANION_MODE_MESSAGES_ONLY });
+  const autoUpdater = createAutoUpdater({
+    log,
+    hasActiveWork: () => false,
+    mode: COMPANION_MODE_MESSAGES_ONLY,
+  });
+  startAutoUpdateLoop({ autoUpdater, log });
+  const client = new RelayClient();
+  let me = null;
+  for (let attempt = 1; !me; attempt += 1) {
+    try {
+      me = await client.me();
+    } catch (err) {
+      const wait = Math.min(60_000, 2_000 * attempt);
+      // eslint-disable-next-line no-console
+      console.error(`[relay] startup me() failed (${err && err.message}); retrying in ${Math.round(wait / 1000)}s`);
+      await new Promise((resolve) => setTimeout(resolve, wait));
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log(`[relay] ordinary-message receiver for ${me.user.email}; polling every ${intervalMs}ms`);
+  for (;;) {
+    try {
+      const result = await pollOrdinaryRelayOnce({ client, log });
+      if (result.ordinaryRelays.length) {
+        log(`processed ${result.ordinaryRelays.length} ordinary relay(s)`);
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(`[relay] ordinary-message receiver error: ${err.message}`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
 export async function runTaskDaemon({ intervalMs = 4000 } = {}) {
   // Last-resort safety net: the daemon is always-on and launchd-restarted, but a
   // restart re-delivers in-flight work and can duplicate agent turns. Keep it alive
@@ -384,8 +448,8 @@ export async function runTaskDaemon({ intervalMs = 4000 } = {}) {
   // Repair Relay.app + launchd surfaces independently of npm postinstall. This is a
   // bounded, per-version migration; it reloads only the pill and never unloads this
   // currently running daemon.
-  startDesktopStartupMigration({ log });
-  const autoUpdater = createAutoUpdater({ log, hasActiveWork: hasActiveTurns });
+  startDesktopStartupMigration({ log, mode: COMPANION_MODE_FULL });
+  const autoUpdater = createAutoUpdater({ log, hasActiveWork: hasActiveTurns, mode: COMPANION_MODE_FULL });
   startAutoUpdateLoop({ autoUpdater, log });
   const client = new RelayClient();
   // Boot resilience: the daemon starts at login, often BEFORE the network is up.
@@ -426,7 +490,11 @@ export async function runTaskDaemon({ intervalMs = 4000 } = {}) {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  runTaskDaemon().catch((err) => {
+  const full = process.argv.includes("--full");
+  const messagesOnly = process.argv.includes("--messages-only");
+  if (full && messagesOnly) throw new Error("Choose either --messages-only or --full, not both.");
+  const runDaemon = full ? runTaskDaemon : runOrdinaryRelayDaemon;
+  runDaemon().catch((err) => {
     // eslint-disable-next-line no-console
     console.error(err);
     process.exit(1);